open-meteo-mcp: Instructions file for Codex

AGENTS.md

Open-Meteo MCP (Model Context Protocol) server: gives LLMs access to Open-Meteo's forecast, historical, air quality, marine, flood, seasonal and climate projection APIs.

Instructions for coding agents. Detailed, area-specific guidance lives in .claude/rules/ (see Area rules) and the release procedure in .claude/skills/release/SKILL.md.

Architecture

• src/index.ts - MCP server (@modelcontextprotocol/sdk), tool registration, both transports
• src/client.ts - OpenMeteoClient: one Axios instance per Open-Meteo service, LRU response cache
• src/tools.ts - Tool metadata (name, title, description, annotations); input schemas come from types.ts
• src/instructions.ts - Server instructions sent at initialize (lands in the client's system prompt): which tool answers which question. A test fails if a tool is not mentioned
• src/types.ts - Zod schemas for all API parameters and responses
• src/truncation.ts - Caps oversized responses and serializes them for the client
• src/security.ts - Auth, origin validation, rate limiting, trusted-proxy IP extraction (HTTP transport only)

Transports

Selected by the TRANSPORT env var:

• stdio (default) - for local MCP clients. Never write logs to stdout here — it would corrupt the protocol stream; log() writes to stderr.
• Streamable HTTP (TRANSPORT=http) - stateless Express server on /mcp, bound to 127.0.0.1 by default.

Tools (17)

• Core: weather_forecast, weather_archive, air_quality, marine_weather, elevation, geocoding
• Model-specific (same schema, different endpoint): dwd_icon_forecast, gfs_forecast, meteofrance_forecast, ecmwf_forecast, jma_forecast, metno_forecast, gem_forecast
• Advanced: flood_forecast, seasonal_forecast, climate_projection, ensemble_forecast

Commands

npm run dev        # auto-reload
npm run build      # TypeScript -> dist/
npm start          # run the built server
npm test
npm run typecheck
npm run lint
npm run smoke      # every tool against the live API (needs a prior build)