@dangahagan/weather-mcp 0.1.0 → 0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Weather MCP Server Contributors
+Copyright (c) 2025 MCP Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,414 +1,153 @@
-# Weather MCP Server
+# MCP Registry
 
-An MCP (Model Context Protocol) server that provides weather data to AI systems like Claude Code. Uses NOAA's API for US weather forecasts and current conditions, plus Open-Meteo for global historical weather data.
+The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.
 
-**No API keys required!** Both NOAA and Open-Meteo APIs are free to use with no authentication needed.
+[**📤 Publish my MCP server**](docs/guides/publishing/publish-server.md) | [**⚡️ Live API docs**](https://registry.modelcontextprotocol.io/docs) | [**👀 Ecosystem vision**](docs/explanations/ecosystem-vision.md) | 📖 **[Full documentation](./docs)**
 
-## Features
+## Development Status
 
-- **Get Forecast**: Retrieve weather forecasts for any US location (7-day forecast)
-- **Current Conditions**: Get real-time weather observations for US locations
-- **Historical Data**: Access historical weather observations for any location worldwide
-  - Recent data (last 7 days): Detailed hourly observations from NOAA real-time API (US only)
-  - Archival data (>7 days old): Hourly/daily weather data from 1940-present via Open-Meteo (global coverage)
-- **Service Status Checking**: Proactively verify API availability with health checks
-- **Enhanced Error Handling**: Detailed, actionable error messages with status page links
+**2025-10-24 update**: The Registry API has entered an **API freeze (v0.1)** 🎉. For the next month or more, the API will remain stable with no breaking changes, allowing integrators to confidently implement support. This freeze applies to v0.1 while development continues on v0. We'll use this period to validate the API in real-world integrations and gather feedback to shape v1 for general availability. Thank you to everyone for your contributions and patience—your involvement has been key to getting us here!
 
-## Installation
+**2025-09-08 update**: The registry has launched in preview 🎉 ([announcement blog post](https://blog.modelcontextprotocol.io/posts/2025-09-08-mcp-registry-preview/)). While the system is now more stable, this is still a preview release and breaking changes or data resets may occur. A general availability (GA) release will follow later. We'd love your feedback in [GitHub discussions](https://github.com/modelcontextprotocol/registry/discussions/new?category=ideas) or in the [#registry-dev Discord](https://discord.com/channels/1358869848138059966/1369487942862504016) ([joining details here](https://modelcontextprotocol.io/community/communication)).
 
-### Quick Install (Recommended)
+Current key maintainers:
+- **Adam Jones** (Anthropic) [@domdomegg](https://github.com/domdomegg)  
+- **Tadas Antanavicius** (PulseMCP) [@tadasant](https://github.com/tadasant)
+- **Toby Padilla** (GitHub) [@toby](https://github.com/toby)
+- **Radoslav (Rado) Dimitrov** (Stacklok) [@rdimitrov](https://github.com/rdimitrov)
 
-**Via npm:**
-```bash
-npm install -g weather-mcp
-```
+## Contributing
 
-**Via npx (no installation):**
-```bash
-npx -y weather-mcp
-```
+We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
 
-Then configure in your MCP client using:
-```json
-{
-  "mcpServers": {
-    "weather": {
-      "command": "npx",
-      "args": ["-y", "weather-mcp"]
-    }
-  }
-}
-```
+Often (but not always) ideas flow through this pipeline:
 
-### From Source
+- **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
+- **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
+- **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work  
+- **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
 
-If you prefer to build from source:
+### Quick start:
 
-**Prerequisites:**
-- Node.js 18 or higher
-- npm or yarn
-- **No API keys or tokens required**
+#### Pre-requisites
 
-**Setup:**
+- **Docker**
+- **Go 1.24.x**
+- **ko** - Container image builder for Go ([installation instructions](https://ko.build/install/))
+- **golangci-lint v2.4.0**
 
-1. Clone the repository:
-```bash
-git clone https://github.com/dgahagan/weather-mcp.git
-cd weather-mcp
-```
-
-2. Install dependencies:
-```bash
-npm install
-```
+#### Running the server
 
-3. Build the project:
 ```bash
-npm run build
-```
-
-## Usage with AI Assistants
-
-This MCP server works with any client that supports the Model Context Protocol, including:
-
-- **Claude Desktop** - Official Claude desktop application
-- **Claude Code** - Official Claude CLI tool
-- **Cline** - VS Code extension for AI-assisted coding
-- **Cursor** - AI-powered code editor
-- **Zed** - High-performance code editor with AI features
-- **VS Code (GitHub Copilot)** - With MCP support enabled
-- **LM Studio** - Local AI model interface
-- **Postman** - API platform with MCP integration
-
-For detailed setup instructions for each client, see **[CLIENT_SETUP.md](./docs/CLIENT_SETUP.md)**.
-
-### Quick Start: Claude Code
-
-Edit `~/.config/claude-code/mcp_settings.json` (macOS/Linux) or `%APPDATA%\claude-code\mcp_settings.json` (Windows):
-
-```json
-{
-  "mcpServers": {
-    "weather": {
-      "command": "node",
-      "args": ["/absolute/path/to/weather-mcp/dist/index.js"]
-    }
-  }
-}
-```
-
-Restart Claude Code and the weather tools will be available.
-
-## Finding Coordinates
-
-All tools require latitude and longitude coordinates. You can find coordinates for any location by:
-- Asking Claude Code: "What are the coordinates for [city name]?"
-- Using Google Maps: Right-click a location and select the coordinates
-- Using a geocoding service like geocode.maps.co or nominatim.org
-
-### Common US City Coordinates
-
-| City | Latitude | Longitude |
-|------|----------|-----------|
-| San Francisco, CA | 37.7749 | -122.4194 |
-| New York, NY | 40.7128 | -74.0060 |
-| Chicago, IL | 41.8781 | -87.6298 |
-| Los Angeles, CA | 34.0522 | -118.2437 |
-| Denver, CO | 39.7392 | -104.9903 |
-| Miami, FL | 25.7617 | -80.1918 |
-| Seattle, WA | 47.6062 | -122.3321 |
-| Austin, TX | 30.2672 | -97.7431 |
-
-## Available Tools
-
-### 1. check_service_status
-Check the operational status of weather APIs.
-
-**Parameters:** None
-
-**Description:**
-Performs health checks on both NOAA and Open-Meteo APIs to verify they are operational. Use this tool when experiencing errors or to proactively verify service availability before making weather data requests. Returns current status, helpful messages, and links to official status pages.
-
-**Example:**
-```
-Check if the weather services are operational
-```
-
-**Returns:**
-- Operational status for NOAA API (forecasts & current conditions)
-- Operational status for Open-Meteo API (historical data)
-- Status page links and recommended actions if issues are detected
-- Overall service availability summary
-
-### 2. get_forecast
-Get weather forecast for a location.
-
-**Parameters:**
-- `latitude` (required): Latitude coordinate (-90 to 90)
-- `longitude` (required): Longitude coordinate (-180 to 180)
-- `days` (optional): Number of days in forecast (1-7, default: 7)
-
-**Example:**
-```
-Get the weather forecast for San Francisco (latitude: 37.7749, longitude: -122.4194)
-```
-
-### 3. get_current_conditions
-Get current weather conditions for a location.
-
-**Parameters:**
-- `latitude` (required): Latitude coordinate (-90 to 90)
-- `longitude` (required): Longitude coordinate (-180 to 180)
-
-**Example:**
-```
-What are the current weather conditions in New York? (latitude: 40.7128, longitude: -74.0060)
+# Start full development environment
+make dev-compose
 ```
 
-### 4. get_historical_weather
-Get historical weather observations for a location.
-
-**Parameters:**
-- `latitude` (required): Latitude coordinate (-90 to 90)
-- `longitude` (required): Longitude coordinate (-180 to 180)
-- `start_date` (required): Start date in ISO format (YYYY-MM-DD)
-- `end_date` (required): End date in ISO format (YYYY-MM-DD)
-- `limit` (optional): Max observations to return (1-500, default: 168)
-
-**Data Source Selection:**
-The server automatically chooses the best data source based on your date range:
-
-- **Last 7 days**: Uses NOAA real-time API
-  - ✓ Detailed hourly observations from weather stations
-  - ✓ Includes: temperature, conditions, wind speed, humidity, pressure
-  - ✓ High reliability and availability
-  - ⚠️ US locations only
-
-- **Older than 7 days**: Uses Open-Meteo Historical Weather API
-  - ✓ No API token required
-  - ✓ Global coverage (worldwide)
-  - ✓ Historical data from 1940 to present
-  - ✓ Hourly data for ranges up to 31 days
-  - ✓ Daily summaries for longer periods
-  - ✓ Includes: temperature, precipitation, wind, humidity, pressure, cloud cover
-  - ✓ High resolution reanalysis data (9-25km grid)
-  - ⚠️ 5-day delay for most recent data
-
-**Examples:**
-
-Recent data (US locations, detailed observations):
-```
-"What was the weather like in Chicago 3 days ago?"
-Coordinates: latitude: 41.8781, longitude: -87.6298
-Date range: 3 days ago to 2 days ago
-```
+This starts the registry at [`localhost:8080`](http://localhost:8080) with PostgreSQL. The database uses ephemeral storage and is reset each time you restart the containers, ensuring a clean state for development and testing.
 
-Historical data (global coverage):
-```
-"What was the weather in Paris on January 15, 2024?"
-Coordinates: latitude: 48.8566, longitude: 2.3522
-Date range: 2024-01-15 to 2024-01-15
-```
+**Note:** The registry uses [ko](https://ko.build) to build container images. The `make dev-compose` command automatically builds the registry image with ko and loads it into your local Docker daemon before starting the services.
 
-Long-term historical analysis:
-```
-"Show me weather data for Tokyo from January 1, 2020 to December 31, 2020"
-Coordinates: latitude: 35.6762, longitude: 139.6503
-Date range: 2020-01-01 to 2020-12-31
-```
+By default, the registry seeds from the production API with a filtered subset of servers (to keep startup fast). This ensures your local environment mirrors production behavior and all seed data passes validation. For offline development you can seed from a file without validation with `MCP_REGISTRY_SEED_FROM=data/seed.json MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION=false make dev-compose`.
 
-**Troubleshooting:**
-If you get "No historical data available":
-- For recent dates (last 7 days): Ensure you're using US coordinates
-- For older dates: Data should be available globally back to 1940
-- Note: Most recent data has a 5-day delay
-- Very recent dates (last 5 days) may not be available in archival data yet
+The setup can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
 
-## Error Handling & Service Status
+<details>
+<summary>Alternative: Running a pre-built Docker image</summary>
 
-### Enhanced Error Messages
+Pre-built Docker images are automatically published to GitHub Container Registry:
 
-This MCP server provides detailed, actionable error messages when issues occur. All error messages include:
+```bash
+# Run latest stable release
+docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
 
-- **Clear problem description** - What went wrong and why
-- **Contextual help** - Specific guidance based on the error type
-- **Status page links** - Direct links to official service status pages
-- **Recommended actions** - Concrete steps to resolve or investigate the issue
+# Run latest from main branch (continuous deployment)
+docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main
 
-**Example Error Messages:**
+# Run specific release version
+docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
 
-When a service is down:
+# Run development build from main branch
+docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d
 ```
-NOAA API server error: Service temporarily unavailable
 
-The NOAA Weather API may be experiencing an outage.
+**Available tags:** 
+- **Releases**: `latest`, `v1.0.0`, `v1.1.0`, etc.
+- **Continuous**: `main` (latest main branch build)
+- **Development**: `main-<date>-<sha>` (specific commit builds)
 
-Check service status:
-- Planned outages: https://weather-gov.github.io/api/planned-outages
-- Service notices: https://www.weather.gov/notification
-- Report issues: nco.ops@noaa.gov or (301) 683-1518
-```
+</details>
 
-When rate limited:
-```
-Open-Meteo API rate limit exceeded (10,000 requests/day for non-commercial use).
+#### Publishing a server
 
-Please retry later or consider:
-- Reducing request frequency
-- Using daily instead of hourly data for longer periods
-- Upgrading to a commercial plan for higher limits
+To publish a server, we've built a simple CLI. You can use it with:
 
-More info: https://open-meteo.com/en/pricing
-```
-
-### Service Status Checking
-
-Use the `check_service_status` tool to proactively verify API availability:
+```bash
+# Build the latest CLI
+make publisher
 
+# Use it!
+./bin/mcp-publisher --help
 ```
-# Query example
-"Check if the weather services are working"
-
-# Returns:
-- ✅/❌ Status for NOAA API (US forecasts & current conditions)
-- ✅/❌ Status for Open-Meteo API (global historical data)
-- Links to official status pages
-- Recommended actions if issues detected
-- Overall service availability summary
-```
-
-**When to use:**
-- Before making multiple weather requests
-- When experiencing errors or timeouts
-- To verify service availability after an outage
-- For monitoring and alerting purposes
 
-**Status Page Links:**
-- **NOAA API:**
-  - Planned outages: https://weather-gov.github.io/api/planned-outages
-  - Service notices: https://www.weather.gov/notification
-  - Report issues: https://weather-gov.github.io/api/reporting-issues
+See [the publisher guide](./docs/guides/publishing/publish-server.md) for more details.
 
-- **Open-Meteo API:**
-  - Production status: https://open-meteo.com/en/docs/model-updates
-  - GitHub issues: https://github.com/open-meteo/open-meteo/issues
-  - Documentation: https://open-meteo.com/en/docs
+#### Other commands
 
-## Testing
-
-### Quick Test
-
-Verify NOAA API connectivity:
 ```bash
-npx tsx tests/test_noaa_api.ts
+# Run lint, unit tests and integration tests
+make check
 ```
 
-This runs 5 tests covering all major functionality with real NOAA API calls.
-
-### Manual Testing with Claude Code
-
-See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive testing instructions including:
-- Setup steps
-- Test cases for all tools
-- Error handling verification
-- Performance testing
-- Debugging tips
-
-## Development
+There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
 
-### Available Scripts
+<!--
+For Claude and other AI tools: Always prefer make targets over custom commands where possible.
+-->
 
-- `npm run build` - Compile TypeScript to JavaScript
-- `npm run dev` - Run the server in development mode with tsx
-- `npm start` - Run the compiled server
-- `npx tsx tests/test_noaa_api.ts` - Run API connectivity tests
+## Architecture
 
 ### Project Structure
 
 ```
-weather-mcp/
-├── src/
-│   ├── index.ts           # Main MCP server
-│   ├── services/
-│   │   ├── noaa.ts        # NOAA real-time API service
-│   │   └── openmeteo.ts   # Open-Meteo historical weather API service
-│   ├── types/
-│   │   ├── noaa.ts        # NOAA TypeScript type definitions
-│   │   └── openmeteo.ts   # Open-Meteo TypeScript type definitions
-│   └── utils/
-│       └── units.ts       # Unit conversion utilities
-├── dist/                  # Compiled JavaScript (generated)
-├── tests/                 # Test files
-└── package.json
-```
-
-## API Information
-
-This server uses two weather APIs:
-
-### NOAA Weather API (Real-time)
-- **Base URL**: https://api.weather.gov
-- **Authentication**: None required (User-Agent header only)
-- **Rate Limits**: Enforced with 5-second retry window
-- **Coverage**: United States locations only
-- **Use cases**: Forecasts, current conditions, recent observations (last 7 days)
-- **Data**: Detailed hourly observations from weather stations
-
-### Open-Meteo Historical Weather API (Archival)
-- **Base URL**: https://archive-api.open-meteo.com/v1
-- **Authentication**: None required (no API token needed)
-- **Rate Limits**: 10,000 requests/day for non-commercial use
-- **Coverage**: Global (worldwide locations)
-- **Use cases**: Historical weather data from 1940 to present
-- **Data**: Hourly or daily temperature, precipitation, wind, humidity, pressure, cloud cover
-- **Resolution**: 9-25km grid resolution from reanalysis models
-- **Delay**: 5-day delay for most recent data
-
-For more details on NOAA APIs, see [NOAA_API_RESEARCH.md](./docs/NOAA_API_RESEARCH.md).
-
-## Limitations
-
-### Geographic Coverage
-
-**Forecasts and Current Conditions:**
-- NOAA APIs only cover **United States locations**
-- International locations are not supported for forecasts and current conditions
-
-**Historical Data:**
-- Recent data (last 7 days): **US locations only** (NOAA API)
-- Archival data (>7 days old): **Global coverage** (Open-Meteo API)
-
-### Historical Data (get_historical_weather)
-
-**Recent Data (Last 7 Days)** - US Only, High Detail:
-- ✓ Detailed hourly observations from weather stations
-- ✓ No API token required
-- ⚠️ US locations only
-- ⚠️ May have occasional gaps depending on weather station
-- ⚠️ Observations may be delayed up to 20 minutes
-
-**Archival Data (Older than 7 Days)** - Global, Reanalysis-Based:
-- ✓ Global coverage (any location worldwide)
-- ✓ No API token required
-- ✓ Reliable data from 1940 to present
-- ✓ Hourly data for date ranges up to 31 days
-- ✓ Daily summaries for longer periods
-- ⚠️ Most recent data has a 5-day delay
-- ⚠️ Reanalysis-based (grid model, not direct station observations)
-
-### Rate Limits
-- **NOAA Weather API**: Automatic retry with exponential backoff on rate limit errors
-- **Open-Meteo API**: 10,000 requests/day for non-commercial use
-
-### Recommendations
-- **For recent US weather**: Use dates within the last 7 days for detailed station observations
-- **For historical analysis**: Open-Meteo provides reliable global coverage back to 1940
-- **For international locations**: Only historical data (>7 days old) is supported
-
-## License
-
-MIT
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
+├── cmd/                     # Application entry points
+│   └── publisher/           # Server publishing tool
+├── data/                    # Seed data
+├── deploy/                  # Deployment configuration (Pulumi)
+├── docs/                    # Documentation
+├── internal/                # Private application code
+│   ├── api/                 # HTTP handlers and routing
+│   ├── auth/                # Authentication (GitHub OAuth, JWT, namespace blocking)
+│   ├── config/              # Configuration management
+│   ├── database/            # Data persistence (PostgreSQL)
+│   ├── service/             # Business logic
+│   ├── telemetry/           # Metrics and monitoring
+│   └── validators/          # Input validation
+├── pkg/                     # Public packages
+│   ├── api/                 # API types and structures
+│   │   └── v0/              # Version 0 API types
+│   └── model/               # Data models for server.json
+├── scripts/                 # Development and testing scripts
+├── tests/                   # Integration tests
+└── tools/                   # CLI tools and utilities
+    └── validate-*.sh        # Schema validation tools
+```
+
+### Authentication
+
+Publishing supports multiple authentication methods:
+- **GitHub OAuth** - For publishing by logging into GitHub
+- **GitHub OIDC** - For publishing from GitHub Actions
+- **DNS verification** - For proving ownership of a domain and its subdomains
+- **HTTP verification** - For proving ownership of a domain
+
+The registry validates namespace ownership when publishing. E.g. to publish...:
+- `io.github.domdomegg/my-cool-mcp` you must login to GitHub as `domdomegg`, or be in a GitHub Action on domdomegg's repos
+- `me.adamjones/my-cool-mcp` you must prove ownership of `adamjones.me` via DNS or HTTP challenge
+
+## Community Projects
+
+Check out [community projects](docs/community-projects.md) to explore notable registry-related work created by the community.
+
+## More documentation
+
+See the [documentation](./docs) for more details if your question has not been answered here!

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@dangahagan/weather-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP (Model Context Protocol) server providing weather data from NOAA and Open-Meteo APIs. Supports forecasts, current conditions, and historical weather data (1940-present) with no API keys required.",
+  "mcpName": "io.github.dgahagan/weather-mcp",
   "main": "dist/index.js",
   "type": "module",
   "bin": {