mcp-camptocamp: 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 Goal

This project provides an MCP (Model Context Protocol) server that exposes the Camptocamp.org API to LLMs. The goal is to enable LLMs to query accurate, up-to-date information about mountain routes, summit altitudes, and route descriptions — preventing hallucinations about mountaineering data.

Architecture

src/
├── index.ts              # Entry point: MCP_TRANSPORT picks stdio (createServer() + StdioServerTransport) or HTTP (dynamic import of http/main.ts)
├── server.ts             # createServer(): McpServer with instructions, version, registerTool for the 15 tools
├── version.ts            # VERSION read from package.json, reported to MCP clients and in the User-Agent
├── http/                 # HTTP mode only (MCP_TRANSPORT=http); never loaded over stdio
│   ├── config.ts         # MCP_* settings: readTransport, readHttpConfig, ConfigError (exit 1, tokens named by position)
│   ├── auth.ts           # Bearer token check: HMAC digests compared with timingSafeEqual, no early exit
│   ├── guards.ts         # Host and Origin checks against MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS
│   ├── body.ts           # readBody: 64 KiB cap, declared or streamed
│   ├── server.ts         # Stateless Streamable HTTP on /mcp, /healthz, 90 s timeout, one log line per request, 8 s drain
│   └── main.ts           # runHttp: startup line, upstream cap and User-Agent, SIGTERM/SIGINT handlers
├── api/
│   ├── http.ts           # getJson: the one fetch (User-Agent, 15 s timeout, 10 MiB cap, error messages, zod parsing)
│   ├── upstream.ts       # HTTP mode only: FIFO cap on Camptocamp requests (queue 50, 20 s), request context, self-hosted User-Agent
│   ├── schemas.ts        # zod response schemas, the one place response types are declared
│   └── camptocamp.ts     # Camptocamp API v6 client: one function per endpoint, pl={lang} (default fr) on searches
└── tools/
    ├── format.ts         # Shared formatting: pickLocale, joinList, formatHeader, route/waypoint/book/outing lines, recent outings, areas section, dates, isPresent (0 and false are printed)
    ├── inputs.ts         # Shared zod inputs: bounded document IDs, 200-char queries
    ├── ratings.ts        # Rating labels by grading system (RATING_DISPLAY) and rating scales (ROUTE_RATING_SYSTEMS)
    ├── enums.ts          # Camptocamp's closed value lists: filters (activities, route types, configurations), CUSTODIANSHIPS meanings
    ├── paging.ts         # Shared search paging: header, filters, next-page footer, 10,000-result window; quote() escapes echoed user input (query, rating bounds) onto one line
    ├── filters.ts        # Shared rating and range filters of search_routes and search_outings: inputs, checks, Filters text
    ├── text.ts           # formatUserText: rewrites image tags and internal links, delimits, demotes and caps user-written text
    ├── concurrency.ts    # mapWithConcurrency: parallel API calls in input order, at most MAX_PARALLEL_REQUESTS (3) at a time
    ├── routes.ts         # Tools: search_routes, get_route
    ├── waypoints.ts      # Tools: search_waypoints, get_waypoint
    ├── outings.ts        # Tools: search_user_outings, get_outing, search_outings, get_outings
    ├── outing-stats.ts   # Tool: outing_stats; collectOutingSets reads every outing of one or more searches (at most 2,000, pages of 100)
    ├── areas.ts          # Tools: search_areas, get_area
    ├── books.ts          # Tools: search_books, get_book
    └── articles.ts       # Tools: search_articles, get_article
scripts/                  # Dev-only, outside src/: neither built nor shipped
├── docs-tools.ts         # npm run docs:tools: writes docs/tools/<tool>.md, creating missing pages
└── docs/
    └── inputs.ts         # Renders each tool's Inputs block (between the generated:inputs markers) from its registered JSON Schema
