Project Structure

This document explains the directory layout, file organization, and module boundaries of the simap-mcp codebase. It is intended for developers who need to navigate the project, understand where different types of code reside, and maintain consistent organization when adding new features.

Overview

The simap-mcp project follows a layered architecture with clear separation of concerns. The codebase is organized into distinct layers that isolate tool implementations, API communication, type definitions, and utility functions. The server acts as a bridge between the Model Context Protocol (MCP) and the SIMAP.ch REST API.

Sources: ARCHITECTURE.md3-17 CONTRIBUTING.md84-89

Directory Structure

The project follows a flat hierarchy at the root level with four main directories:

Directory	Purpose
src/	All TypeScript source code ARCHITECTURE.md22-68
tests/	Test files organized to mirror the src/ structure CONTRIBUTING.md184-187
dist/	Compiled JavaScript output (generated by npm run build) tsconfig.json6
Configuration	Root level files for build, lint, and package metadata CONTRIBUTING.md48-60

Sources: ARCHITECTURE.md21-68 CONTRIBUTING.md48-60 tsconfig.json1-17

Source Code Organization

Entry Points and Server Lifecycle

The application has two primary entry point files at the root of src/:

• src/index.ts: The executable entry point that starts the server ARCHITECTURE.md23
• src/server.ts: Contains the logic for configuring the McpServer instance and connecting it to the StdioServerTransport ARCHITECTURE.md24

Sources: ARCHITECTURE.md23-24 ARCHITECTURE.md33 CONTRIBUTING.md171-173

Tools Layer

The src/tools/ directory contains all 14 MCP tool implementations, organized by functional domain. Each tool is registered to the McpServer instance via the registerTools function ARCHITECTURE.md33

Tools follow a modular pattern:

1. Input Shape: Defined using zod for runtime input validation. Each tool exports an *InputShape (raw object), an *InputSchema (wrapped z.object), and an *Input type CONTRIBUTING.md133-150
2. Handler: An async function that processes the request and returns tool results, typically wrapped in a try/catch block CONTRIBUTING.md152-169
3. Registration: Exported register* functions (e.g., registerSearchTenders) that take the McpServer instance as an argument CONTRIBUTING.md171-173

Sources: ARCHITECTURE.md32-55 CONTRIBUTING.md119-174 ARCHITECTURE.md72-85

API Integration Layer

The src/api/ directory manages all communication with the SIMAP.ch backend.

File	Key Entity	Purpose
client.ts	SimapClient	A centralized HTTP client (singleton simap) that handles URL building via buildUrl(), timeouts, and response validation ARCHITECTURE.md28
endpoints.ts	ENDPOINTS	Constants for all API endpoint paths ARCHITECTURE.md29
rate-limiter.ts	SlidingWindowRateLimiter	Implements FIFO-ordered rate limiting (default 60 req/min) ARCHITECTURE.md30

Sources: ARCHITECTURE.md26-30 ARCHITECTURE.md87-92

Types and Utilities

• src/types/: Defines the data structures used across the project.
  • api.ts: API response types like SimapApiError and ProjectSearchEntry ARCHITECTURE.md58
  • common.ts: Shared types like Translation, Language, and Pagination ARCHITECTURE.md59
  • tools.ts: Parameter enums for tool inputs like ProjectSubType ARCHITECTURE.md61
  • schemas.ts: Shared Zod primitives used for validation ARCHITECTURE.md60
• src/utils/: Shared logic for processing data.
  • translation.ts: Implements getTranslation() with a fallback chain: requested lang → de → fr → en → it ARCHITECTURE.md66
  • formatting.ts: Contains Markdown formatting helpers like formatProject ARCHITECTURE.md67
  • errors.ts: toToolErrorResult() for standardized error reporting to the MCP client ARCHITECTURE.md65

Sources: ARCHITECTURE.md56-68 ARCHITECTURE.md93-107

Data Flow: From MCP Client to SIMAP API

This diagram bridges the gap between the Natural Language space (MCP tools) and the Code Entity space (classes and functions).

Sources: ARCHITECTURE.md5-17 ARCHITECTURE.md87-111 CONTRIBUTING.md133-174 ARCHITECTURE.md129-132

Module Boundaries and Conventions

The project enforces strict naming conventions and file organization to ensure maintainability:

Element	Convention	Example
Files	kebab-case	search-tenders.ts CONTRIBUTING.md200
Functions	camelCase	registerSearchCpv CONTRIBUTING.md201
Classes	PascalCase	SimapClient CONTRIBUTING.md202
MCP Tools	snake_case	search_cpv_codes CONTRIBUTING.md204
Constants	UPPER_SNAKE	SIMAP_API_BASE CONTRIBUTING.md203

TypeScript strict mode is enabled via tsconfig.json tsconfig.json8 Tests are mandatory for every new feature and should mirror the source structure CONTRIBUTING.md184-187

Sources: CONTRIBUTING.md188-205 ARCHITECTURE.md133-142 tsconfig.json1-17