Runtime Dependencies

This page documents the production dependencies required to run simap-mcp. The project maintains a minimal footprint, relying on two primary libraries to handle the Model Context Protocol (MCP) infrastructure and data validation.

---

Overview

The simap-mcp server requires exactly two runtime dependencies to operate. These are declared in the dependencies section of the project configuration.

Dependency	Version	Purpose
@modelcontextprotocol/sdk	^1.29.0	MCP protocol implementation, server framework, and stdio transport
zod	^4.4.3	Schema definition, input validation, and type inference (Bumped in v1.2.4)

These dependencies are installed automatically when running npm install or when the package is executed via npx @digilac/simap-mcp.

Sources: package.json54-57 package-lock.json11-14

---

@modelcontextprotocol/sdk

Purpose and Role

The Model Context Protocol SDK is the core framework used to build the server. It provides the high-level McpServer abstraction which manages tool registration, and the StdioServerTransport which handles the low-level communication with MCP clients (like Claude Desktop) over standard input/output.

Key Components and Implementation

The server lifecycle is managed in src/server.ts, where the SDK classes are instantiated and connected.

Class / Function	Source Location	Role in simap-mcp
McpServer	src/server.ts16-20	The main server instance that holds tool definitions and handles JSON-RPC routing.
StdioServerTransport	src/server.ts32	Implements the JSON-RPC over stdio transport layer.
server.connect()	src/server.ts33	Binds the server instance to the transport to start listening for requests.
registerTools()	src/server.ts22	Function that iterates through domain tools and calls server.tool() to register them.

Sources: src/server.ts1-35 package.json55

Natural Language to Code: MCP Communication

This diagram maps the conceptual flow of an MCP request to the specific SDK entities used in the codebase.

Title: "MCP Request Flow"

Sources: src/server.ts16-35 src/tools/index.ts1-10

---

zod

Purpose and Role

zod is a TypeScript-first schema declaration and validation library. It is used to define the "contract" for every tool exposed by the server and to validate complex responses from the SIMAP API. This ensures that any input received from an LLM matches the expected format before the code attempts to process it, and that API responses conform to expected structures.

In version 1.2.4, zod was bumped to ^4.4.3. This update provides improved handling for discriminatedUnion and preprocess logic, which are critical for robust input sanitization and complex tool parameter branching (e.g., handling optional fields or coercing types from LLM outputs).

Sources: package.json56 package-lock.json13

Implementation Detail

In simap-mcp, zod serves three specific roles:

1. Input Validation: Defining the parameters object passed to server.tool(). Incoming JSON-RPC arguments are automatically parsed against these schemas.
2. API Response Validation: Validating data fetched from SIMAP.ch (e.g., PublicationDetailsSchema) to ensure runtime safety when accessing deeply nested properties.
3. Type Safety: Providing inferred TypeScript types for tool handlers and API clients (e.g., using z.infer) so developers don't have to maintain redundant interface definitions.

The codebase utilizes z.lazy() for recursive structures like CPV code trees src/types/schemas.ts32-34 and .passthrough() to maintain compatibility with undocumented API fields src/types/schemas.ts92

Mapping Nomenclatures to Zod Entities

This diagram shows how domain-specific nomenclature tools (CPV, BKP, etc.) are structured using zod schemas.

Title: "Schema and Nomenclature Mapping"

Sources: src/types/schemas.ts9-55 package.json56

---

Data Flow and Validation Lifecycle

The runtime dependencies work in tandem to process a tool call. The McpServer uses the zod schema to validate the request before the handler is ever executed.

Title: "Validation and Execution Lifecycle"

Sources: src/server.ts16-25 package.json54-57

---

Versioning and Compatibility

The project targets Node.js version 22 or higher as of v1.3.0, which is compatible with the latest versions of both dependencies. Node 20 reached end-of-life on 2026-04-30, leading to the requirement bump.

Requirement	Value	Source
Node.js	>=22	package.json48
SDK Version	^1.29.0	package.json55
Zod Version	^4.4.3	package.json56
Module System	ESM	package.json6

The exact versions of all transitive dependencies are locked in package-lock.json to ensure reproducible builds and stable runtime behavior across different environments.

Sources: package.json6 package.json47-49 package-lock.json1-32