Skip to main content
Glama
wcnm8888

io.github.wcnm8888/mcp1-weather-query

by wcnm8888
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

MCP1-天气查询

一个用于学习 MCP Server 设计、stdio 调试、结构化 Tool 输出、测试、打包与发布流程的 Python 小项目。项目将复现 Datawhale《第十章 智能体通信协议》的天气案例，但以 2026-07-28 MCP 规范和当前官方 Python SDK 为基线，不直接复制教程中的旧封装、数据源或发布叙述。

当前状态

  • 项目类型：启动新项目。

  • 项目整体等级：M；规划、roadmap 和执行基线已完成。

  • 本地打包能力：项目可生成并审查 wheel/sdist，也已在两个项目外独立环境完成无 PYTHONPATH 安装与 stdio 验证；实时任务状态以 docs/project-management/current-task.md 为准。

  • 代码：领域/服务/Open-Meteo 适配器已实现；官方 v2 MCPServer 只注册 get_current_weather，并提供输入/输出 Schema、只读 annotations、结构化成功结果和稳定 Tool execution error。

  • Git：private 仓库为 wcnm8888/mcp1-weather-query；PR #1 已把 feat/f-001-local-weather-tool 合并到 main，原本地和远程功能分支已删除。

  • 制品/发布：mcp-weather-query==0.1.0 已通过 GitHub Actions Trusted Publishing 发布到 生产 PyPI；wheel、sdist、公开元数据、 SHA-256 与 attestations 已复核。

  • 测试：最近一次完整默认门禁为 96 passed, 1 skipped；唯一 skip 是显式 opt-in 的 live contract。此前 live contract 为 1 passed，Inspector 已完成唯一 Tool 的发现、成功和错误路径验证。

  • 启动边界：项目已注册 mcp-weather-query console command；wheel 与 sdist 已分别在项目外独立环境安装，并在无 PYTHONPATH、非源码工作目录下启动同一 stdio Server。

  • Node 兼容性：项目独立 Node 24.19.0 已通过官方 SHA256 校验，Inspector 2.1.0 不再产生 engine warning；系统 Node 22.16.0 未改变。

  • 协议证据：官方 Python SDK v2 Client(mode="auto") 通过生产 stdio 入口完成 server/discover，协商 MCP 2026-07-28，且未执行 Legacy initialize；同一 Server 继续允许 Inspector 2.1.0 以 Legacy MCP 2025-11-25 调试。

  • F-002 packaging：版本 0.1.0、uv_build、console script、MIT LICENSE 和 Open-Meteo NOTICE 已转绿；Step 3 生成的本地 wheel/sdist 已完成制品审查，Step 4 双干净安装验证通过。

  • 安装证据：公开 wheel 与 sdist 已分别在项目外全新环境安装；两者都只发现 get_current_weather，生产 console 的 stdout 仅含 MCP 消息、退出码为 0，确定性离线 调用返回合法 structuredContent。

  • 登记状态：io.github.wcnm8888/mcp1-weather-query==0.1.0 已登记到 Official MCP Registry； 官方 API 返回唯一 active/latest 记录，公开 PyPI 安装后的 installed-package stdio 复验通过。

Related MCP server: Weather MCP Server

安装与启动

从本地发布候选 wheel 安装

D-001 已在项目外生成并审查本地候选制品。获得已审查的 0.1.0 wheel 后， 可在包含 dist/ 的候选目录运行：

uv tool install ./dist/mcp_weather_query-0.1.0-py3-none-any.whl
mcp-weather-query

这会通过发行包提供的 console entry point 启动生产 stdio MCP Server，不需要 editable install、项目源码目录或 PYTHONPATH。mcp-weather-query 必须位于当前 PATH；可用 uv tool dir --bin 查看 uv 的工具命令目录。

从 PyPI 运行固定版本

PyPI 官方项目页已提供 0.1.0，可直接运行固定版本：

uvx --from mcp-weather-query==0.1.0 mcp-weather-query

stdio Host 配置

本地 wheel 安装完成且 console command 已位于 PATH 后，Host 可使用以下最小配置：

{
  "mcpServers": {
    "weather": {
      "command": "mcp-weather-query",
      "args": []
    }
  }
}

Server 通过 stdin/stdout 交换 MCP 协议消息；普通诊断只写入 stderr。不同 Host 的 配置文件位置和外层字段可能不同，但 command 不应改为源码路径，也不应注入 PYTHONPATH。

