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

Cursor에 마운트

  1. 빌드합니다(npm run build).

  2. 이 프로젝트에 .cursor/mcp.json을 추가합니다:

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

모든 Cursor 프로젝트에서는 ${workspaceFolder} 대신 %USERPROFILE%\.cursor\mcp.json과 build\index.js의 전체 경로를 사용하세요.

  1. Customize → MCP(또는 Cursor Settings → MCP)를 열고 weather를 활성화합니다.

  2. src/를 변경한 후 npm run build를 다시 실행하고 서버를 껐다 켜서 Cursor가 프로세스를 다시 시작하게 하세요.

서버가 연결된 후에는 console.log를 사용하지 마세요. stdout은 MCP 통신 채널입니다. 로그에는 console.error를 사용하세요.

호출할 수 있는 항목

도구

모델(또는 Agent chat에서 요청한 사용자)은 tools/call로 다음을 호출합니다.

이름

입력

설명

get_alerts

state — 미국 2자리 주 코드(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}(소수점 4자리)을 로드한 다음 properties.forecast 또는 properties.forecastHourly를 따라가세요.

  • NWS는 User-Agent 헤더를 요구합니다(weather-api-call.ts에 설정됨).

  • 적용 범위는 미국(및 일부 속령)입니다. 다른 좌표는 종종 실패합니다.

문제 해결

증상

해결 방법

서버가 빨간색 / 도구 없음

다시 빌드하고 build/index.js가 존재하는지 확인한 후 MCP 토글

핸드셰이크 실패

stdio를 connect했는지 확인하고 stdout에 로그를 남기지 마세요

예보가 비어 있거나 실패

미국 위도/경도만 가능; MCP Logs 확인

npm test 실패

네트워크 / NWS 장애

Cursor: Output → MCP Logs.

라이선스

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.
    -