How to Contribute

This document explains the contribution workflow for the simap-mcp project, including how to report issues, propose features, and submit code changes. For detailed information about code structure and standards, see Project Structure and Code Quality and Standards For adding new tools specifically, see Adding a New Tool

Contribution Types

The project welcomes three types of contributions:

Reporting Bugs

Bug reports help improve stability and user experience. Before reporting:

1. Check that the bug hasn't already been reported in the Issues [CONTRIBUTING.md9].
2. Create a new issue using the Bug report template [.github/ISSUE_TEMPLATE/bug_report.md1-6].
3. Include required information:
   • Clear description of the problem [.github/ISSUE_TEMPLATE/bug_report.md8-10].
   • Steps to reproduce [.github/ISSUE_TEMPLATE/bug_report.md12-16].
   • Expected vs. actual behavior [.github/ISSUE_TEMPLATE/bug_report.md18-24].
   • Environment details: Node.js version, OS, and MCP client (e.g., Claude Code, Claude Desktop) [.github/ISSUE_TEMPLATE/bug_report.md26-30].

Sources: CONTRIBUTING.md7-14 .github/ISSUE_TEMPLATE/bug_report.md1-35

Proposing Features

Feature requests should describe the use case and relevant SIMAP API endpoints:

1. Create an issue describing the use case [CONTRIBUTING.md18].
2. Use the Feature request template [.github/ISSUE_TEMPLATE/feature_request.md1-6].
3. Mention the relevant simap.ch API endpoint if applicable (e.g., /codes/v1/cpv/search) [.github/ISSUE_TEMPLATE/feature_request.md16-20].
4. Provide a proposed implementation idea if possible [.github/ISSUE_TEMPLATE/feature_request.md22-24].

Sources: CONTRIBUTING.md16-19 .github/ISSUE_TEMPLATE/feature_request.md1-29

Contributing Code

Code contributions follow a structured workflow:

1. Choose an existing issue or create one [CONTRIBUTING.md23].
2. Comment on the issue to indicate you're working on it [CONTRIBUTING.md24].
3. Follow the development workflow described below [CONTRIBUTING.md25].

Sources: CONTRIBUTING.md21-25

Prerequisites and Environment Setup

Required Tools

Tool	Minimum Version	Purpose
Node.js	22+	Runtime and build tooling [CONTRIBUTING.md31]
npm	Latest	Package management [CONTRIBUTING.md32]
Git	Latest	Version control [CONTRIBUTING.md33]

Note: As of v1.3.0, Node.js >= 22 is the minimum engine requirement [CONTRIBUTING.md31].

Sources: CONTRIBUTING.md29-33

Initial Setup

Clone and verify the development environment:

This sequence validates that all tooling works correctly before starting development [CONTRIBUTING.md37-44].

Sources: CONTRIBUTING.md37-44

Available NPM Scripts

Script	Command	Description
Build	npm run build	Compile TypeScript [CONTRIBUTING.md50]
Start	npm start	Run the built server [CONTRIBUTING.md51]
Development	npm run dev	Build and run server [CONTRIBUTING.md52]
Linting	npm run lint	Check code with ESLint [CONTRIBUTING.md53]
Auto-fix	npm run lint:fix	Auto-fix ESLint issues [CONTRIBUTING.md54]
Formatting	npm run format	Format with Prettier [CONTRIBUTING.md55]
Type Check	npm run typecheck	TypeScript validation [CONTRIBUTING.md57]
Test	npm test	Run Vitest test suite [CONTRIBUTING.md58]
Test Watch	npm run test:watch	Run tests in watch mode [CONTRIBUTING.md59]

Sources: CONTRIBUTING.md46-60

Development Workflow

The contribution process follows a fork-based workflow with quality gates and version management via changesets.

Workflow Diagram

Sources: CONTRIBUTING.md61-117

Step 1: Fork and Clone

Fork the repository via GitHub UI, then clone locally:

The upstream remote allows pulling updates from the main repository [CONTRIBUTING.md69-72].

Sources: CONTRIBUTING.md63-72

Step 2: Create a Feature Branch

Always branch from the latest main:

Branch naming conventions:

