simap-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP (Model Context Protocol) server that integrates with simap.ch, Switzerland's public procurement platform. Exposes 14 tools and 1 prompt (analyze_tender) for searching and retrieving tender information, nomenclature codes (CPV/BKP/NPK/OAG), and organization data.

Documentation

Commands

npm run build        # Compile TypeScript (tsc)
npm start            # Run the server
npm run dev          # Recompile on every save (tsc --watch)
npm run inspect      # MCP Inspector UI against dist/ (respawns the server per connection)
npm run tools        # List tools + input schemas via the fastmcp CLI (smoke check)
npm run lint         # Check code style
npm run format       # Format with Prettier
npm run format:check # Check formatting (used in CI)
npm run typecheck    # tsc --noEmit
npm test             # Run tests with vitest
npm run test:watch   # Run tests in watch mode

Source Layout

src/
├── index.ts                          # Entry point
├── server.ts                         # MCP server config + stdio transport
├── api/
│   ├── index.ts                      # Re-exports
│   ├── client.ts                     # SimapClient + exported buildUrl()
│   ├── endpoints.ts                  # API endpoint constants
│   ├── rate-limiter.ts               # SlidingWindowRateLimiter (FIFO)
│   └── response-cache.ts             # ResponseCache (TTL + LRU) for reference data
├── tools/
│   ├── index.ts                      # registerTools()
│   ├── search-tenders.ts             # search_tenders
│   ├── search-tenders-params.ts      # SEARCH_TENDERS_PARAM_MAP + buildTenderSearchQuery()
│   ├── get-tender-details.ts         # get_tender_details
│   ├── codes/
│   │   ├── index.ts
│   │   ├── list-cantons.ts           # list_cantons
│   │   ├── search-{cpv,bkp,npk,oag}-codes.ts
│   │   └── browse-{cpv,bkp,npk,oag}-tree.ts
│   └── organizations/
│       ├── index.ts
│       ├── list-institutions.ts
│       ├── search-proc-offices.ts
│       └── get-publication-history.ts
├── prompts/
│   ├── index.ts                      # registerPrompts()
│   └── analyze-tender.ts             # analyze_tender
├── types/
│   ├── index.ts                      # Re-exports
│   ├── api.ts                        # API response types (SimapApiError, ...)
│   ├── common.ts                     # Translation, Language, Pagination
│   ├── tools.ts                      # Parameter enums
│   └── schemas.ts                    # Shared Zod primitives
└── utils/
    ├── index.ts                      # Re-exports
    ├── errors.ts                     # toToolErrorResult(), toolErrorResult()
    ├── register-tool.ts              # registerTool() — FastMCP wrapper
    ├── translation.ts                # getTranslation() with fallback chain
    └── formatting.ts                 # Markdown formatting