Tool Architecture

This document explains the structure, organization, and registration of the 14 MCP tools exposed by the simap-mcp server. It covers tool categorization by domain, the registration pattern, and the anatomy of individual tool implementations using the McpServer SDK.

Tool Inventory

The simap-mcp server exposes 14 tools organized into three functional domains.

Domain	Tool Name	Description	Registration Function
Core Tenders	search_tenders	Search tenders with filters	registerSearchTenders
get_tender_details	Get full details of a tender	registerGetTenderDetails
Nomenclature Codes	search_cpv_codes	Search CPV codes (EU procurement vocabulary)	registerSearchCpvCodes
browse_cpv_tree	Navigate CPV code hierarchy	registerBrowseCpvTree
search_bkp_codes	Search BKP codes (construction)	registerSearchBkpCodes
browse_bkp_tree	Navigate BKP code hierarchy	registerBrowseBkpTree
search_npk_codes	Search NPK codes (standardized positions)	registerSearchNpkCodes
browse_npk_tree	Navigate NPK code hierarchy	registerBrowseNpkTree
search_oag_codes	Search OAG codes (object types)	registerSearchOagCodes
browse_oag_tree	Navigate OAG code hierarchy	registerBrowseOagTree
list_cantons	List all Swiss cantons	registerListCantons
Organizations	list_institutions	List public institutions	registerListInstitutions
search_proc_offices	Search procurement offices	registerSearchProcOffices
get_publication_history	Get publication history for a project	registerGetPublicationHistory

Sources: src/tools/index.ts7-10 src/tools/index.ts17-24 CLAUDE.md7-8

Domain Organization

Registration Hierarchy

The server uses a hierarchical registration pattern where the root registerTools function delegates to domain-specific registration functions.

Title: Tool Registration Hierarchy

Sources: src/tools/index.ts15-25 src/tools/index.ts7-10 src/tools/codes/index.ts19-32 src/tools/organizations/index.ts13-20

Domain Categories

Core Tender Tools

Located directly in src/tools/, these provide the primary workflow for discovering and viewing procurement opportunities:

• search_tenders: Entry point for tender discovery with extensive filtering. src/tools/index.ts17
• get_tender_details: Deep-dive into specific tender details, including support for fullRaw output for LLM analysis. src/tools/index.ts18

Nomenclature Code Tools (src/tools/codes/)

Nine tools organized around Swiss classification systems. These are registered via registerCodeTools in src/tools/codes/index.ts.

• CPV (Common Procurement Vocabulary): EU-wide classification. src/tools/codes/index.ts21
• BKP (Baukostenplan): Swiss construction cost planning. src/tools/codes/index.ts25
• NPK (Normierte Positionsbezeichnungen): Standardized descriptions. src/tools/codes/index.ts26
• OAG (Objektartengruppen): Object type groups. src/tools/codes/index.ts27
• Cantons: Swiss regional codes. src/tools/codes/index.ts22

Organization Tools (src/tools/organizations/)

Three tools for working with contracting entities, registered via registerOrganizationTools in src/tools/organizations/index.ts.

• list_institutions: Public institutions. src/tools/organizations/index.ts15
• search_proc_offices: Procurement offices. src/tools/organizations/index.ts19
• get_publication_history: Project history. src/tools/organizations/index.ts18

Sources: src/tools/index.ts7-10 src/tools/index.ts15-25 CLAUDE.md49-58

Tool Implementation Pattern

Code Entity to MCP Mapping

Each tool is implemented in its own file and follows a standard pattern to bridge TypeScript logic to the MCP McpServer.tool() registration.

Title: Bridge between MCP Protocol and Code Implementation

Sources: CLAUDE.md76-78 src/tools/index.ts15-25

Standard Tool Structure

Each tool file follows a strict convention to maintain consistency and testability:

1. Input Shape: An exported *InputShape object containing raw Zod field definitions. This is passed directly to the third argument of server.tool(). CONTRIBUTING.md143-146
2. Input Schema: An exported *InputSchema (defined as z.object(*InputShape)) used for unit testing to avoid drift between registration and tests. CONTRIBUTING.md149
3. Input Type: An exported *Input type inferred from the schema. CONTRIBUTING.md150
4. Handler: An async function that receives the validated parameters, interacts with the SimapClient (singleton simap), and returns the tool result. Errors are routed through toToolErrorResult(). CONTRIBUTING.md152-169
5. Registration: A function (e.g., registerSearchTenders(server: McpServer)) that calls server.tool(). CONTRIBUTING.md171-174

Sources: CLAUDE.md76-78 CONTRIBUTING.md131-174

Registration Logic

McpServer.tool() Usage

The McpServer.tool() method is the core registration mechanism from @modelcontextprotocol/sdk. It takes primary arguments including:

1. Name: The snake_case string identifying the tool to the MCP client (e.g., search_tenders). CLAUDE.md88
2. Description: A string explaining the tool's purpose to the LLM. CONTRIBUTING.md172
3. Schema: The Zod shape defining parameters (*InputShape). CONTRIBUTING.md172
4. Callback: The logic to execute when the tool is called (handler). CONTRIBUTING.md172

Sources: CLAUDE.md76-78 src/tools/index.ts15-25 CONTRIBUTING.md171-174

Registration Entry Point

The root registerTools function in src/tools/index.ts acts as the entry point for all tool registrations, ensuring modularity by delegating to domain-specific files.

Sources: src/tools/index.ts15-25

Domain Indexers

Domain indexers group related registrations to keep the root registerTools clean and maintainable.

Title: Domain Registration Pattern

Sources: src/tools/index.ts21-24 src/tools/codes/index.ts19-32 src/tools/organizations/index.ts13-20