Weather Pro

A Model Context Protocol server that exposes real-time weather, built to demonstrate the full MCP surface — not just tools — and to run like a real service (dual transport, auth, caching, retries, tests, Docker, CI).

It is the "after" to a deliberately minimal "before" (../mcp-real-weather-api), which exposes a single get_weather tool over stdio and nothing else.

Targets the current stable spec, MCP 2025-11-25, via @modelcontextprotocol/sdk.

---

What it demonstrates

MCP concept	Where to see it	What it proves
Structured output	get_weather outputSchema → structuredContent	Tool results are typed & machine-readable, not opaque text
Tool annotations	readOnlyHint, openWorldHint on both tools	Server signals to the host that a tool is safe to auto-run
Input validation	Zod inputSchema on every tool	Bad arguments are rejected before our code runs
Elicitation	get_weather on an ambiguous city ("Springfield")	Server pauses to ask the user a structured question
Sampling	get_weather includeAdvice	Server asks the client's LLM for advice — ships no LLM SDK itself
Progress	compare_weather over several cities	Long-running tool streams incremental progress + supports cancel
Resources (direct)	weather://reference/conditions	Fixed, read-only context (WMO code table)
Resource templates	weather://current/{city}, weather://forecast/{city}/{date}	Parameterised, discoverable data (RFC 6570 URIs)
Completions	{city} autocomplete on templates & the prompt	Suggests valid argument values as you type
Prompts	plan-my-day	Reusable, user-invoked workflow (slash command)
Logging	sendLoggingMessage in tools	Structured observability over the protocol

See DEMO.md for the guided walkthrough / talking points.

---

Quick start

npm install
npm test          # unit tests (offline, deterministic)
npm run inspect   # open the MCP Inspector against the stdio server

Run it

# Local (stdio) — for Claude Desktop, IDEs
npm start

# Remote (HTTP) — for multi-client / deployment
MCP_TRANSPORT=http PORT=3000 MCP_AUTH_TOKEN=changeme npm run start:http

End-to-end smoke tests (hit the live Open-Meteo API):

npm run smoke                                   # spawns + drives the stdio server
# In one terminal: MCP_TRANSPORT=http PORT=3030 MCP_AUTH_TOKEN=demo-secret npm start
npm run smoke:http                              # drives the running HTTP server

---

Connect a client

Claude Desktop / IDE (stdio)

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "weather-pro": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-weather-pro/src/index.js"]
    }
  }
}

Remote (Streamable HTTP)

{
  "mcpServers": {
    "weather-pro": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer changeme" }
    }
  }
}

---

Architecture

src/
  index.js              entrypoint — selects transport from MCP_TRANSPORT
  config.js             env-driven config (one source of truth)
  logger.js             structured JSON logs → stderr (stdout is the protocol!)
  cache.js              bounded TTL cache (hit/miss stats)
  httpClient.js         axios + timeout + retry/backoff for upstream calls
  schemas.js            Zod input/output schemas (validation + structured output)
  server.js             builds the McpServer and registers every primitive
  services/
    geo.js              geocoding + ambiguity detection (powers elicitation)
    weather.js          current + forecast + WMO code mapping + units
    cities.js           static list for completions
  features/
    tools.js            get_weather, compare_weather
    resources.js        direct resource + two templates
    prompts.js          plan-my-day
  transports/
    stdio.js            local transport + graceful shutdown
    http.js             Streamable HTTP + Bearer auth + sessions + /health

Production concerns covered

• Dual transport (stdio + Streamable HTTP) from one codebase.
• Auth — Bearer token on every HTTP /mcp call; /health left open.
• Resilience — per-call timeouts, bounded exponential backoff with jitter.
• Caching — geocoding (24h) and weather (5m) with bounded size + eviction.
• Validation — Zod on all tool inputs; SDK validates structured output.
• Graceful degradation — elicitation/sampling are used only if the client supports them; otherwise the tool still returns a correct result.
• Observability — structured stderr logs + protocol-level logging.
• Tests & CI — unit tests on Node 18/20/22 + a Docker build in GitHub Actions.
• Containerised — multi-stage-friendly Dockerfile with a healthcheck.

License

MIT