smhi-mcp-server: Instructions file for Claude Code

CLAUDE.md

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

What this is

An MCP (Model Context Protocol) server exposing SMHI (Swedish Meteorological and Hydrological Institute) weather data as tools, built against SMHI's current snow1g point-forecast API. SMHI retired the older pmp3g API on 2026-03-31; this is a fresh implementation, not a migration.

Commands

npm install
npm run typecheck      # tsc --noEmit
npm test                # vitest run (all tests, single run)
npm run test:watch      # vitest (watch mode)
npm run test:coverage   # vitest run --coverage
npm run build            # tsc -> dist/
npm start                 # node dist/index.js

Run a single test file: npx vitest run src/__tests__/tools.test.ts Run tests matching a name: npx vitest run -t "getFireRisk"

CI (.github/workflows/ci.yml) runs on Node 20.x/22.x/24.x: npm ci, npm run typecheck, npm test, npm run build. Match this locally before pushing.

Architecture

Request flow: src/index.ts (MCP server, stdio transport) → tool module in src/tools/*.ts (zod schema + handler) → src/smhi-client.ts (fetches SMHI APIs, shapes raw responses) → lookup tables (weather-symbols.ts, fire-risk-classes.ts) for human-readable descriptions.

Adding a new tool touches four places:

1. src/smhi-client.ts — fetch function against the relevant SMHI API/category, plus a converter from the raw SMHI shape to a processed type.
2. src/types.ts — raw API response types and processed output types for the new data.
3. src/tools/<name>.ts — zod input schema (z.object with .describe() on each field) + async handler calling the client function. Exports the schema, the handler, and the inferred input type.
4. src/tools/index.ts — re-export the new schema/handler/type.
5. src/index.ts — call server.registerTool(name, { description, inputSchema, annotations: { title, ...READONLY_ANNOTATIONS } }, handler), passing the zod schema straight through as inputSchema (it doubles as the wire-format JSON Schema, generated automatically) and wrapping the handler in withErrorHandling unless it needs a non-JSON content block (see get_radar_image, which returns an image block alongside text and so wires its own try/catch).