@dangahagan/weather-mcp 0.1.1 β†’ 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 MCP Contributors
3
+ Copyright (c) 2025 Weather MCP Server Contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,153 +1,464 @@
1
- # MCP Registry
1
+ # Weather MCP Server
2
2
 
3
- The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.
3
+ [![npm version](https://badge.fury.io/js/@dangahagan%2Fweather-mcp.svg)](https://www.npmjs.com/package/@dangahagan/weather-mcp)
4
+ [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.dgahagan/weather-mcp)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4
6
 
5
- [**πŸ“€ 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)**
7
+ 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.
6
8
 
7
- ## Development Status
9
+ **πŸ“¦ Available in the [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.dgahagan/weather-mcp)** as `io.github.dgahagan/weather-mcp`
8
10
 
9
- **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!
11
+ **No API keys required!** Both NOAA and Open-Meteo APIs are free to use with no authentication needed.
10
12
 
11
- **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)).
13
+ ## Features
12
14
 
13
- Current key maintainers:
14
- - **Adam Jones** (Anthropic) [@domdomegg](https://github.com/domdomegg)
15
- - **Tadas Antanavicius** (PulseMCP) [@tadasant](https://github.com/tadasant)
16
- - **Toby Padilla** (GitHub) [@toby](https://github.com/toby)
17
- - **Radoslav (Rado) Dimitrov** (Stacklok) [@rdimitrov](https://github.com/rdimitrov)
15
+ - **Get Forecast**: Retrieve weather forecasts for any US location (7-day forecast)
16
+ - **Current Conditions**: Get real-time weather observations for US locations
17
+ - **Historical Data**: Access historical weather observations for any location worldwide
18
+ - Recent data (last 7 days): Detailed hourly observations from NOAA real-time API (US only)
19
+ - Archival data (>7 days old): Hourly/daily weather data from 1940-present via Open-Meteo (global coverage)
20
+ - **Service Status Checking**: Proactively verify API availability with health checks
21
+ - **Enhanced Error Handling**: Detailed, actionable error messages with status page links
22
+ - **Intelligent Caching**: Built-in in-memory cache reduces API calls and improves performance
18
23
 
19
- ## Contributing
24
+ ## Caching
25
+
26
+ The Weather MCP server includes an intelligent in-memory caching system that significantly improves performance for AI-driven weather queries.
20
27
 
21
- We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
28
+ ### Benefits
22
29
 
23
- Often (but not always) ideas flow through this pipeline:
30
+ - **Faster Responses**: Cached queries return in <10ms vs 200-1000ms for API calls
31
+ - **Reduced API Load**: 50-80% fewer API calls for typical AI conversation patterns
32
+ - **Rate Limit Protection**: Prevents hitting API rate limits during heavy usage
33
+ - **Automatic Management**: Smart TTL-based expiration with LRU eviction
24
34
 
25
- - **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
26
- - **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
27
- - **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work
28
- - **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
35
+ ### How It Works
29
36
 
30
- ### Quick start:
37
+ The cache automatically stores and retrieves weather data with intelligent expiration:
31
38
 
32
- #### Pre-requisites
39
+ - **Forecasts**: Cached for 2 hours (updated approximately hourly)
40
+ - **Current Conditions**: Cached for 15 minutes (observations update every 20-60 minutes)
41
+ - **Historical Data (>1 day old)**: Cached indefinitely (finalized data never changes)
42
+ - **Recent Historical (<1 day)**: Cached for 1 hour (may still be updated)
43
+ - **Grid Coordinates**: Cached indefinitely (geographic mappings are static)
33
44
 
34
- - **Docker**
35
- - **Go 1.24.x**
36
- - **ko** - Container image builder for Go ([installation instructions](https://ko.build/install/))
37
- - **golangci-lint v2.4.0**
45
+ ### Configuration
38
46
 
39
- #### Running the server
47
+ Caching is **enabled by default** with sensible settings. To customize:
40
48
 
41
49
  ```bash
42
- # Start full development environment
43
- make dev-compose
50
+ # Disable caching (not recommended)
51
+ export CACHE_ENABLED=false
52
+
53
+ # Adjust maximum cache size (default: 1000 entries)
54
+ export CACHE_MAX_SIZE=1500
44
55
  ```
45
56
 
46
- 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.
57
+ ### Monitoring
47
58
 
48
- **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.
59
+ Use the `check_service_status` tool to view cache statistics including:
60
+ - Hit rate percentage
61
+ - Cache size and utilization
62
+ - API call reduction metrics
49
63
 
50
- 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`.
64
+ For detailed information about caching architecture and configuration, see [.github/CACHING.md](./.github/CACHING.md).
51
65
 
52
- The setup can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
66
+ ## Installation
53
67
 
54
- <details>
55
- <summary>Alternative: Running a pre-built Docker image</summary>
68
+ ### Quick Install (Recommended)
56
69
 
57
- Pre-built Docker images are automatically published to GitHub Container Registry:
70
+ **Via npm:**
71
+ ```bash
72
+ npm install -g @dangahagan/weather-mcp
73
+ ```
58
74
 
75
+ **Via npx (no installation):**
59
76
  ```bash
60
- # Run latest stable release
61
- docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
77
+ npx -y @dangahagan/weather-mcp
78
+ ```
62
79
 
63
- # Run latest from main branch (continuous deployment)
64
- docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main
80
+ Then configure in your MCP client using:
81
+ ```json
82
+ {
83
+ "mcpServers": {
84
+ "weather": {
85
+ "command": "npx",
86
+ "args": ["-y", "@dangahagan/weather-mcp"]
87
+ }
88
+ }
89
+ }
90
+ ```
65
91
 
66
- # Run specific release version
67
- docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
92
+ ### From Source
68
93
 
69
- # Run development build from main branch
70
- docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d
71
- ```
94
+ If you prefer to build from source:
72
95
 
73
- **Available tags:**
74
- - **Releases**: `latest`, `v1.0.0`, `v1.1.0`, etc.
75
- - **Continuous**: `main` (latest main branch build)
76
- - **Development**: `main-<date>-<sha>` (specific commit builds)
96
+ **Prerequisites:**
97
+ - Node.js 18 or higher
98
+ - npm or yarn
99
+ - **No API keys or tokens required**
77
100
 
78
- </details>
101
+ **Setup:**
79
102
 
80
- #### Publishing a server
103
+ 1. Clone the repository:
104
+ ```bash
105
+ git clone https://github.com/dgahagan/weather-mcp.git
106
+ cd weather-mcp
107
+ ```
81
108
 
82
- To publish a server, we've built a simple CLI. You can use it with:
109
+ 2. Install dependencies:
110
+ ```bash
111
+ npm install
112
+ ```
83
113
 
114
+ 3. Build the project:
84
115
  ```bash
85
- # Build the latest CLI
86
- make publisher
116
+ npm run build
117
+ ```
118
+
119
+ ## Usage with AI Assistants
120
+
121
+ This MCP server works with any client that supports the Model Context Protocol, including:
122
+
123
+ - **Claude Desktop** - Official Claude desktop application
124
+ - **Claude Code** - Official Claude CLI tool
125
+ - **Cline** - VS Code extension for AI-assisted coding
126
+ - **Cursor** - AI-powered code editor
127
+ - **Zed** - High-performance code editor with AI features
128
+ - **VS Code (GitHub Copilot)** - With MCP support enabled
129
+ - **LM Studio** - Local AI model interface
130
+ - **Postman** - API platform with MCP integration
131
+
132
+ For detailed setup instructions for each client, see **[CLIENT_SETUP.md](./docs/CLIENT_SETUP.md)**.
133
+
134
+ ### Quick Start: Claude Code
135
+
136
+ Edit `~/.config/claude-code/mcp_settings.json` (macOS/Linux) or `%APPDATA%\claude-code\mcp_settings.json` (Windows):
137
+
138
+ ```json
139
+ {
140
+ "mcpServers": {
141
+ "weather": {
142
+ "command": "node",
143
+ "args": ["/absolute/path/to/weather-mcp/dist/index.js"]
144
+ }
145
+ }
146
+ }
147
+ ```
148
+
149
+ Restart Claude Code and the weather tools will be available.
150
+
151
+ ## Finding Coordinates
152
+
153
+ All tools require latitude and longitude coordinates. You can find coordinates for any location by:
154
+ - Asking Claude Code: "What are the coordinates for [city name]?"
155
+ - Using Google Maps: Right-click a location and select the coordinates
156
+ - Using a geocoding service like geocode.maps.co or nominatim.org
157
+
158
+ ### Common US City Coordinates
159
+
160
+ | City | Latitude | Longitude |
161
+ |------|----------|-----------|
162
+ | San Francisco, CA | 37.7749 | -122.4194 |
163
+ | New York, NY | 40.7128 | -74.0060 |
164
+ | Chicago, IL | 41.8781 | -87.6298 |
165
+ | Los Angeles, CA | 34.0522 | -118.2437 |
166
+ | Denver, CO | 39.7392 | -104.9903 |
167
+ | Miami, FL | 25.7617 | -80.1918 |
168
+ | Seattle, WA | 47.6062 | -122.3321 |
169
+ | Austin, TX | 30.2672 | -97.7431 |
170
+
171
+ ## Available Tools
172
+
173
+ ### 1. check_service_status
174
+ Check the operational status of weather APIs and cache performance.
175
+
176
+ **Parameters:** None
177
+
178
+ **Description:**
179
+ 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, links to official status pages, and cache statistics.
180
+
181
+ **Example:**
182
+ ```
183
+ Check if the weather services are operational
184
+ ```
185
+
186
+ **Returns:**
187
+ - Operational status for NOAA API (forecasts & current conditions)
188
+ - Operational status for Open-Meteo API (historical data)
189
+ - Cache statistics (hit rate, size, API call reduction)
190
+ - Status page links and recommended actions if issues are detected
191
+ - Overall service availability summary
192
+
193
+ ### 2. get_forecast
194
+ Get weather forecast for a location.
195
+
196
+ **Parameters:**
197
+ - `latitude` (required): Latitude coordinate (-90 to 90)
198
+ - `longitude` (required): Longitude coordinate (-180 to 180)
199
+ - `days` (optional): Number of days in forecast (1-7, default: 7)
200
+
201
+ **Example:**
202
+ ```
203
+ Get the weather forecast for San Francisco (latitude: 37.7749, longitude: -122.4194)
204
+ ```
205
+
206
+ ### 3. get_current_conditions
207
+ Get current weather conditions for a location.
208
+
209
+ **Parameters:**
210
+ - `latitude` (required): Latitude coordinate (-90 to 90)
211
+ - `longitude` (required): Longitude coordinate (-180 to 180)
212
+
213
+ **Example:**
214
+ ```
215
+ What are the current weather conditions in New York? (latitude: 40.7128, longitude: -74.0060)
216
+ ```
217
+
218
+ ### 4. get_historical_weather
219
+ Get historical weather observations for a location.
220
+
221
+ **Parameters:**
222
+ - `latitude` (required): Latitude coordinate (-90 to 90)
223
+ - `longitude` (required): Longitude coordinate (-180 to 180)
224
+ - `start_date` (required): Start date in ISO format (YYYY-MM-DD)
225
+ - `end_date` (required): End date in ISO format (YYYY-MM-DD)
226
+ - `limit` (optional): Max observations to return (1-500, default: 168)
227
+
228
+ **Data Source Selection:**
229
+ The server automatically chooses the best data source based on your date range:
230
+
231
+ - **Last 7 days**: Uses NOAA real-time API
232
+ - βœ“ Detailed hourly observations from weather stations
233
+ - βœ“ Includes: temperature, conditions, wind speed, humidity, pressure
234
+ - βœ“ High reliability and availability
235
+ - ⚠️ US locations only
236
+
237
+ - **Older than 7 days**: Uses Open-Meteo Historical Weather API
238
+ - βœ“ No API token required
239
+ - βœ“ Global coverage (worldwide)
240
+ - βœ“ Historical data from 1940 to present
241
+ - βœ“ Hourly data for ranges up to 31 days
242
+ - βœ“ Daily summaries for longer periods
243
+ - βœ“ Includes: temperature, precipitation, wind, humidity, pressure, cloud cover
244
+ - βœ“ High resolution reanalysis data (9-25km grid)
245
+ - ⚠️ 5-day delay for most recent data
246
+
247
+ **Examples:**
248
+
249
+ Recent data (US locations, detailed observations):
250
+ ```
251
+ "What was the weather like in Chicago 3 days ago?"
252
+ Coordinates: latitude: 41.8781, longitude: -87.6298
253
+ Date range: 3 days ago to 2 days ago
254
+ ```
255
+
256
+ Historical data (global coverage):
257
+ ```
258
+ "What was the weather in Paris on January 15, 2024?"
259
+ Coordinates: latitude: 48.8566, longitude: 2.3522
260
+ Date range: 2024-01-15 to 2024-01-15
261
+ ```
262
+
263
+ Long-term historical analysis:
264
+ ```
265
+ "Show me weather data for Tokyo from January 1, 2020 to December 31, 2020"
266
+ Coordinates: latitude: 35.6762, longitude: 139.6503
267
+ Date range: 2020-01-01 to 2020-12-31
268
+ ```
269
+
270
+ **Troubleshooting:**
271
+ If you get "No historical data available":
272
+ - For recent dates (last 7 days): Ensure you're using US coordinates
273
+ - For older dates: Data should be available globally back to 1940
274
+ - Note: Most recent data has a 5-day delay
275
+ - Very recent dates (last 5 days) may not be available in archival data yet
276
+
277
+ ## Error Handling & Service Status
278
+
279
+ ### Enhanced Error Messages
280
+
281
+ This MCP server provides detailed, actionable error messages when issues occur. All error messages include:
282
+
283
+ - **Clear problem description** - What went wrong and why
284
+ - **Contextual help** - Specific guidance based on the error type
285
+ - **Status page links** - Direct links to official service status pages
286
+ - **Recommended actions** - Concrete steps to resolve or investigate the issue
287
+
288
+ **Example Error Messages:**
289
+
290
+ When a service is down:
291
+ ```
292
+ NOAA API server error: Service temporarily unavailable
293
+
294
+ The NOAA Weather API may be experiencing an outage.
87
295
 
88
- # Use it!
89
- ./bin/mcp-publisher --help
296
+ Check service status:
297
+ - Planned outages: https://weather-gov.github.io/api/planned-outages
298
+ - Service notices: https://www.weather.gov/notification
299
+ - Report issues: nco.ops@noaa.gov or (301) 683-1518
90
300
  ```
91
301
 
92
- See [the publisher guide](./docs/guides/publishing/publish-server.md) for more details.
302
+ When rate limited:
303
+ ```
304
+ Open-Meteo API rate limit exceeded (10,000 requests/day for non-commercial use).
305
+
306
+ Please retry later or consider:
307
+ - Reducing request frequency
308
+ - Using daily instead of hourly data for longer periods
309
+ - Upgrading to a commercial plan for higher limits
310
+
311
+ More info: https://open-meteo.com/en/pricing
312
+ ```
313
+
314
+ ### Service Status Checking
315
+
316
+ Use the `check_service_status` tool to proactively verify API availability:
317
+
318
+ ```
319
+ # Query example
320
+ "Check if the weather services are working"
321
+
322
+ # Returns:
323
+ - βœ…/❌ Status for NOAA API (US forecasts & current conditions)
324
+ - βœ…/❌ Status for Open-Meteo API (global historical data)
325
+ - Links to official status pages
326
+ - Recommended actions if issues detected
327
+ - Overall service availability summary
328
+ ```
329
+
330
+ **When to use:**
331
+ - Before making multiple weather requests
332
+ - When experiencing errors or timeouts
333
+ - To verify service availability after an outage
334
+ - For monitoring and alerting purposes
335
+
336
+ **Status Page Links:**
337
+ - **NOAA API:**
338
+ - Planned outages: https://weather-gov.github.io/api/planned-outages
339
+ - Service notices: https://www.weather.gov/notification
340
+ - Report issues: https://weather-gov.github.io/api/reporting-issues
341
+
342
+ - **Open-Meteo API:**
343
+ - Production status: https://open-meteo.com/en/docs/model-updates
344
+ - GitHub issues: https://github.com/open-meteo/open-meteo/issues
345
+ - Documentation: https://open-meteo.com/en/docs
93
346
 
94
- #### Other commands
347
+ ## Testing
95
348
 
349
+ ### Quick Test
350
+
351
+ Verify NOAA API connectivity:
96
352
  ```bash
97
- # Run lint, unit tests and integration tests
98
- make check
353
+ npx tsx tests/test_noaa_api.ts
99
354
  ```
100
355
 
101
- There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
356
+ This runs 5 tests covering all major functionality with real NOAA API calls.
357
+
358
+ ### Manual Testing with Claude Code
359
+
360
+ See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive testing instructions including:
361
+ - Setup steps
362
+ - Test cases for all tools
363
+ - Error handling verification
364
+ - Performance testing
365
+ - Debugging tips
102
366
 
103
- <!--
104
- For Claude and other AI tools: Always prefer make targets over custom commands where possible.
105
- -->
367
+ ## Development
106
368
 
107
- ## Architecture
369
+ ### Available Scripts
370
+
371
+ - `npm run build` - Compile TypeScript to JavaScript
372
+ - `npm run dev` - Run the server in development mode with tsx
373
+ - `npm start` - Run the compiled server
374
+ - `npx tsx tests/test_noaa_api.ts` - Run API connectivity tests
108
375
 
109
376
  ### Project Structure
110
377
 
111
378
  ```
112
- β”œβ”€β”€ cmd/ # Application entry points
113
- β”‚ └── publisher/ # Server publishing tool
114
- β”œβ”€β”€ data/ # Seed data
115
- β”œβ”€β”€ deploy/ # Deployment configuration (Pulumi)
116
- β”œβ”€β”€ docs/ # Documentation
117
- β”œβ”€β”€ internal/ # Private application code
118
- β”‚ β”œβ”€β”€ api/ # HTTP handlers and routing
119
- β”‚ β”œβ”€β”€ auth/ # Authentication (GitHub OAuth, JWT, namespace blocking)
120
- β”‚ β”œβ”€β”€ config/ # Configuration management
121
- β”‚ β”œβ”€β”€ database/ # Data persistence (PostgreSQL)
122
- β”‚ β”œβ”€β”€ service/ # Business logic
123
- β”‚ β”œβ”€β”€ telemetry/ # Metrics and monitoring
124
- β”‚ └── validators/ # Input validation
125
- β”œβ”€β”€ pkg/ # Public packages
126
- β”‚ β”œβ”€β”€ api/ # API types and structures
127
- β”‚ β”‚ └── v0/ # Version 0 API types
128
- β”‚ └── model/ # Data models for server.json
129
- β”œβ”€β”€ scripts/ # Development and testing scripts
130
- β”œβ”€β”€ tests/ # Integration tests
131
- └── tools/ # CLI tools and utilities
132
- └── validate-*.sh # Schema validation tools
133
- ```
134
-
135
- ### Authentication
136
-
137
- Publishing supports multiple authentication methods:
138
- - **GitHub OAuth** - For publishing by logging into GitHub
139
- - **GitHub OIDC** - For publishing from GitHub Actions
140
- - **DNS verification** - For proving ownership of a domain and its subdomains
141
- - **HTTP verification** - For proving ownership of a domain
142
-
143
- The registry validates namespace ownership when publishing. E.g. to publish...:
144
- - `io.github.domdomegg/my-cool-mcp` you must login to GitHub as `domdomegg`, or be in a GitHub Action on domdomegg's repos
145
- - `me.adamjones/my-cool-mcp` you must prove ownership of `adamjones.me` via DNS or HTTP challenge
146
-
147
- ## Community Projects
148
-
149
- Check out [community projects](docs/community-projects.md) to explore notable registry-related work created by the community.
150
-
151
- ## More documentation
152
-
153
- See the [documentation](./docs) for more details if your question has not been answered here!
379
+ weather-mcp/
380
+ β”œβ”€β”€ src/
381
+ β”‚ β”œβ”€β”€ index.ts # Main MCP server
382
+ β”‚ β”œβ”€β”€ services/
383
+ β”‚ β”‚ β”œβ”€β”€ noaa.ts # NOAA real-time API service
384
+ β”‚ β”‚ └── openmeteo.ts # Open-Meteo historical weather API service
385
+ β”‚ β”œβ”€β”€ types/
386
+ β”‚ β”‚ β”œβ”€β”€ noaa.ts # NOAA TypeScript type definitions
387
+ β”‚ β”‚ └── openmeteo.ts # Open-Meteo TypeScript type definitions
388
+ β”‚ └── utils/
389
+ β”‚ └── units.ts # Unit conversion utilities
390
+ β”œβ”€β”€ dist/ # Compiled JavaScript (generated)
391
+ β”œβ”€β”€ tests/ # Test files
392
+ └── package.json
393
+ ```
394
+
395
+ ## API Information
396
+
397
+ This server uses two weather APIs:
398
+
399
+ ### NOAA Weather API (Real-time)
400
+ - **Base URL**: https://api.weather.gov
401
+ - **Authentication**: None required (User-Agent header only)
402
+ - **Rate Limits**: Enforced with 5-second retry window
403
+ - **Coverage**: United States locations only
404
+ - **Use cases**: Forecasts, current conditions, recent observations (last 7 days)
405
+ - **Data**: Detailed hourly observations from weather stations
406
+
407
+ ### Open-Meteo Historical Weather API (Archival)
408
+ - **Base URL**: https://archive-api.open-meteo.com/v1
409
+ - **Authentication**: None required (no API token needed)
410
+ - **Rate Limits**: 10,000 requests/day for non-commercial use
411
+ - **Coverage**: Global (worldwide locations)
412
+ - **Use cases**: Historical weather data from 1940 to present
413
+ - **Data**: Hourly or daily temperature, precipitation, wind, humidity, pressure, cloud cover
414
+ - **Resolution**: 9-25km grid resolution from reanalysis models
415
+ - **Delay**: 5-day delay for most recent data
416
+
417
+ For more details on NOAA APIs, see [NOAA_API_RESEARCH.md](./docs/NOAA_API_RESEARCH.md).
418
+
419
+ ## Limitations
420
+
421
+ ### Geographic Coverage
422
+
423
+ **Forecasts and Current Conditions:**
424
+ - NOAA APIs only cover **United States locations**
425
+ - International locations are not supported for forecasts and current conditions
426
+
427
+ **Historical Data:**
428
+ - Recent data (last 7 days): **US locations only** (NOAA API)
429
+ - Archival data (>7 days old): **Global coverage** (Open-Meteo API)
430
+
431
+ ### Historical Data (get_historical_weather)
432
+
433
+ **Recent Data (Last 7 Days)** - US Only, High Detail:
434
+ - βœ“ Detailed hourly observations from weather stations
435
+ - βœ“ No API token required
436
+ - ⚠️ US locations only
437
+ - ⚠️ May have occasional gaps depending on weather station
438
+ - ⚠️ Observations may be delayed up to 20 minutes
439
+
440
+ **Archival Data (Older than 7 Days)** - Global, Reanalysis-Based:
441
+ - βœ“ Global coverage (any location worldwide)
442
+ - βœ“ No API token required
443
+ - βœ“ Reliable data from 1940 to present
444
+ - βœ“ Hourly data for date ranges up to 31 days
445
+ - βœ“ Daily summaries for longer periods
446
+ - ⚠️ Most recent data has a 5-day delay
447
+ - ⚠️ Reanalysis-based (grid model, not direct station observations)
448
+
449
+ ### Rate Limits
450
+ - **NOAA Weather API**: Automatic retry with exponential backoff on rate limit errors
451
+ - **Open-Meteo API**: 10,000 requests/day for non-commercial use
452
+
453
+ ### Recommendations
454
+ - **For recent US weather**: Use dates within the last 7 days for detailed station observations
455
+ - **For historical analysis**: Open-Meteo provides reliable global coverage back to 1940
456
+ - **For international locations**: Only historical data (>7 days old) is supported
457
+
458
+ ## License
459
+
460
+ MIT
461
+
462
+ ## Contributing
463
+
464
+ Contributions are welcome! Please feel free to submit a Pull Request.
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Cache configuration for weather data
3
+ *
4
+ * TTL (Time To Live) values are set based on data volatility:
5
+ * - Historical data: Never changes once recorded
6
+ * - Geographic data: Static (grid coordinates, station locations)
7
+ * - Forecasts: Updated approximately hourly
8
+ * - Current conditions: Observations typically update every 20-60 minutes
9
+ */
10
+ export declare const CacheConfig: {
11
+ readonly enabled: boolean;
12
+ readonly maxSize: number;
13
+ readonly ttl: {
14
+ readonly gridCoordinates: number;
15
+ readonly stations: number;
16
+ readonly forecast: number;
17
+ readonly currentConditions: number;
18
+ readonly recentHistorical: number;
19
+ readonly historicalData: number;
20
+ readonly serviceStatus: number;
21
+ };
22
+ };
23
+ /**
24
+ * Determine appropriate TTL for historical weather data based on date
25
+ * @param startDate Start date of the historical query
26
+ * @returns TTL in milliseconds
27
+ */
28
+ export declare function getHistoricalDataTTL(startDate: string | Date): number;
29
+ //# sourceMappingURL=cache.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,eAAO,MAAM,WAAW;;;;;;;;;;;;CAqCd,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYrE"}