tests/
├── api/
│   ├── camptocamp.test.ts  # API client unit tests with mocked fetch (URLs, parameters)
│   ├── http.test.ts        # getJson: errors, timeout, size cap, User-Agent, malformed responses
│   ├── upstream.test.ts    # Upstream cap, FIFO queue, busy error, request context, User-Agent
│   └── schemas.test.ts     # Response schemas against real-shaped fixtures (null and missing fields)
├── server/                 # MCP-layer tests: SDK Client + InMemoryTransport against createServer(), fetch mocked
│   ├── helpers.ts          # connect(), stubFetch(), jsonResponse()
│   ├── registration.test.ts      # Tool list, titles, annotations, input schemas (snapshot), instructions, call results
│   ├── input-validation.test.ts  # Invalid inputs rejected before any request
│   ├── errors.test.ts            # Upstream failures returned as isError
│   └── version.test.ts           # Reported version equals package.json
├── http/                   # HTTP mode, server started in-process (helpers.ts), fetch mocked
│   ├── config.test.ts, auth.test.ts, guards.test.ts, body.test.ts  # Settings, token check, Host/Origin, body cap
│   ├── server.test.ts      # Routes, /healthz, 401, 403, 413, 400, stateless MCP, startup line
│   ├── fidelity.test.ts    # Tools, schemas and tool output identical to the in-memory transport
│   ├── logging.test.ts, timeout.test.ts, shutdown.test.ts, upstream.test.ts  # Request log, 504, drain, cap and User-Agent
│   └── cli.test.ts         # src/index.ts spawned: stdio by default, HTTP startup and exit codes; runHttp signals
├── contract/
│   └── api.contract.test.ts  # Live Camptocamp API contract tests (npm run test:contract only)
├── docs/
│   ├── markdown.ts         # Markdown helpers (files, fenced blocks, inline code, links, GitHub heading slugs) and the docs checks
│   ├── docs.test.ts        # docs/ and README.md: links and anchors, json blocks, mcpServers (stdio or self-hosted HTTP entry), no literal bearer token, package/image names, Node version, Sources, support matrix dates, self-hosting guide commands
│   ├── inputs.test.ts      # docs:tools generator: rendered Inputs block, markers, page idempotence, all 15 schemas
│   ├── tools.test.ts       # docs/tools/: one page per registered tool, the index, Inputs blocks in sync with the schemas, no unknown tool or parameter
│   ├── clients.test.ts     # docs/clients/: Mistral Vibe Code and Gemini CLI config snippets (toml permissions, mcp_servers entry, policy rules)
│   ├── readme.test.ts      # README.md: length, sections, badges, quick start copied from getting-started, one line per tool
│   └── system-prompt.test.ts  # docs/system-prompt.md: one prompt block, its length cap and its rules
├── hooks/
│   └── guard.test.sh       # Tests for the agent guard hook (.claude/hooks/guard.sh), run on the host
└── tools/
    ├── through-schema.ts   # Test helper: parses mocked API fixtures through the zod schemas
    ├── bare-rating.ts      # Test helper: BARE_RATING, a bare "Rating:" label that must never be printed
    ├── format.test.ts      # Shared formatting helper unit tests
    ├── ratings.test.ts     # Rating label order, Labande joining and rating scales
    ├── paging.test.ts      # Shared search paging unit tests
    ├── filters.test.ts     # Shared rating and range filter checks and messages
    ├── text.test.ts        # formatUserText unit tests
    ├── concurrency.test.ts # mapWithConcurrency: order, cap, fast rejection
    ├── routes.test.ts      # Tool handler unit tests
    ├── waypoints.test.ts   # Tool handler unit tests
    ├── outings.test.ts     # Tool handler unit tests
    ├── outing-stats.test.ts # outing_stats counts (61 Innominata outings) and collectMatchingOutings paging
    ├── areas.test.ts       # Tool handler unit tests
    ├── books.test.ts       # Tool handler unit tests
    └── articles.test.ts    # Tool handler unit tests
docs/
├── README.md               # Docs index: Start here, Clients, Guides, Tool reference, support matrix (Last verified per client)
├── getting-started.md      # Prerequisites, npx and Docker commands, pre-warm, smoke test, Claude Code and mcpServers config
├── troubleshooting.md      # Startup timeout, old Node, Docker -i, Gemini trust, Claude Desktop logs, ENOENT, output limit, status
├── clients/                # One page per client: setup, tool approval, limits, Sources and a Last verified line
│   ├── claude-desktop.md
│   ├── claude-code.md
│   ├── chatgpt-desktop-and-codex.md
│   ├── mistral-vibe-code.md
│   ├── gemini-cli.md
│   └── remote-only.md      # Clients that only take remote servers, with their source and a local alternative
├── agent-sdks.md           # OpenAI Agents SDK, Mistral and google-genai over stdio, with Sources
├── self-hosting.md         # HTTP mode: token, docker run / compose / npx, Caddy, checks, logs, each client, Sources
├── using-with-llms.md      # Tool chains, a worked example, output conventions, what the server does not provide
├── system-prompt.md        # A copyable system prompt for SDK agents, and why each rule
├── development.md          # Make targets, contract tests, local image, releases, stack
└── tools/                  # Tool reference: README.md index, one <tool>.md page per tool (Inputs block generated by npm run docs:tools)
vitest.config.ts            # npm test / coverage: excludes tests/contract/ and the src/index.ts bootstrap
vitest.contract.config.ts   # npm run test:contract: only tests/contract/**/*.contract.test.ts, no coverage