Contributing

This page provides an overview of how to contribute to the simap-mcp project. It covers the contribution workflow, quality standards, and community guidelines.

For detailed step-by-step instructions on the contribution process, see How to Contribute. For community standards and behavior expectations, see Code of Conduct. For reporting security vulnerabilities, see Security Policy.

---

Contribution Types

The simap-mcp project accepts three types of contributions:

Type	Description	Starting Point
Bug Reports	Issues with existing functionality	GitHub Issues using the bug report template
Feature Proposals	New tools or enhancements	GitHub Issues describing the use case
Code Contributions	Pull requests with implementations	Fork → Branch → PR workflow

All contributions must comply with the Code of Conduct and pass automated quality gates before merging.

Sources: CONTRIBUTING.md7-26

---

Contribution Workflow

The following diagram shows the complete lifecycle of a code contribution, from local development to deployment:

Developer Contribution Pipeline

Sources: CONTRIBUTING.md61-117 CONTRIBUTING.md90-100

---

Quality Gates

All code contributions must pass the following automated checks before merging. The CI workflow executes these checks on every push and pull request. Note that as of v1.3.0, Node.js 20 is no longer supported in the CI matrix.

Quality Check Pipeline

Quality Standards

Check	Tool	Configuration	Purpose
Formatting	Prettier	package.json	Enforce 2-space indent, double quotes, semicolons CONTRIBUTING.md208-213
Linting	ESLint	package.json	TypeScript rules, no any, code quality CONTRIBUTING.md191-195
Type Checking	tsc --noEmit	tsconfig.json	Strict TypeScript validation CONTRIBUTING.md192
Build	tsc	tsconfig.json	Compile to dist/index.js CONTRIBUTING.md50
Testing	Vitest	package.json	Unit tests for all tools and utilities CONTRIBUTING.md58

Sources: CONTRIBUTING.md102-109 CONTRIBUTING.md188-213

---

Code Standards Overview

File and Directory Conventions

When adding new functionality, follow this file organization pattern:

Code Entity Organization

Sources: CONTRIBUTING.md121-178 CONTRIBUTING.md123-129

Naming Conventions

Element	Convention	Example	Location
Files	kebab-case.ts	search-cpv.ts	src/tools/ CONTRIBUTING.md200
Functions	camelCase	registerSearchCpv	All .ts files CONTRIBUTING.md201
Classes	PascalCase	SimapClient	src/api/client.ts CONTRIBUTING.md202
Constants	UPPER_SNAKE_CASE	SIMAP_API_BASE	src/api/endpoints.ts CONTRIBUTING.md203
MCP Tools	snake_case	search_cpv_codes	Tool registration CONTRIBUTING.md204

Sources: CONTRIBUTING.md196-205

TypeScript Requirements

• Strict mode enabled: All code must pass tsc --noEmit with strict checks CONTRIBUTING.md192
• No any type: Use unknown for genuinely unknown types, otherwise provide explicit types CONTRIBUTING.md193
• Explicit parameter types: All public function parameters must have type annotations CONTRIBUTING.md194
• Zod validation: All tool inputs validated with the *InputShape/*InputSchema pattern CONTRIBUTING.md131-151
• Engine Requirement: Node.js >= 22 is required as of v1.3.0 CONTRIBUTING.md31

Sources: CONTRIBUTING.md188-195

Commit Message Format

type(scope): short description

Examples:
 feat(tools): add search_xxx tool
 fix(api): handle timeout errors properly
 docs: update README
 refactor(utils): simplify translation logic
 test: add coverage for browse_cpv_tree
 chore: update dependencies

Valid types: feat, fix, docs, refactor, test, chore CONTRIBUTING.md221

Sources: CONTRIBUTING.md215-228

---

Adding a New Tool

For step-by-step instructions on implementing a new MCP tool, see Adding a New Tool.

The high-level process follows the standardized pattern:

1. Create tool file in the appropriate directory (e.g., src/tools/codes/search-xxx.ts CONTRIBUTING.md123-129).
2. Define Zod symbols: Export xxxInputShape (plain object for registration), xxxInputSchema (wrapped object for validation), and XxxInput (inferred type) CONTRIBUTING.md131-151
3. Implement handler function using simap.get() and toToolErrorResult() for standardized error mapping CONTRIBUTING.md152-169
4. Register tool using server.tool() within a registerXxx function CONTRIBUTING.md171-173
5. Add API endpoint constant to src/api/endpoints.ts CONTRIBUTING.md180-182
6. Write tests in tests/tools/ using the exported xxxInputSchema to ensure schema consistency CONTRIBUTING.md184-186

Sources: CONTRIBUTING.md119-186

---

Community Guidelines

Code of Conduct

The project follows the Contributor Covenant 3.0 Code of Conduct. All participants must:

• Engage kindly and honestly CODE_OF_CONDUCT.md17
• Respect different viewpoints CODE_OF_CONDUCT.md18
• Accept constructive feedback CODE_OF_CONDUCT.md20
• Avoid harassment, character attacks, and discrimination CODE_OF_CONDUCT.md29-31

For complete details, enforcement procedures (Warning through Permanent Ban), and the full text, see Code of Conduct.

Security Policy

Security vulnerabilities should not be reported as public issues SECURITY.md13 Instead, use GitHub's private vulnerability reporting or follow the instructions in the Security Policy.

The project supports the latest 1.x versions SECURITY.md7 and provides specific guidance for production deployments and debug mode. For complete details, see Security Policy.

---

Environment Setup

Prerequisites

• Node.js: 22 or higher (updated in v1.3.0) CONTRIBUTING.md31
• npm: Required for dependency management CONTRIBUTING.md32
• Git: For version control CONTRIBUTING.md33

Sources: CONTRIBUTING.md29-33

Installation Commands

Sources: CONTRIBUTING.md37-44

Available npm Scripts

Script	Command	Purpose
Build	npm run build	Compile TypeScript CONTRIBUTING.md50
Dev	npm run dev	Build and run server CONTRIBUTING.md52
Lint	npm run lint	Check code with ESLint CONTRIBUTING.md53
Format	npm run format	Format code with Prettier CONTRIBUTING.md55
Type Check	npm run typecheck	Validate TypeScript types CONTRIBUTING.md57
Test	npm test	Run all tests with Vitest CONTRIBUTING.md58

Sources: CONTRIBUTING.md46-60

---

Pull Request Checklist

Before submitting a pull request, ensure:

• Code compiles without errors (npm run build) CONTRIBUTING.md107
• All tests pass (npm test) CONTRIBUTING.md108
• Linter passes with no warnings (npm run lint) CONTRIBUTING.md105
• Type checking passes (npm run typecheck) CONTRIBUTING.md106
• Changeset added if the change is user-visible (npx changeset). The changeset-bot will comment on the PR with the current status CONTRIBUTING.md92-98
• Commits are clean and follow the required format CONTRIBUTING.md215-228

Sources: CONTRIBUTING.md90-117 CONTRIBUTING.md215-240

---

Getting Help

• Questions about contributing: Open an issue CONTRIBUTING.md243
• Architecture questions: See Architecture and Project Structure CONTRIBUTING.md244
• Tool implementation: See Adding a New Tool.
• Code standards: See Code Quality and Standards.

Sources: CONTRIBUTING.md241-247