Architecture

This document provides a comprehensive overview of the simap-mcp system architecture, explaining how the server is structured to bridge AI assistants with the SIMAP.ch public procurement platform. It covers the layered design, communication patterns, and key architectural decisions.

For detailed information on specific aspects:

• System Overview — High-level architecture: MCP server, stdio transport, and data flow from client to SIMAP API.
• Tool Architecture — Structure, registration, and categorization of the 14 available tools.
• API Integration Layer — SimapClient implementation, endpoint management, and HTTP communication patterns.
• Type System and Utilities — Type definitions, Zod validation, translation fallbacks, and Markdown helpers.

System Context

The simap-mcp server operates as a stdio-based MCP server that acts as a bridge between AI assistants (primarily Claude) and the SIMAP.ch public procurement API. The server runs as a child process of the MCP client, communicating via JSON-RPC over standard input/output streams.

System Context and Process Boundary

Sources: src/index.ts10-15 src/server.ts5-35 ARCHITECTURE.md3-17

Key Architectural Characteristics:

Aspect	Design Decision	Rationale
Transport	StdioServerTransport	Standard MCP protocol, no network configuration needed. src/server.ts32-33
Communication	Synchronous request/response	Simplifies implementation, matches API query pattern.
Authentication	None	SIMAP.ch API is public, no auth required.
Data Operations	Read-only queries	Server only retrieves data, never modifies.
State Management	Stateless	Each request is independent, no session management.
Rate Limiting	SlidingWindowRateLimiter	Protects upstream API with FIFO-ordered queueing. src/api/rate-limiter.ts43
Language Support	Multilingual (de/fr/it/en)	Swiss context requires all four national languages. CLAUDE.md81

Sources: src/server.ts28-35 ARCHITECTURE.md89-107 CLAUDE.md77-81

Layered Architecture

The codebase follows a strict three-layer architecture with unidirectional dependencies: Tools → API Client → External SIMAP API. Support layers (types, utils) are used orthogonally across all layers.

Architectural Layers and Code Entities

Sources: ARCHITECTURE.md19-68 src/server.ts22 CLAUDE.md33-70

Layer Responsibilities

Presentation Layer (Tools)

• Implements 14 MCP tool handlers organized by domain (Tenders, Codes, Organizations). CLAUDE.md44-58
• Validates input parameters using Zod shapes (*InputShape). ARCHITECTURE.md72-83 CLAUDE.md76
• Transforms API responses into formatted Markdown output for the AI using src/utils/formatting.ts. CLAUDE.md69
• For details, see Tool Architecture.

API Integration Layer

• SimapClient (singleton simap) handles URL construction via buildUrl(), query parameter serialization, and HTTP calls. CLAUDE.md41 ARCHITECTURE.md87-91 CLAUDE.md77
• Manages concurrency and throughput via SlidingWindowRateLimiter (default 60 req/min, FIFO-ordered). CLAUDE.md43 ARCHITECTURE.md91 CLAUDE.md77
• Maps constants from endpoints.ts to fetch requests. src/api/endpoints.ts7-31
• For details, see API Integration Layer.

Support Layers

• Types: Centralized definitions for API responses (api.ts), tool parameters (tools.ts), and common interfaces (common.ts). CLAUDE.md59-64
• Utils: Logic for i18n translation fallbacks (translation.ts), Markdown formatting helpers (formatting.ts), and standardized error mapping via toToolErrorResult(). CLAUDE.md65-69 CLAUDE.md78
• For details, see Type System and Utilities.

Request Flow and Data Transformation

Every MCP tool invocation follows a consistent pipeline from user input to formatted output.

MCP Tool Request Lifecycle

Sources: src/server.ts16-25 ARCHITECTURE.md72-107 CLAUDE.md74-81

Design Patterns

Tool Registration Pattern

The server uses a decentralized registration pattern. Each tool file exports an *InputShape (raw Zod shape), an *InputSchema (z.object(shape)), and a register* function. These are aggregated in src/tools/index.ts and called during server initialization in src/server.ts. ARCHITECTURE.md72-83 CLAUDE.md76

Sources: ARCHITECTURE.md72-83 src/server.ts22 CLAUDE.md76

Multilingual Fallback

Translation logic implements a fallback chain to ensure data availability in the Swiss context: Requested Language → de → fr → en → it. CLAUDE.md81 ARCHITECTURE.md93-95

Sources: CLAUDE.md81 ARCHITECTURE.md95 src/utils/translation.ts1-20

Error Mapping Pattern

Tool handlers route caught errors through toToolErrorResult() (src/utils/errors.ts) which transforms technical exceptions (like 404s, timeouts, or network failures) into human-readable messages for the AI. CLAUDE.md78 ARCHITECTURE.md97-107

Sources: CLAUDE.md78 ARCHITECTURE.md99-107 src/utils/errors.ts5-40