发布与登记状态

  • mcp-weather-query==0.1.0 已发布；公开可用性、文件和 attestation 以 PyPI 官方项目页 为准。

  • io.github.wcnm8888/mcp1-weather-query==0.1.0 已登记到 Official MCP Registry；官方 API 已复核为唯一 active/latest 条目，且 PyPI package、uvx、stdio、仓库元数据与冻结的 server.json 一致。

  • README 顶部的 mcp-name 注释继续作为 PyPI ownership verification marker；它与公开 Registry 身份保持一致，但 Registry 不托管 wheel/sdist，安装来源仍是 PyPI。

  • R-002 只对冻结的 server.json 执行过一次 publish。发布后已通过官方 API 和全新 PyPI 安装环境复验，并使用官方 mcp-publisher logout 处置本机短期认证文件。

  • 后续版本发布、Registry metadata 更新、状态变更或 GitHub Release 仍需要新的独立用户授权。

已交付能力

首个闭环提供一个只读 MCP Tool：get_current_weather。它接收地点名称和可选国家代码，通过固定天气数据源解析地点并返回带单位、时间、解析后地点和数据来源的结构化当前天气结果。

明确非目标

  • 不构建完整 Agent、聊天 UI、RAG 或多 Agent 系统。

  • 不提供天气预报、历史天气、空气质量、灾害预警或穿衣建议。

  • 不提供写入、删除、任意 Shell、任意文件访问或任意 URL 请求。

  • 首期不提供 Streamable HTTP、远程托管、账号体系和生产 SLA。

  • 不因教程示例存在多个 Tool 而增加“城市列表”或“服务器信息”等展示性 Tool。

文档入口

项目定义、架构、测试、发布和路线状态见 docs/README.md。

许可证与数据署名

  • 项目源代码采用 MIT License。

  • 天气与地理编码数据由 Open-Meteo 提供，数据依照 CC BY 4.0 使用。

  • 本学习项目只使用 Open-Meteo 非商业免费 API。公开免费层限制为每分钟 600 次、 每小时 5,000 次、每天 10,000 次请求，且无 SLA；不应把本工具视为商业或生产级 天气服务。限额和服务条款可能由上游调整，使用前应复核 Open-Meteo 官方说明。

  • 本项目会把选定的上游字段规范化为结构化 MCP Tool 输出，不改变底层测量值； 详细第三方数据说明见 NOTICE。

参考基线

Available Tools

1 tool
get_current_weatherGet current weatherA
Read-onlyIdempotent

Resolve a city or postal-code-like location and return read-only, model-based current conditions. This Tool does not provide forecasts, alerts, advice, or arbitrary URL content. Always inspect resolved_location because place names can be ambiguous.

ParametersJSON Schema
NameRequiredDescriptionDefault
locationYesCity, place name, or postal-code-like text. Trimmed length must be 2-100 characters; the value is never interpreted as a URL.
country_codeNoOptional ISO 3166-1 alpha-2 country code. Lower-case input is accepted and normalized to upper-case.

Output Schema

ParametersJSON Schema
NameRequiredDescription
currentYes
metadataYes
country_codeYes
resolved_locationYes
requested_locationYes

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar for the description is lower. The description adds valuable context beyond those flags: results are model-based current conditions, the tool is not a general URL fetcher, and resolved locations can be ambiguous. It does not mention potential rate limits or data freshness, but those are minor given the strong annotation coverage.

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

Conciseness5/5

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

The description is two sentences with no filler: the core action and scope are front-loaded, exclusions are stated compactly, and the critical usage warning about ambiguous place names is included. Every sentence earns its place.

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

Completeness5/5

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

Given the output schema exists, the description does not need to explain return values. The description covers purpose, exclusions, and the key ambiguity caveat, and the annotations plus schema provide the rest. There are no sibling tools to distinguish, so nothing material is missing.

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%, so the schema already documents both parameters thoroughly. The description reinforces that location is city/postal-code-like text but adds no new parameter-level detail beyond the schema. Baseline 3 is appropriate because the schema carries the semantic weight.

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

Purpose5/5

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

The description uses a specific verb ('Resolve') with a clear resource ('city or postal-code-like location') and states the outcome: return read-only, model-based current conditions. It also explicitly delimits the tool's scope by listing what it does not provide (forecasts, alerts, advice, or URL content), which removes ambiguity even without sibling tools.

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

Usage Guidelines5/5

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

The description provides explicit when-not-to-use guidance ('does not provide forecasts, alerts, advice, or arbitrary URL content') and actionable advice for the main use case ('Always inspect resolved_location because place names can be ambiguous'). This is sufficient routing guidance given there are no sibling tools.

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. 1 tool updatev0.1.0
    • First observedget_current_weather
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is zero ambiguity in tool selection. The tool's purpose is clearly distinct by being the sole option.

Naming Consistency5/5

The single tool name 'get_current_weather' follows the standard verb_noun pattern, which is clear and predictable.

Tool Count4/5

One tool is minimal, but the server's scope is explicitly limited to current conditions, making the count reasonable if slightly thin.

Completeness5/5

For the stated purpose of returning current weather conditions, the tool fully covers the domain; forecasts and alerts are intentionally excluded.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers