@dangahagan/weather-mcp 0.1.1 → 0.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 MCP Contributors
+Copyright (c) 2025 Weather MCP Server 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,153 +1,420 @@
-# MCP Registry
+# Weather MCP Server
 
-The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.
+[![npm version](https://badge.fury.io/js/@dangahagan%2Fweather-mcp.svg)](https://www.npmjs.com/package/@dangahagan/weather-mcp)
+[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.dgahagan/weather-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-[**📤 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)**
+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.
 
-## Development Status
+**📦 Available in the [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.dgahagan/weather-mcp)** as `io.github.dgahagan/weather-mcp`
 
-**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!
+**No API keys required!** Both NOAA and Open-Meteo APIs are free to use with no authentication needed.
 
-**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)).
+## Features
 
-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)
+- **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
 
-## Contributing
+## Installation
 
-We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
+### Quick Install (Recommended)
 
-Often (but not always) ideas flow through this pipeline:
+**Via npm:**
+```bash
+npm install -g @dangahagan/weather-mcp
+```
 
-- **[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
+**Via npx (no installation):**
+```bash
+npx -y @dangahagan/weather-mcp
+```
 
-### Quick start:
+Then configure in your MCP client using:
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "npx",
+      "args": ["-y", "@dangahagan/weather-mcp"]
+    }
+  }
+}
+```
 
-#### Pre-requisites
+### From Source
 
-- **Docker**
-- **Go 1.24.x**
-- **ko** - Container image builder for Go ([installation instructions](https://ko.build/install/))
-- **golangci-lint v2.4.0**
+If you prefer to build from source:
 
-#### Running the server
+**Prerequisites:**
+- Node.js 18 or higher
+- npm or yarn
+- **No API keys or tokens required**
 
+**Setup:**
+
+1. Clone the repository:
 ```bash
-# Start full development environment
-make dev-compose
+git clone https://github.com/dgahagan/weather-mcp.git
+cd weather-mcp
 ```
 
-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.
+2. Install dependencies:
+```bash
+npm install
+```
 
-**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.
+3. Build the project:
+```bash
+npm run build
+```
 
-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`.
+## Usage with AI Assistants
 
-The setup can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
+This MCP server works with any client that supports the Model Context Protocol, including:
 
-<details>
-<summary>Alternative: Running a pre-built Docker image</summary>
+- **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
 
-Pre-built Docker images are automatically published to GitHub Container Registry:
+For detailed setup instructions for each client, see **[CLIENT_SETUP.md](./docs/CLIENT_SETUP.md)**.
 
-```bash
-# Run latest stable release
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
+### 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
 
-# Run latest from main branch (continuous deployment)
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main
+### 1. check_service_status
+Check the operational status of weather APIs.
 
-# Run specific release version
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
+**Parameters:** None
 
-# Run development build from main branch
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d
+**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
 ```
 
-**Available tags:** 
-- **Releases**: `latest`, `v1.0.0`, `v1.1.0`, etc.
-- **Continuous**: `main` (latest main branch build)
-- **Development**: `main-<date>-<sha>` (specific commit builds)
+**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.
 
-</details>
+**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)
 
-#### Publishing a server
+**Example:**
+```
+Get the weather forecast for San Francisco (latitude: 37.7749, longitude: -122.4194)
+```
 
-To publish a server, we've built a simple CLI. You can use it with:
+### 3. get_current_conditions
+Get current weather conditions for a location.
 
-```bash
-# Build the latest CLI
-make publisher
+**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)
+```
+
+### 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
+```
+
+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
+```
+
+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
+```
+
+**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
+
+## Error Handling & Service Status
+
+### Enhanced Error Messages
 
-# Use it!
-./bin/mcp-publisher --help
+This MCP server provides detailed, actionable error messages when issues occur. All error messages include:
+
+- **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
+
+**Example Error Messages:**
+
+When a service is down:
+```
+NOAA API server error: Service temporarily unavailable
+
+The NOAA Weather API may be experiencing an outage.
+
+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
+```
+
+When rate limited:
+```
+Open-Meteo API rate limit exceeded (10,000 requests/day for non-commercial use).
+
+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
+
+More info: https://open-meteo.com/en/pricing
 ```
 
-See [the publisher guide](./docs/guides/publishing/publish-server.md) for more details.
+### Service Status Checking
 
-#### Other commands
+Use the `check_service_status` tool to proactively verify API availability:
 
+```
+# 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
+
+- **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
+
+## Testing
+
+### Quick Test
+
+Verify NOAA API connectivity:
 ```bash
-# Run lint, unit tests and integration tests
-make check
+npx tsx tests/test_noaa_api.ts
 ```
 
-There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
+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
 
-<!--
-For Claude and other AI tools: Always prefer make targets over custom commands where possible.
--->
+## Development
 
-## Architecture
+### Available Scripts
+
+- `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
 
 ### Project Structure
 
 ```
-├── 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!
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangahagan/weather-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",