MCP Tools Reference

This page provides comprehensive documentation for all 14 MCP tools exposed by the simap-mcp server. Each tool is registered via the Model Context Protocol and enables AI assistants like Claude to interact with the SIMAP.ch public procurement platform.

For detailed architectural information about the server itself, see Architecture. For guidance on implementing new tools, see Adding a New Tool. For API integration details, see SIMAP.ch API Integration.

Overview

The simap-mcp server exposes 14 tools organized into three functional categories:

Category	Tools	Purpose
Tender Operations	search_tenders get_tender_details get_publication_history	Search, retrieve, and track public procurement tenders
Code & Nomenclature	search_cpv_codes, browse_cpv_tree search_bkp_codes, browse_bkp_tree search_npk_codes, browse_npk_tree search_oag_codes, browse_oag_tree list_cantons	Search and navigate Swiss classification systems (CPV, BKP, NPK, OAG)
Organizations	list_institutions search_proc_offices	Query Swiss public entities and procurement offices

All tools follow consistent patterns for multilingual support, parameter validation via Zod, and response formatting. Detailed documentation for each category is available in sub-pages Tender Tools, Code and Nomenclature Tools, and Organization Tools.

Sources: README.md17-32 src/tools/index.ts1-25

Tool-to-Code Mapping

The following diagram bridges the "Natural Language Space" (Tool Names) to the "Code Entity Space" (Files and API Endpoints):

Diagram: Tool Implementation and API Endpoint Mapping

Each tool is registered in src/tools/index.ts and implements a specific handler function that validates inputs via Zod schemas, calls the SIMAP API via SimapClient, and formats the response.

Sources: src/tools/index.ts7-25 CLAUDE.md33-70 CLAUDE.md74-82 src/api/endpoints.ts1-25

Common Patterns

All tools follow standardized patterns for consistency and maintainability.

Parameter Validation

Each tool defines its input schema using zod (bumped to ^4.4.3 in v1.2.4 for improved discriminatedUnion and preprocess handling), which provides runtime type validation. The schema is passed to the MCP SDK's McpServer.tool() registration:

Diagram: Parameter Validation Flow

All parameter validation happens before the tool handler executes. Invalid inputs are rejected immediately with descriptive error messages. Tools export *InputShape, *InputSchema, and *Input types to maintain consistency between registration and testing.

Sources: CLAUDE.md76 src/types/schemas.ts1-20 CHANGELOG.md16

Language Support

All tools that return translated content accept a lang parameter:

Parameter	Type	Values	Default	Description
lang	string	de, fr, it, en	en	Preferred language for response

The server implements a fallback chain for translations via getTranslation() to ensure content is available even if the requested language is missing (requested -> de -> fr -> en -> it).

Sources: CLAUDE.md81 src/utils/translation.ts1-25 src/types/common.ts1-15

Response Format

All tools return plain text content formatted as Markdown. Response structure varies by tool type:

Tool Type	Response Structure
Search Tools	List of results with key details, pagination token (lastItem) if applicable
Detail Tools	Complete structured information about a single entity (e.g., get_tender_details)
Browse Tools	Hierarchical tree display with parent-child relationships (e.g., browse_cpv_tree)
List Tools	Comprehensive list of entities with filtering applied (e.g., list_cantons)

Markdown formatting utilizes formatInlineCode() and escapeInlineCode() (added/improved in v1.2.3) to ensure CommonMark §6.1 compliance and safe rendering in LLM interfaces. formatInlineCode() specifically handles backtick fencing and padding for user input.

Sources: src/utils/formatting.ts1-69 CHANGELOG.md22-33

Tool Execution Flow

The following diagram illustrates the complete execution path for a tool invocation, bridging code entities:

Diagram: Tool Execution Sequence

This sequence is consistent across all 14 tools. Errors are caught and routed through toToolErrorResult() in src/utils/errors.ts to provide typed error feedback to the client.

Sources: src/tools/index.ts1-26 src/api/client.ts1-40 src/utils/errors.ts1-30

Tool Categories

The 14 tools are organized into three functional categories, each documented in detail on dedicated sub-pages:

Tender Tools

Three tools for searching and retrieving public procurement tenders:

• search_tenders - Search with filters (dates, types, cantons, codes).
• get_tender_details - Retrieve full tender information by ID. Supports fullRaw: true (added in v1.2.0) for complete JSON data.
• get_publication_history - Track tender lifecycle and modifications.

For details, see Tender Tools.

Sources: README.md19-20 README.md25 src/tools/search-tenders.ts1-50 src/tools/get-tender-details.ts1-20

Code and Nomenclature Tools

Nine tools for Swiss classification systems, organized as four dual-tool pairs (search + browse) plus canton listing:

• CPV (Common Procurement Vocabulary): search_cpv_codes, browse_cpv_tree
• BKP (Construction Cost Planning): search_bkp_codes, browse_bkp_tree
• NPK (Standardized Positions): search_npk_codes, browse_npk_tree
• OAG (Object Types): search_oag_codes, browse_oag_tree
• Canton Reference: list_cantons

For details, see Code and Nomenclature Tools.

Sources: README.md21-23 README.md27-32 src/tools/codes/index.ts1-20

Organization Tools

Two tools for querying Swiss administrative entities:

• list_institutions - List public institutions that issue tenders.
• search_proc_offices - Search procurement offices by name or institution.

For details, see Organization Tools.

Sources: README.md24 README.md26 src/tools/organizations/index.ts1-15