Overview

This document provides a high-level introduction to the simap-mcp project, explaining its purpose, architecture, capabilities, and role in the Model Context Protocol ecosystem.

Purpose and Scope

The simap-mcp project is a Model Context Protocol server that provides AI assistants with programmatic access to simap.ch, Switzerland's official public procurement platform README.md1-14 The server exposes 14 specialized tools that enable AI assistants like Claude to search tenders, browse classification codes, and query organizational data from the Swiss public procurement system README.md16-33

Sources: README.md1-14 package.json1-10

What is simap-mcp

simap-mcp (@digilac/simap-mcp) is a Node.js application that implements the Model Context Protocol specification server.json1-4 It acts as a bridge between MCP-compatible AI clients and the simap.ch public API, translating natural language queries into structured API calls and formatting responses into readable Markdown for AI consumption.

The server is distributed as an npm package server.json12-14 and registered in the MCP Registry server.json3 enabling zero-installation usage via npx or traditional global installation README.md40-200 Version 1.3.0 is the current stable release server.json9 requiring Node.js 22 or higher package.json47-49

Sources: server.json1-20 README.md1-14 package.json47-49

System Context

The following diagram illustrates the simap-mcp server's position within the broader ecosystem, showing how code entities interact:

System Architecture Context

Key Components:

Component	Code Entity	Purpose
Entry point	src/index.ts	Server initialization and boot package.json7
Server instance	McpServer	MCP protocol handler and config package.json55
API client	SimapClient	Singleton HTTP communication with simap.ch README.md251
Tool handlers	14 tool modules	MCP tool implementations README.md17-32
Transport	StdioServerTransport	stdio JSON-RPC communication server.json16

Sources: server.json1-20 README.md1-34 package.json1-70

Core Capabilities

The server exposes 14 MCP tools organized into three functional domains README.md16-33:

Tender Operations (3 tools)

Tool Name	Purpose
search_tenders	Search public tenders with filters (text, dates, types, cantons, CPV codes) README.md19
get_tender_details	Retrieve full details of a specific tender README.md20
get_publication_history	Get publication timeline for a project README.md25

Code and Nomenclature Systems (9 tools)

The server provides search and browse capabilities for four Swiss classification systems README.md21-32:

System	Search Tool	Browse Tool	Purpose
CPV	search_cpv_codes	browse_cpv_tree	Common Procurement Vocabulary (EU standard)
BKP	search_bkp_codes	browse_bkp_tree	Building construction codes (Swiss)
NPK	search_npk_codes	browse_npk_tree	Standardized position catalog
OAG	search_oag_codes	browse_oag_tree	Object classification codes

Additional tool:

• list_cantons - List all 26 Swiss cantons with codes README.md23

Organization Data (2 tools)

Tool Name	Purpose
list_institutions	List Swiss public institutions that publish tenders README.md24
search_proc_offices	Search public procurement offices README.md26

Sources: README.md16-33

Architecture Layers

The codebase follows a modular architecture with clear separation of concerns:

Architectural Layers and Dependencies

Layer Responsibilities:

Layer	Key Components	Purpose
Entry	src/index.ts	Bootstraps the server and transport package.json9
Tools	src/tools/	Domain logic and Zod input validation package.json56
API	src/api/	HTTP communication and rate limiting
Utils	src/utils/	i18n, Error mapping, and Markdown formatting

Sources: server.json1-20 package.json1-70

Distribution and Deployment

The simap-mcp server uses a dual-distribution strategy:

NPM Distribution

The package is published as @digilac/simap-mcp server.json13:

1. npx: npx -y @digilac/simap-mcp README.md55-56
2. Global: npm install -g @digilac/simap-mcp README.md185
3. Source: Build via npm run build package.json12 README.md209

MCP Registry Distribution

The server is registered as io.github.Digilac/simap-mcp server.json3 The registry entry references the npm package and specifies stdio transport server.json10-19

Automated Publishing Workflow

Build and Quality Process:

Stage	Command	Purpose
Lint	npm run lint	Code quality checks package.json15
Format check	npm run format:check	Prettier validation package.json18
Type check	npm run typecheck	TypeScript validation package.json19
Build	npm run build	Compile to dist/ package.json12
Test	npm test	Execute vitest suite package.json20

Sources: package.json11-28 README.md3-8

Communication Protocol

The server implements JSON-RPC over stdio transport:

Request Flow Through Code Entities

Protocol Details:

Aspect	Implementation	Reference
Transport	stdio	server.json16
Validation	zod	package.json56
SDK	@modelcontextprotocol/sdk	package.json55

Sources: server.json15-18 package.json54-57

Typical Use Cases

• Search: "Show me new tenders published today in simap" README.md231
• Filter: "Find construction tenders in canton Vaud in simap" README.md232
• Details: "Give me the details of this tender in simap" README.md233
• Codes: "Search CPV codes for IT services in simap" README.md234

Sources: README.md227-235

Project Metadata

• Version: 1.3.0 server.json9
• License: MIT README.md255
• Author: Digilac README.md13
• Repository: https server.json6

Sources: server.json1-20 README.md1-14