Glossary

This page defines codebase-specific terms, jargon, and domain concepts used in the simap-mcp project. It serves as a technical reference for onboarding engineers to understand the mapping between the Swiss public procurement domain and the implementation details in the code.

Core Concepts

MCP (Model Context Protocol)

The architectural foundation of this project. It allows AI models (like Claude) to use local or remote tools via a standardized JSON-RPC based protocol CLAUDE.md7-8

• McpServer: The main class from @modelcontextprotocol/sdk that manages tool registration and request handling CONTRIBUTING.md136
• StdioServerTransport: The communication layer that enables the server to talk to the client via stdin and stdout CLAUDE.md38
• registerTools: A pattern used to modularize tool registration. The McpServer instance is passed to registration functions which call server.tool() CONTRIBUTING.md171-172

simap.ch (Système d'information sur les marchés publics en Suisse)

The official platform for public procurement in Switzerland. This MCP server acts as a wrapper around the simap.ch public API CLAUDE.md7-8

• SimapClient: A specialized HTTP client (singleton simap) that wraps fetch, handles URL building, timeouts, and Zod response validation src/api/client.ts32-101
• SIMAP_API_BASE: The base URL for API requests src/api/client.ts6
• SimapApiError: A custom error class used to wrap non-2xx HTTP responses from the API, including the status code and endpoint src/types/api.ts7

Nomenclature Systems

Public procurement uses several standardized classification systems to categorize what is being bought. The codebase implements search and tree-browsing tools for four major systems:

Term	Full Name	Domain	Code Reference
CPV	Common Procurement Vocabulary	EU-standardized goods/services	CLAUDE.md52
BKP	Baukostenplan	Swiss construction costs	CLAUDE.md52
NPK	Normpositionen-Katalog	Standardized construction items	CLAUDE.md52
OAG	Object types	Specific procurement objects	CLAUDE.md52
Canton	Swiss Canton	Sub-national administrative division	src/tools/codes/list-cantons.ts1-10

Sources: CLAUDE.md49-58 src/api/client.ts6-7 src/types/common.ts1-27

Domain Mapping Diagram

The following diagram illustrates how natural language concepts from the Swiss procurement domain map to specific TypeScript entities and code structures.

Domain to Code Entity Mapping

Sources: CLAUDE.md44-58 src/utils/formatting.ts7-10 src/types/common.ts1-27

Technical Terms & Implementation Details

Rate Limiting

To prevent overwhelming the simap API and avoid 429 errors, the server implements a queuing mechanism.

• SlidingWindowRateLimiter: A FIFO-based limiter that ensures requests are throttled according to the window src/api/rate-limiter.ts43
• acquire(): The method called by SimapClient before every request to wait for an available slot src/api/client.ts48

Translation & Fallback Chain

simap data is inherently multilingual (German, French, Italian, and English). The codebase uses a specific fallback logic to ensure the AI always receives text even if the preferred language is missing.

• Translation Interface: Defines optional keys for de, fr, it, and en src/types/common.ts8-13
• Language Type: Union of supported language codes: "de" | "fr" | "it" | "en" src/types/common.ts18
• getTranslation(): A utility function that implements the fallback chain: Requested Lang -> de -> fr -> en -> it src/utils/translation.ts15-21

Project and Publication Structure

The simap API distinguishes between the overall procurement effort and specific notices.

• Tender: Often used interchangeably with "Project" in the tool layer, represented by ProjectSearchEntry src/utils/formatting.ts7
• Publication: A specific notice (tender, award, etc.) within a project src/utils/formatting.ts158-161
• Lot: A sub-division of a tender. The lotTitle in LotEntrySchema is marked as .nullish() to handle API responses where titles are missing CHANGELOG.md58-59
• fullRaw: A boolean parameter in get_tender_details that, when true, appends the unmodified JSON response to the Markdown output CHANGELOG.md123-124
• zurichTodayDate: A utility (used in buildTenderSearchQuery) that defaults publicationFrom to the current date in the Europe/Zurich timezone src/tools/search-tenders-params.ts90-97

Formatting & Security

• formatInlineCode: Wraps user input in a CommonMark-safe inline code span using dynamic backtick fences to handle backticks within the content src/utils/formatting.ts54-63
• escapeInlineCode: Escapes backslashes and backticks for use in Markdown prose context (e.g., within paragraphs). Now escapes backslashes before backticks to prevent incomplete sanitization src/utils/formatting.ts27-32 CHANGELOG.md22
• toToolErrorResult: Converts caught errors into a typed user-facing tool result, distinguishing between 404, 4xx, 5xx, and network/timeout issues src/utils/errors.ts44-69

Tool Patterns

• InputShape/InputSchema/Input pattern: Every tool exports its Zod shape (for registration), the Zod schema (for validation/testing), and the TypeScript type (inferred from schema) CONTRIBUTING.md131-150
• passthrough (Zod): Used in response schemas to ensure unknown API fields are preserved rather than stripped during validation CHANGELOG.md123-124

Data Flow Diagram

This diagram shows how a request from a user flows through the MCP server logic, specifically highlighting the transformation of search parameters and the role of the rate limiter.

Request and Data Flow

Sources: CLAUDE.md76-81 src/utils/formatting.ts75-111 src/utils/errors.ts44-69 src/tools/search-tenders-params.ts41-87

Reference Tables

Key Functions & Utilities

Function	Purpose	Code Reference
buildUrl	Construct URLs with repeated query keys for arrays	src/api/client.ts109-131
toToolErrorResult	Map exceptions to user-friendly error messages	src/utils/errors.ts44-69
buildTenderSearchQuery	Map user filters to simap API parameters	src/tools/search-tenders-params.ts41-87
formatPublicationDetails	Render structured tender data into Markdown	src/utils/formatting.ts158-185
formatInlineCode	CommonMark §6.1 compliant code span wrapping	src/utils/formatting.ts54-63
getTranslation	Extract text using the standard fallback chain	src/utils/translation.ts15-21

Core Parameters & Config

Parameter	Meaning	Code Reference
lastItem	Pagination token for the next page of results	src/types/common.ts24
SEARCH_TENDERS_PARAM_MAP	Static mapping of tool keys to API keys	src/tools/search-tenders-params.ts18-30
SIMAP_MCP_DEBUG	Env var to enable verbose stderr logging	src/api/client.ts15-18
changesets	Tool for versioning and changelog management	CHANGELOG.md40-43
mcp-publisher	Workflow for dual-registry publication	CHANGELOG.md40

Sources: src/types/common.ts1-27 src/utils/formatting.ts1-185 src/utils/translation.ts1-22 CHANGELOG.md1-124 src/api/client.ts1-137