Development Guide

This guide provides technical guidance for developers working on the simap-mcp codebase. It covers environment setup, development workflows, and key concepts needed to contribute effectively to the project.

For detailed information on specific topics, see:

• Project Structure: Project Structure for directory organization and module boundaries across src/api, src/tools, src/types, src/utils, and tests/.
• Adding a New Tool: Adding a New Tool for a step-by-step guide on implementing new MCP tools using the *InputShape/*InputSchema pattern and toToolErrorResult().
• Code Quality and Standards: Code Quality and Standards for naming conventions (kebab-case files, PascalCase types, snake_case tools), TypeScript strict mode, and linting. Note that Node.js >=22 is now the minimum requirement.
• Testing: Testing for the testing strategy using Vitest, covering schema validation, query building, and response formatting.

Prerequisites

Before beginning development, ensure you have the following installed:

Requirement	Minimum Version	Purpose
Node.js	22.x	Runtime environment (Node 20 reached EOL)
npm	Bundled with Node.js	Package management
Git	Any recent version	Version control

The project is tested on Node.js versions 22 and 24 in CI to ensure compatibility across modern LTS releases.

Sources: CONTRIBUTING.md31-33 CLAUDE.md83-92

Environment Setup

Initial Setup

Clone the repository and install dependencies:

Verify the setup by running the build and test suite:

Fork-Based Development

For external contributors, use a fork-based workflow. Create a feature branch for your changes and ensure you run npm run format and npm run typecheck before committing.

Sources: CONTRIBUTING.md46-58 CLAUDE.md21-31 CONTRIBUTING.md61-82

Development Commands

The project uses npm scripts for all development tasks, defined in package.json.

Command	Purpose
npm run build	Compile TypeScript with tsc
npm start	Run compiled server from dist/index.js
npm run dev	Build and run in one step
npm run lint	Check code style with ESLint
npm run format	Format code with Prettier
npm run typecheck	Run TypeScript type checking (tsc --noEmit)
npm test	Run Vitest test suite

Command Flow Diagram

Sources: CONTRIBUTING.md46-58 CLAUDE.md21-31 CONTRIBUTING.md104-109

Key Development Concepts

Entry Point Flow

The server initialization follows a layered approach from the entry point to tool registration. The McpServer class from the SDK is the core engine.

The server starts at src/index.ts, which invokes startServer() defined in src/server.ts. This function initializes the McpServer and registers tools via the central src/tools/index.ts registry.

Sources: src/index.ts1-5 src/server.ts1-24 src/tools/index.ts1-16 CLAUDE.md34-45

Tool Implementation Pattern

All MCP tools follow a consistent implementation pattern using Zod for validation and a standard handler signature.

1. Define Schema: Use Zod to define input parameters (e.g., searchXxxInputShape). CONTRIBUTING.md143-146
2. Implement Handler: An async function that uses the SimapClient (singleton simap). CONTRIBUTING.md152-169
3. Register: Export a function (e.g., registerSearchXxx) that calls server.tool(). CONTRIBUTING.md171-173

Data Flow Sequence

Sources: src/tools/index.ts1-16 CLAUDE.md74-82 CONTRIBUTING.md131-174

API Client Architecture

The SimapClient in src/api/client.ts is a singleton exported as simap. It centralizes:

• Base URL: Uses SIMAP_API_BASE for all requests. CLAUDE.md89
• Endpoints: Managed as constants in src/api/endpoints.ts. CLAUDE.md42
• Rate Limiting: Uses a SlidingWindowRateLimiter to manage request frequency. CLAUDE.md43
• Error Handling: Standardizes response validation and error messages using toToolErrorResult. CLAUDE.md67

Sources: CLAUDE.md74-80 CONTRIBUTING.md138-140 src/api/endpoints.ts1-42

Development Workflow

Standard Cycle

1. Branch: Create a feature branch. CONTRIBUTING.md74-82
2. Implement: Add tool logic in src/tools/ (following kebab-case) and register in the appropriate index.ts. CONTRIBUTING.md119-182
3. Verify: Run npm run lint, npm run typecheck, and npm test. CONTRIBUTING.md104-109
4. PR: Submit a Pull Request following Conventional Commits. CLAUDE.md91-92
5. Changesets: Add a changeset for user-visible changes with npx changeset. CLAUDE.md109-112 CONTRIBUTING.md90-98

Code Conventions

• Files: kebab-case (search-tenders.ts) CLAUDE.md85
• Functions: camelCase (registerSearchTenders) CLAUDE.md86
• Types: PascalCase (ProjectSearchEntry) CLAUDE.md87
• MCP Tools: snake_case (search_tenders) CLAUDE.md88
• Constants: UPPER_SNAKE (SIMAP_API_BASE) CLAUDE.md89

Sources: CLAUDE.md83-92 CONTRIBUTING.md196-214

Local Testing with Claude Desktop

To test the server locally with Claude Desktop:

1. Build the project: npm run build
2. Add the configuration to your Claude Desktop settings (typically ~/.claude/settings.json or equivalent):

3. Restart Claude Desktop.

Sources: CLAUDE.md21-23 CONTRIBUTING.md50-51