Skip to main content
Glama
deenesjakoruzh
kingshuknandy2016

weather

by kingshuknandy2016
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mcp-weather-ts

TypeScript MCP 服务器，将 National Weather Service API 中的美国天气数据提供给 Cursor 等宿主。

宿主启动 node build/index.js，并通过 stdio 以 JSON-RPC 进行通信。模型本身不会直接调用 NWS，而是调用该服务器的工具（也可以读取资源或使用提示）。

MCP 工作原理（工具、资源、提示、传输）：docs/create-mcp.readme.md。

环境要求

  • Node.js 22+（本仓库使用 ESM 和 fetch）

  • npm

  • 可访问 https://api.weather.gov 的网络（仅限美国地区）

Related MCP server: weather

设置

npm install
npm run build

tsc 会将 JavaScript 写入 build/。Cursor 必须运行构建后的文件，而不是 src/index.ts。

脚本

命令

作用

npm run build

将 src/ 编译到 build/

npm test

对 NWS 做冒烟测试：访问 /points，然后访问预报 URL 和逐小时预报 URL

在 Cursor 中挂载

  1. 构建（npm run build）。

  2. 在本项目中添加 .cursor/mcp.json：

{
  "mcpServers": {
    "weather": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/build/index.js"]
    }
  }
}

对于所有 Cursor 项目，请使用 %USERPROFILE%\.cursor\mcp.json 以及 build\index.js 的完整路径，而不是 ${workspaceFolder}。

  1. 打开自定义 → MCP（或 Cursor 设置 → MCP）并启用 weather。

  2. 修改 src/ 后，再次运行 npm run build，并将服务器关闭再打开，以便 Cursor 重启该进程。

服务器连接后，请勿使用 console.log：stdout 是 MCP 的通信通道。日志请使用 console.error。

你可以调用什么

工具

模型（或你在 Agent 聊天中提问）通过 tools/call 调用以下工具。

名称

输入

作用

get_alerts

state — 两位美国州代码（CA、NY）

该州的生效警报

get_forecast

latitude、longitude

12 小时预报（NWS 先访问 /points，再访问 properties.forecast）

test_tool

name

练习：Hello, {name}!

聊天示例：

  • “CA 有什么天气警报吗？”

  • “39.7456, -97.0892 的预报”

参数示例：

{ "state": "CA" }
{ "latitude": 39.7456, "longitude": -97.0892 }

资源

名称

URI

作用

nws_guide

weather://nws-guide

关于工具和 NWS 查询流程的简短静态说明

请让智能体读取 weather://nws-guide，或在客户端中使用 resources/read。

提示

名称

参数

作用

check_weather

place — 例如 Boston MA 或 CA

用户消息模板，指示模型使用 get_forecast / get_alerts

在 Cursor 中，选择 Check weather 提示并填写 place。

项目结构

src/index.ts              Create McpServer, register, connect stdio
src/tools.ts              get_alerts, get_forecast, test_tool
src/resources.ts          weather://nws-guide
src/prompts.ts            check_weather
src/weather-api-call.ts   NWS fetch + types + alert formatting
src/createTransport.ts    StdioServerTransport + connect
tests/weather-api-call.test.ts
docs/create-mcp.readme.md How to design MCP servers

src/index.ts 中的启动顺序：

  1. new McpServer({ name: "weather", version: "1.0.0" })

  2. registerWeatherTools / registerWeatherResources / registerWeatherPrompts

  3. connectStdioTransport(server)

NWS 说明

  • 预报并不位于 /points/{lat},{lon}/forecast。请先加载 /points/{lat},{lon}（保留四位小数），然后再访问 properties.forecast 或 properties.forecastHourly。

  • NWS 要求提供 User-Agent 请求头（已在 weather-api-call.ts 中设置）。

  • 覆盖范围为美国（及部分领地）。其他坐标通常会失败。

故障排查

症状

尝试方法

服务器红色 / 没有工具

重新构建，确认 build/index.js 存在，切换 MCP 开关

握手失败

确保你已 connect stdio，且不要向 stdout 写日志

预报为空或失败

仅支持美国经纬度；查看 MCP 日志

npm test 失败

网络 / NWS 故障

Cursor：输出 → MCP 日志。

许可证

ISC

Available Tools

3 tools
get_alertsWeather AlertsB

Get weather alerts for a US state

