Adding a New Tool

This page provides a step-by-step guide for implementing a new MCP tool in the simap-mcp server. It reflects the updated patterns used in the project, including the *InputShape / *InputSchema / *Input export pattern and standardized error mapping via toToolErrorResult.

Purpose and Scope

This guide walks through the complete process of adding a new tool to the MCP server, from initial file creation to registration and testing. It ensures your tool integrates correctly with the existing architecture and follows project conventions defined in the development workflow CONTRIBUTING.md119-173

Tool Anatomy

Every MCP tool in simap-mcp consists of four essential components:

Component	Purpose	Location
Zod Schema	Input validation and type inference	Tool file
Handler Function	Business logic and API interaction	Tool file
Registration Function	Registers tool with McpServer	Tool file
Test Suite	Validates behavior	tests/tools/

Tool Architecture Overview

Sources: CONTRIBUTING.md131-173 src/tools/codes/search-cpv-codes.ts19-100

Step-by-Step Implementation

Step 1: Choose Location and Create File

Determine the appropriate subdirectory based on tool domain. Files must use kebab-case naming CONTRIBUTING.md196-200

Domain	Directory	Examples
Tender operations	src/tools/	search-tenders.ts
Nomenclature codes	src/tools/codes/	search-cpv-codes.ts
Organizations	src/tools/organizations/	search-proc-offices.ts

Sources: CONTRIBUTING.md121-129 CONTRIBUTING.md196-200

Step 2: Add API Endpoint

If your tool requires a new SIMAP API endpoint, add it to the ENDPOINTS constant in src/api/endpoints.ts CONTRIBUTING.md180-182

Sources: CONTRIBUTING.md139 CONTRIBUTING.md180-182 src/api/endpoints.ts7-31

Step 3: Define Input Schema and Exports

The project uses a specific pattern where three symbols are exported alongside the registration function to ensure type safety and facilitate testing without schema drift CONTRIBUTING.md131-150

Sources: CONTRIBUTING.md142-150 src/tools/codes/search-cpv-codes.ts19-25

Step 4: Implement Handler Function

The handler function receives validated parameters, calls the SIMAP API using the singleton simap client, and returns an MCP-compliant response. Use toToolErrorResult for standardized error handling CONTRIBUTING.md152-168

Sources: CONTRIBUTING.md152-168 src/tools/codes/search-cpv-codes.ts43-88

Step 5: Create Registration Function

Export a registration function that binds the tool to the McpServer. The tool name must be in snake_case CONTRIBUTING.md171-173

Sources: CONTRIBUTING.md171-173 CONTRIBUTING.md204 src/tools/codes/search-cpv-codes.ts93-100

Step 6: Register in Domain Index

Add the import and call in the appropriate index.ts file for the domain or the main tool registry CONTRIBUTING.md176-178

Example for Code Registry:

Sources: CONTRIBUTING.md176-178

Step 7: Write Tests

Tests are mandatory for every new tool CONTRIBUTING.md184-186 Create a test file in tests/tools/ mirroring the source structure.

Required Test Areas:

1. Schema validation: Ensure searchXxxInputSchema accepts valid inputs and rejects invalid ones.
2. Query parameter building: Verify parameters correctly map to API query params.
3. Response formatting: Verify output is correctly formatted for the user.

Sources: CONTRIBUTING.md184-186

Data Flow: From Prompt to API

Natural Language Space to Code Entity Mapping

Sources: src/tools/codes/search-cpv-codes.ts43-88 CONTRIBUTING.md138-155 src/api/endpoints.ts18

Tool Registration Hierarchy

Code Entity Mapping

Sources: CONTRIBUTING.md176-178 src/tools/codes/search-cpv-codes.ts93-100 src/index.ts10-12

Verification Checklist

Check	Command
Code compiles	npm run build
Tests pass	npm test
Linter passes	npm run lint
Type check passes	npm run typecheck
Formatting correct	npm run format

Sources: CONTRIBUTING.md46-59 CONTRIBUTING.md232-240