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

Related MCP server: OpenWeather-OneCall3-MCP

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).