ParametersJSON Schema
NameRequiredDescriptionDefault
stateYesTwo-letter state code (e.g. CA, NY)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description alone must carry behavioral disclosure. It only says 'get', which suggests a read-only operation, but it does not state whether any side effects occur, whether auth is required, rate limits, or what happens on error. For a simple getter, this is a notable gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is front-loaded with the core action and object. While it is brief, it is efficient and avoids fluff, earning a high score for conciseness without sacrificing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description provides a minimal but adequate foundation. It does not describe the return format or any special conditions, but for a straightforward alert retrieval, the current description may suffice. However, it could be improved by mentioning that it returns a list of alerts or any date relevance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers the single parameter fully: 'Two-letter state code (e.g. CA, NY)' with length constraints. The description adds no additional meaning beyond what the schema provides. With 100% schema description coverage, the baseline of 3 is appropriate; the description does not enhance understanding of the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb 'get' and the resource 'weather alerts for a US state', which clearly distinguishes it from sibling tools (get_forecast for forecasts, test_tool for testing). It is specific about the domain (weather) and geographic scope (US state), so an agent can understand the primary function without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for any US state but does not explicitly contrast with get_forecast or mention any alternatives. There is no explicit when-not-to-use guidance or relationship to siblings. However, the context of 'US state' implies the parameter scope, so usage is reasonably clear but leaves room for ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_forecastWeather ForecastC

Get weather forecast for a location

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYesLatitude of the location
longitudeYesLongitude of the location

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Get', implying a read-only operation, but does not mention what the forecast contains, whether authentication is required, potential rate limits, or the format of the response. The lack of any behavioral details beyond the obvious is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is front-loaded with the core action. While it is appropriately concise, it is also so minimal that it misses opportunities to add value through structure, such as listing key output or usage notes. Overall, it is concise but not optimally informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, annotations, and any additional description, the tool is incomplete for an agent to call it correctly. There is no indication of what the forecast data looks like, how to interpret the response, or any caveats about precision or coverage. For a simple tool with two parameters, the description should at least mention typical return fields (e.g., temperature, conditions) to provide sufficient context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the schema documenting latitude and longitude ranges and simple descriptions. The tool description adds nothing beyond the schema, but since the schema already defines both parameters adequately, a baseline score of 3 is appropriate. No additional semantic meaning is supplied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'weather forecast', which is specific and unambiguous. However, it does not differentiate from the sibling tool get_alerts, which might also relate to weather, leaving some ambiguity about the precise distinction between forecast and alert retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus get_alerts or test_tool. The description provides no context about conditions that would make this tool preferable, nor any exclusion criteria or alternative suggestions. The agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

test_toolTest ToolD

Test tool

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the person to greet

TDQS

D1.6/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It says nothing about side effects, return values, or operational details, offering no insight beyond the tool's existence. This is a complete failure to convey behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While the description is short (one word), this is under-specification rather than conciseness. It lacks any substantive content, so while it is minimal, it does not earn credit for efficient wording because it provides no value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter, the description is grossly incomplete. It omits the purpose, expected behavior, output, and any conditions or prerequisites. Even with a well-documented schema, the tool cannot be used correctly without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the 'name' parameter is described as 'The name of the person to greet'), so per the rubric the baseline is 3. The description adds no additional parameter semantics, but the schema already documents the parameter adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tautological: description restates name/title.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the siblings (get_alerts, get_forecast). The description gives no context, no conditions, and no exclusions, leaving the agent with zero direction on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedget_alerts
    • First observedget_forecast
    • First observedtest_tool
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.4/5.0

Scored across 3 tools

Disambiguation4/5

get_alerts and get_forecast are clearly distinct in purpose, but test_tool is ambiguous and could be mistaken for a generic utility, though it doesn't overlap with the weather tools. An agent can easily differentiate the two weather tools, and test_tool is separate enough to avoid confusion.

Naming Consistency3/5

Two tools follow a consistent 'get_<noun>' pattern (get_alerts, get_forecast), but test_tool breaks this convention with a different verb and structure. The naming is still readable, but the inconsistency is noticeable given only three tools.

Tool Count3/5

Three tools is borderline for a weather server, which typically needs more operations like current conditions or location search. The presence of test_tool, which does not serve a core weather purpose, makes the count feel less purposeful and slightly thin.

Completeness2/5

The server covers alerts and forecasts but lacks fundamental weather operations like current conditions or historical data. The test_tool is irrelevant to the domain, leaving notable gaps that would require agents to work around missing functionality.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • weather

    qurioskill
    F
    license
    C
    quality
    C
    maintenance
    Exposes US weather data as MCP tools, resources, and prompts via the National Weather Service API, enabling clients like Claude Desktop to get alerts, forecasts, and weather briefings.
    2
    1
    -

  • Weather MCP Demo

    huanhuang1
    F
    license
    Not graded
    quality
    C
    maintenance
    This MCP server provides tools to get current weather, forecasts, and weather alerts from the US National Weather Service via REST APIs, enabling AI agents to query live weather data.
    1
    -

  • Weather MCP Server

    Krishna-Dhawangale
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables natural-language weather queries for U.S. states and coordinates, returning real-time alerts and forecasts from the National Weather Service API via MCP tools.
    -