System Overview

Purpose and Scope

This document describes the high-level architecture of the simap-mcp system, including its core components, layered design, and data flow patterns. It focuses on the MCP server infrastructure, stdio transport mechanism, and the relationships between major architectural layers.

The simap-mcp project serves as a Model Context Protocol (MCP) server that integrates with simap.ch, Switzerland's public procurement platform, exposing 14 tools for searching and retrieving tender information, nomenclature codes (CPV/BKP/NPK/OAG), and organization data CLAUDE.md5-8 ARCHITECTURE.md5-16

---

Core Components

The simap-mcp system consists of four primary components that work together to provide MCP-based access to the simap.ch API.

System Components Diagram

Sources: src/index.ts1-15 src/server.ts1-35

Entry Point

The application entry point is located at src/index.ts1-15 This file:

• Contains a shebang (#!/usr/bin/env node) making it executable as a command-line tool src/index.ts1
• Imports the startServer function from src/server.ts30-35
• Initiates the server startup process src/index.ts12-15
• Implements basic error handling that logs to stderr and exits with code 1 on fatal errors src/index.ts13-14

MCP Server Instance

The McpServer instance is created by the createServer() function in src/server.ts16-25 This instance:

• Uses the @modelcontextprotocol/sdk package src/server.ts5
• Is configured with server metadata:
  • name: "simap" src/server.ts18
  • version: Extracted from package.json src/server.ts11-19
• Receives tool registrations via the registerTools(server) call src/server.ts22 which populates the server with the 14 available tools ARCHITECTURE.md10
• Handles incoming JSON-RPC requests from the AI assistant client.

Sources: src/server.ts1-35 ARCHITECTURE.md1-16

Transport Layer

The transport layer uses StdioServerTransport from the MCP SDK src/server.ts6 which:

• Enables communication via standard input/output streams (stdin/stdout) src/server.ts32-33
• Implements the JSON-RPC protocol for message exchange ARCHITECTURE.md7
• Runs the server as a child process of the AI assistant client (e.g., Claude Desktop).
• Eliminates the need for network configuration.

The connection is established in src/server.ts33 via await server.connect(transport). A confirmation message is logged to stderr src/server.ts34 to avoid interfering with stdout, which is reserved for protocol communication.

Sources: src/server.ts30-35 ARCHITECTURE.md5-16

---

Layered Architecture

The simap-mcp system follows a clean layered architecture with unidirectional dependencies flowing from top to bottom.

Architecture Layers Diagram

Sources: ARCHITECTURE.md18-63 src/api/endpoints.ts5-31 CLAUDE.md33-70

Layer Responsibilities

Layer	Path	Responsibilities	Dependencies
Entry & Server	src/index.ts src/server.ts	Application bootstrap, MCP server initialization, transport setup src/server.ts1-35	MCP SDK, Tools Layer
Tools	src/tools/	Tool registration, input validation via Zod, output formatting src/tools/index.ts33 ARCHITECTURE.md72-82	API Layer, Support Layer
API Client	src/api/	HTTP communication (fetch), endpoint management, rate limiting, timeouts src/api/client.ts28 src/api/rate-limiter.ts30	None (external simap.ch only)
Support	src/types/ src/utils/	Type definitions, translation with fallback, Markdown formatting, error mapping src/utils/translation.ts66 src/utils/errors.ts65	None

The architecture enforces separation of concerns:

• No circular dependencies: Each layer only depends on layers below it.
• Single API client: All HTTP communication goes through the SimapClient singleton (simap) ARCHITECTURE.md88-91
• Rate Limiting: The client composes a SlidingWindowRateLimiter (default: 60 req/min, FIFO-ordered) to prevent API abuse ARCHITECTURE.md91 CLAUDE.md77
• Centralized types: Type definitions are shared across layers via src/types/ ARCHITECTURE.md56-61
• Reusable utilities: Translation and formatting logic is abstracted for use across tools ARCHITECTURE.md63-67

Sources: ARCHITECTURE.md18-91 CLAUDE.md74-82

---

Data Flow

Request processing follows a consistent pipeline from user input to formatted response.

Request Processing Flow

Sources: ARCHITECTURE.md5-16 src/server.ts30-35 src/utils/errors.ts9-105

Data Transformation Stages

1. Input Reception: JSON-RPC message arrives via stdin.
2. Routing: McpServer routes to registered tool handler based on tool name src/server.ts22
3. Validation: Zod schemas validate parameter types and constraints using the *InputShape pattern ARCHITECTURE.md72-83
4. API Request: SimapClient constructs and sends HTTPS request using native fetch, respecting the SlidingWindowRateLimiter ARCHITECTURE.md88-91
5. Response Parsing: JSON response is parsed into typed objects defined in src/types/api.ts ARCHITECTURE.md58
6. Formatting: Utilities transform data into Markdown with multilingual support via getTranslation() ARCHITECTURE.md93-95
7. Output Transmission: Formatted result sent via stdout as JSON-RPC response.

Each stage has clear error boundaries. Validation errors prevent API requests, and API errors are caught and transformed into user-friendly messages via toToolErrorResult() which maps status codes (404, 4xx, 5xx) to specific strings ARCHITECTURE.md97-108 Debug logging can be enabled via SIMAP_MCP_DEBUG=1 to see raw request/response details on stderr CLAUDE.md80

Sources: ARCHITECTURE.md65-108 src/utils/errors.ts9-105 CLAUDE.md78-81

---

Execution Model

The simap-mcp server operates as a child process of the AI assistant client, typically communicating via stdio.

Process Model

Sources: src/index.ts1-15 src/server.ts30-35

Process Lifecycle

Phase	Action	Component
Startup	AI client spawns the process using the configured command (e.g., npx simap-mcp)	AI Assistant
Initialize	index.ts calls startServer() which creates McpServer and connects transport src/index.ts12 src/server.ts30-33	simap-mcp
Ready	Server logs "simap MCP Server running on stdio" to stderr src/server.ts34	simap-mcp
Operation	Server processes JSON-RPC requests via stdin, responds via stdout	StdioServerTransport
Shutdown	AI client closes stdin, server process exits	Operating System

The server is stateless — each request is independent, and no data is persisted between requests. The process remains running for the duration of the AI session. Node.js >=22 is required as of v1.3.0 CLAUDE.md22

Sources: src/index.ts1-15 src/server.ts30-35

---

Component Interactions

The following table summarizes the key interactions between major system components.

Component Communication Matrix

Source Component	Target Component	Interaction Type	Protocol/Mechanism	Purpose
index.ts	server.ts	Function call	startServer()	Bootstrap server src/index.ts12
server.ts	McpServer	Instantiation	new McpServer({...})	Create server instance src/server.ts17
server.ts	tools/index.ts	Function call	registerTools(server)	Register all tools src/server.ts22
McpServer	StdioServerTransport	Connection	server.connect(transport)	Establish communication src/server.ts33
StdioServerTransport	AI Client	Stdio streams	JSON-RPC over stdin/stdout	Bidirectional messaging src/server.ts32
Tool handlers	SimapClient	Method calls	Singleton access	Make API requests ARCHITECTURE.md88-91
SimapClient	simap.ch	HTTPS	HTTP GET	Retrieve data ARCHITECTURE.md28
Tool handlers	utils/translation.ts	Function calls	getTranslation(...)	Extract multilingual text ARCHITECTURE.md93-95
Tool handlers	utils/formatting.ts	Function calls	Formatting helpers	Format output ARCHITECTURE.md67
Tool handlers	utils/errors.ts	Function calls	toToolErrorResult(...)	Standardize error output ARCHITECTURE.md97-108

Sources: src/index.ts src/server.ts ARCHITECTURE.md src/api/endpoints.ts CLAUDE.md