Smarter Weather

Smarter Weather Developer Platform

Agents: start here. Nothing to install. Call https://api.smarterweather.com/v1/weather?lat=41.66&lon=-91.53 with no key; the 401 body's next_steps member tells you where to get one and what to do with it. Full agent path: llms.txt / AGENTS.md.

The public home for the Smarter Weather developer platform: SDKs, documentation, example apps, the @smarterweather/mcp-weather and @smarterweather/mcp-onboarding packages, agent skills, and the OpenAPI specification for api.smarterweather.com.

Generally available. The REST API, both hosted MCP servers, and both npm stdio bridges are live in production. Breaking-change policy: six months' notice before removing a /v1/* endpoint or an MCP tool, 90 days before a breaking change to a request or response shape. Non-breaking additions ship immediately.

What lives here

• OpenAPI specification (openapi.yaml) for the public REST API at https://api.smarterweather.com. Auto-synced from the canonical source on change. Also served at https://developers.smarterweather.com/openapi.yaml.
• MCP tool descriptors (descriptors/mcp-tools.json) -- the canonical catalog for the weather MCP server, synced on every server change.
• @smarterweather/mcp-weather -- npm package source for the stdio bridge that connects MCP clients (Cursor, Claude Desktop, Claude Code, etc.) to the hosted MCP endpoint at https://mcp.smarterweather.com. The bridge attaches your API key from SMARTERWEATHER_API_KEY and proxies every JSON-RPC message; all weather logic runs server-side.
• @smarterweather/mcp-onboarding -- npm package source for the stdio bridge to the developer-onboarding MCP server at https://mcp.developers.smarterweather.com. Provides agent-driven self-service account creation, API key provisioning, and SDK setup walkthroughs. Auth via OAuth (browser callback).
• Client SDKs -- TypeScript and Python first; Go to follow. Not yet shipped; call the REST API directly in the meantime.
• Examples -- examples/: the first call in curl, JavaScript, Python and Go, which CI runs against a mock of the API, and MCP client configs for Claude Desktop and Cursor, which CI checks statically. Listed in examples/index.json.
• Agent Plugins -- plugins/smarterweather/ is the long-lived Agent Plugins 1.0 package (weather MCP + playbooks). plugins/smarterweather-onboarding/ is the one-shot signup / key-mint install; remove it after configure_mcp so its account tools are not left in a long-lived config (the two servers live on different hosts and do not conflict). Cursor Marketplace discovery uses .cursor-plugin/marketplace.json. .cursor/skills/use-smarterweather-api/ is a pointer at the weather skills; .claude/CLAUDE.md remains a follow-up refresh.
• Documentation -- guides under docs/ that complement the developer portal at https://developers.smarterweather.com. See the docs index for the current map.

What does not live here: the Smarter Weather core service, ingestion pipeline, or any internal infrastructure. Those remain in a separate private repository.

Quickstart

Three requests, no install:

# 1. Call with no key: the 401 carries `next_steps` (and WWW-Authenticate).
curl -sS -D - 'https://api.smarterweather.com/v1/weather?lat=41.66&lon=-91.53'

# 2. Get a key (free, no card, shown once) at
#    https://developers.smarterweather.com/dashboard/api-keys
#    and put it in .env as SMARTERWEATHER_API_KEY (add .env to .gitignore).

# 3. Call again with the key.
curl -sS 'https://api.smarterweather.com/v1/weather?lat=41.66&lon=-91.53' \
  -H "Authorization: Bearer $SMARTERWEATHER_API_KEY"

The hosted developer portal at https://developers.smarterweather.com is the source of truth for account creation, API key minting, plan management, and usage. Agents whose client speaks MCP can do the same without the dashboard through the onboarding MCP server — see docs/mcp-onboarding.md.

Once you have a key:

# REST API
curl -H "Authorization: Bearer $SMARTERWEATHER_API_KEY" \
  "https://api.smarterweather.com/v1/weather?lat=41.88&lon=-87.63"

# Weather MCP bridge (defaults to https://mcp.smarterweather.com;
# override via SMARTERWEATHER_MCP_URL).
npx -y @smarterweather/mcp-weather --version

The full quickstart with language-specific snippets lives at https://developers.smarterweather.com/quickstart. Agents should start from llms.txt or AGENTS.md.

Getting help

• Bug reports and feature requests -- file an issue on this repo using the templates in the issue chooser.
• API contract questions -- file an issue with the "API contract question" template; these route to the team that owns the public surface.
• General "how do I do X?" questions -- start a thread in Discussions. We prefer Discussions over chat platforms because answers stay searchable.
• Account, billing, or commercial inquiries -- email alex@smarterweather.com or use the contact page.
• Security issues -- see SECURITY.md. Please do not open public issues for security reports.

Roadmap

Smarter Weather built the developer platform in phases; this repo publishes artifacts as each one ships.

The roadmap is published for transparency, not as a commitment. Dates are intentionally omitted -- watch this repository for releases.

Contributing

External contributions are welcome on a tiered basis (typo and small SDK fixes are fast-tracked; new features start with an issue). The OpenAPI specification is read-only -- contract changes route through issues.

See CONTRIBUTING.md for the full posture and the Code of Conduct for community expectations.

License

• Code -- SDKs, examples, the @smarterweather/mcp-weather and @smarterweather/mcp-onboarding package sources, and any agent skills or scaffolding are licensed under the MIT License.
• Documentation and prose -- this README, anything under docs/, and openapi.yaml (when present) are licensed under Creative Commons Attribution 4.0 International.

Where any file's intended license is ambiguous (for example, a tutorial that mixes prose and code samples), assume MIT for the code blocks and CC BY 4.0 for the surrounding prose.

The Smarter Weather hosted APIs and services themselves are governed by separate Terms of Service and Developer Terms at https://smarterweather.com/terms and https://developers.smarterweather.com/legal/terms. This repository contains client-side and documentation artifacts only; access to the hosted APIs requires a separate agreement.

Attribution

Smarter Weather builds on data and software from many providers. See ATTRIBUTION.md for the canonical acknowledgements list.