@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 +1 -1
- package/README.md +416 -105
- package/dist/config/cache.d.ts +29 -0
- package/dist/config/cache.d.ts.map +1 -0
- package/dist/config/cache.js +62 -0
- package/dist/config/cache.js.map +1 -0
- package/dist/index.js +34 -0
- package/dist/index.js.map +1 -1
- package/dist/services/noaa.d.ts +9 -0
- package/dist/services/noaa.d.ts.map +1 -1
- package/dist/services/noaa.js +81 -0
- package/dist/services/noaa.js.map +1 -1
- package/dist/services/openmeteo.d.ts +9 -0
- package/dist/services/openmeteo.d.ts.map +1 -1
- package/dist/services/openmeteo.js +90 -0
- package/dist/services/openmeteo.js.map +1 -1
- package/dist/utils/cache.d.ts +62 -0
- package/dist/utils/cache.d.ts.map +1 -0
- package/dist/utils/cache.js +135 -0
- package/dist/utils/cache.js.map +1 -0
- package/package.json +1 -1
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,153 +1,464 @@
|
|
|
1
|
-
# MCP
|
|
1
|
+
# Weather MCP Server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@dangahagan/weather-mcp)
|
|
4
|
+
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.dgahagan/weather-mcp)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
6
|
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
11
|
+
**No API keys required!** Both NOAA and Open-Meteo APIs are free to use with no authentication needed.
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
## Features
|
|
12
14
|
|
|
13
|
-
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
16
|
-
-
|
|
17
|
-
-
|
|
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
|
-
##
|
|
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
|
-
|
|
28
|
+
### Benefits
|
|
22
29
|
|
|
23
|
-
|
|
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
|
-
|
|
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
|
-
|
|
37
|
+
The cache automatically stores and retrieves weather data with intelligent expiration:
|
|
31
38
|
|
|
32
|
-
|
|
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
|
-
|
|
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
|
-
|
|
47
|
+
Caching is **enabled by default** with sensible settings. To customize:
|
|
40
48
|
|
|
41
49
|
```bash
|
|
42
|
-
#
|
|
43
|
-
|
|
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
|
-
|
|
57
|
+
### Monitoring
|
|
47
58
|
|
|
48
|
-
|
|
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
|
-
|
|
64
|
+
For detailed information about caching architecture and configuration, see [.github/CACHING.md](./.github/CACHING.md).
|
|
51
65
|
|
|
52
|
-
|
|
66
|
+
## Installation
|
|
53
67
|
|
|
54
|
-
|
|
55
|
-
<summary>Alternative: Running a pre-built Docker image</summary>
|
|
68
|
+
### Quick Install (Recommended)
|
|
56
69
|
|
|
57
|
-
|
|
70
|
+
**Via npm:**
|
|
71
|
+
```bash
|
|
72
|
+
npm install -g @dangahagan/weather-mcp
|
|
73
|
+
```
|
|
58
74
|
|
|
75
|
+
**Via npx (no installation):**
|
|
59
76
|
```bash
|
|
60
|
-
|
|
61
|
-
|
|
77
|
+
npx -y @dangahagan/weather-mcp
|
|
78
|
+
```
|
|
62
79
|
|
|
63
|
-
|
|
64
|
-
|
|
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
|
-
|
|
67
|
-
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
|
|
92
|
+
### From Source
|
|
68
93
|
|
|
69
|
-
|
|
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
|
-
**
|
|
74
|
-
-
|
|
75
|
-
-
|
|
76
|
-
- **
|
|
96
|
+
**Prerequisites:**
|
|
97
|
+
- Node.js 18 or higher
|
|
98
|
+
- npm or yarn
|
|
99
|
+
- **No API keys or tokens required**
|
|
77
100
|
|
|
78
|
-
|
|
101
|
+
**Setup:**
|
|
79
102
|
|
|
80
|
-
|
|
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
|
-
|
|
109
|
+
2. Install dependencies:
|
|
110
|
+
```bash
|
|
111
|
+
npm install
|
|
112
|
+
```
|
|
83
113
|
|
|
114
|
+
3. Build the project:
|
|
84
115
|
```bash
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
|
|
89
|
-
|
|
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
|
-
|
|
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
|
-
|
|
347
|
+
## Testing
|
|
95
348
|
|
|
349
|
+
### Quick Test
|
|
350
|
+
|
|
351
|
+
Verify NOAA API connectivity:
|
|
96
352
|
```bash
|
|
97
|
-
|
|
98
|
-
make check
|
|
353
|
+
npx tsx tests/test_noaa_api.ts
|
|
99
354
|
```
|
|
100
355
|
|
|
101
|
-
|
|
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
|
-
|
|
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
|
-
|
|
113
|
-
|
|
114
|
-
βββ
|
|
115
|
-
βββ
|
|
116
|
-
βββ
|
|
117
|
-
|
|
118
|
-
β βββ
|
|
119
|
-
β βββ
|
|
120
|
-
β
|
|
121
|
-
β
|
|
122
|
-
β
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
- **
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
- **
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
-
|
|
145
|
-
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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"}
|