• feature/*: New functionality or tools [CONTRIBUTING.md79]
• fix/*: Bug fixes [CONTRIBUTING.md81]

Sources: CONTRIBUTING.md74-82

Step 3: Develop

Follow the implementation pattern for new tools:

1. Create the Tool File: Use the appropriate directory (e.g., src/tools/codes/ or src/tools/organizations/) [CONTRIBUTING.md123-129].
2. Follow the Tool Pattern: Export the InputShape (consumed by server.tool()), InputSchema (for tests), and Input type [CONTRIBUTING.md143-150].
3. Implement Handler: Use simap.get() and handle errors with toToolErrorResult() [CONTRIBUTING.md152-168].
4. Register Tool: Call server.tool() in the register* function and export it [CONTRIBUTING.md171-173].
5. Add Endpoint: Update src/api/endpoints.ts [CONTRIBUTING.md180-182].
6. Write Tests: Create matching test file in tests/tools/ [CONTRIBUTING.md184-186].

Sources: CONTRIBUTING.md119-186

Step 4: Changesets (v1.2.2+)

Changesets are now opt-in. If your change is user-visible (new tool, behavior change, bug fix, or public documentation update), run:

Pick the appropriate version bump (patch, minor, or major) and write a summary [.changeset/README.md11-14]. Lead with the affected symbol/file in backticks [.changeset/README.md14]. Internal changes like refactors, CI tweaks, or test updates do not require a changeset [CONTRIBUTING.md98]. The changeset-bot will comment on every PR with the current status [.changeset/README.md3].

Sources: CONTRIBUTING.md90-100 .changeset/README.md1-28

Step 5: Verify Before Pushing

Run all quality checks locally before pushing:

These commands mirror the CI pipeline checks [CONTRIBUTING.md104-109].

Sources: CONTRIBUTING.md102-109

Step 6: Push and Open Pull Request

Open a Pull Request via GitHub UI. Use the PR template provided [CONTRIBUTING.md111-117].

Sources: CONTRIBUTING.md111-117 .github/PULL_REQUEST_TEMPLATE.md1-33

Commit Message Format

Commits follow the Conventional Commits pattern for clarity [CONTRIBUTING.md215-219].

Format Structure

type(scope): short description

Commit Types

Type	Purpose	Example
feat	New feature or tool	feat(tools): add search_xxx tool [CONTRIBUTING.md225]
fix	Bug fix	fix(api): handle timeout errors properly [CONTRIBUTING.md226]
docs	Documentation changes	docs: update README [CONTRIBUTING.md227]
refactor	Code restructuring	refactor(api): simplify client [CONTRIBUTING.md221]
test	Test additions	test(tools): add search tests [CONTRIBUTING.md221]
chore	Build/tooling	chore: update dependencies [CONTRIBUTING.md221]

Sources: CONTRIBUTING.md215-228

Pull Request Process

PR Template Usage

The template at .github/PULL_REQUEST_TEMPLATE.md1-33 requires:

1. Description: What the PR accomplishes [.github/PULL_REQUEST_TEMPLATE.md1-4].
2. Related Issue: Reference via Fixes # [.github/PULL_REQUEST_TEMPLATE.md5-8].
3. Type of Change: Bug fix, new feature, enhancement, docs, or refactoring [.github/PULL_REQUEST_TEMPLATE.md9-16].
4. Checklist: Compilation, linting, formatting, tests, and changeset status [.github/PULL_REQUEST_TEMPLATE.md17-26].

Pre-Submission Checklist

Before requesting review, verify:

• Code compiles: npm run build succeeds [CONTRIBUTING.md234].
• Linter passes: npm run lint reports no errors [CONTRIBUTING.md236].
• Tests pass: npm test succeeds [CONTRIBUTING.md235].
• Changeset added if user-visible [CONTRIBUTING.md237].
• Documentation updated if necessary [CONTRIBUTING.md238].

Sources: CONTRIBUTING.md230-240 .github/PULL_REQUEST_TEMPLATE.md1-33

Code Standards Summary

Naming Conventions

Element	Convention	Example
Files	kebab-case	search-cpv.ts [CONTRIBUTING.md200]
Functions	camelCase	registerSearchCpv [CONTRIBUTING.md201]
Classes	PascalCase	SimapClient [CONTRIBUTING.md202]
Constants	UPPER_SNAKE	SIMAP_API_BASE [CONTRIBUTING.md203]
MCP Tools	snake_case	search_cpv_codes [CONTRIBUTING.md204]

Formatting Rules

The project enforces strict formatting:

• 2 spaces indentation [CONTRIBUTING.md208]
• Semicolons required [CONTRIBUTING.md209]
• Double quotes [CONTRIBUTING.md210]
• Trailing comma (ES5) [CONTRIBUTING.md211]

Run npm run format before committing to ensure compliance [CONTRIBUTING.md213].

Sources: CONTRIBUTING.md188-214

Tool Implementation Logic

When contributing a new tool, the implementation must bridge natural language requirements to specific code entities.

Tool Registration Flow

This diagram maps system components to specific code entities used during tool development.

Data Flow Mapping

The following diagram bridges the Natural Language request from an MCP client to the internal code execution flow.

Sources: CONTRIBUTING.md131-174 src/api/endpoints.ts5-31 .github/PULL_REQUEST_TEMPLATE.md1-33