weather-mcp

Multi-tenant MCP server for OpenWeather One Call API 4.0, built from the skeleton pattern with:

• Persistent secrets in Vault
• Persistent configuration in Postgres
• Tenant/principal scoping (tenant/user and tenant/account)
• Admin-guarded mutation tools through MCP_ADMIN_AUTH_KEY
• Full One Call 4.0 endpoint coverage

What This MCP Exposes

OpenWeather One Call 4.0 endpoints covered:

• GET /data/4.0/onecall/current
• GET /data/4.0/onecall/timeline/1min
• GET /data/4.0/onecall/timeline/15min
• GET /data/4.0/onecall/timeline/1h
• GET /data/4.0/onecall/timeline/1day
• GET /data/4.0/onecall/alert/{alert_id}

Extra dedicated MCP tools:

• Scope metadata and discovery
• Query suggestion and schema discovery
• Vault API key upsert/delete/status per tenant/principal
• Postgres config get/list/set/delete per tenant/principal
• Vault HTTP token create/revoke per tenant/principal
• Safe pagination URL follower

Persistence Model

• Secrets (OpenWeather API key, HTTP auth token index) are stored in Vault KV.
• Config values are stored in Postgres table <app_name>_config.

Scope path examples:

• Vault token index: weather/tenants/acme/users/sam/http/auth/token-index
• Vault API key secret: weather/tenants/acme/users/sam/http/auth/token-index/openweather

Quick Start

1. Copy .env.example to .env and fill values.
2. Start local dependencies:
   • docker compose up -d postgres vault
3. Install dependencies:
   • npm ci
4. Generate endpoint inventory artifact:
   • npm run inventory:generate
5. Run tests:
   • npm test
6. Start MCP:
   • stdio: npm run start:stdio
   • http: npm run start:http

Key Environment Variables

• MCP_ADMIN_AUTH_KEY: Required for mutating tools when set.
• MCP_CONFIG_DEFAULT_TENANT_ID
• MCP_CONFIG_DEFAULT_PRINCIPAL_TYPE
• MCP_CONFIG_DEFAULT_PRINCIPAL_ID
• OPENWEATHER_API_KEY: global fallback only; recommended pattern is scoped Vault key via tool.
• MCP_HTTP_TOKEN_SOURCE=vault|static

See .env.example for complete list.

Tooling Reference

Detailed LLM-oriented tool contracts are in:

• docs/tools.md

Coverage inventory artifact:

• artifacts/openweather-onecall4-inventory.json

Inventory and Push Enforcement

Scripts:

• npm run inventory:generate
• npm run inventory:check
• npm run verify:prepush

CI workflow .github/workflows/inventory-and-tests.yml enforces:

• Inventory generation
• Inventory file committed and stable
• Full test pass through verify:prepush

Security Notes

• Do not place production OpenWeather keys in plaintext env if scoped Vault keys are available.
• Mutating tools should always be invoked with authorizationKey when MCP_ADMIN_AUTH_KEY is configured.
• MCP_ALLOW_SENSITIVE_OUTPUT=false redacts sensitive values from tool output.

License

MIT (see LICENSE).