@Xjt Demo/Xjt Weather

基于 MCP 官方 Weather Server Quickstart 实现的天气 MCP Server，数据源为高德地图天气查询 API，可通过 npx 直接运行，无需本地安装。

前置条件

1. 在 高德开放平台 注册并创建应用
2. 申请 Web 服务 类型的 API Key
3. 在 MCP 配置中通过环境变量 AMAP_API_KEY 传入 Key

城市编码（adcode）可参考高德城市编码表，例如：

城市	adcode
北京东城	110101
上海	310100
广州	440100
深圳	440300

MCP Tools

Tool	说明
get-weather-live	查询指定城市的实况天气
get-weather-forecast	查询指定城市的天气预报（当天 + 未来 3 天）

两个工具均接受 city 参数：支持城市名称（如 上海、北京东城）或 6 位 adcode（如 310100）。

Cursor / Claude 配置

发布到 npm 后，使用者无需手动安装依赖。npx 会自动下载包及其 dependencies，然后启动 MCP Server。

{
  "mcpServers": {
    "xjtWeather": {
      "command": "npx",
      "args": ["-y", "@xjt-demo/xjt-weather-mcp"],
      "env": {
        "AMAP_API_KEY": "你的高德 Web 服务 Key"
      }
    }
  }
}

预发布通道：

{
  "mcpServers": {
    "xjtWeatherAlpha": {
      "command": "npx",
      "args": ["-y", "@xjt-demo/xjt-weather-mcp@alpha"],
      "env": {
        "AMAP_API_KEY": "你的高德 Web 服务 Key"
      }
    }
  }
}

本地开发

npm install
npm run build
AMAP_API_KEY=你的Key npm run dev

本地调试配置：

{
  "mcpServers": {
    "xjtWeatherLocal": {
      "command": "node",
      "args": ["/path/to/xjt-weather-mcp/dist/server.js"],
      "env": {
        "AMAP_API_KEY": "你的高德 Web 服务 Key"
      }
    }
  }
}

运行集成测试前， 在.env 文件中填入 Key（.env 已被 git 忽略）：

使用 MCP Inspector 调试：

AMAP_API_KEY=你的Key npx @modelcontextprotocol/inspector node dist/server.js

开发与发布流程

本仓库采用 main（稳定）+ alpha（预发布） 双分支策略：

分支	用途	发布命令	npm dist-tag	版本示例
alpha	新功能开发、预发布验证	pnpm release:alpha	alpha	1.2.0-alpha.0
main / master	稳定版	pnpm release:stable	latest	1.2.0

日常开发

• 新功能、较大改动：在 alpha 分支开发；需要对外验证时执行 pnpm release:alpha
• 小 bugfix、文档修正：可直接在 main 修改；发布后同步回 alpha（git checkout alpha && git merge main）

发布路径

路径 A：新功能（走 alpha）

npm login
git checkout alpha
# 开发、提交后
pnpm release:alpha

# 验证通过后
git checkout main
git merge alpha
pnpm release:stable

路径 B：紧急修复（走 main）

git checkout main
# 修复、提交后
pnpm release:stable

# 同步到 alpha
git checkout alpha
git merge main

版本号选择

变更类型	版本	示例
Bug 修复	PATCH	1.1.0 → 1.1.1
新功能（向后兼容）	MINOR	1.1.0 → 1.2.0
破坏性变更	MAJOR	1.x → 2.0.0
仅发布配置 / 文档	不发版	—

用户安装

npx @xjt-demo/xjt-weather-mcp              # latest（稳定版）
npx @xjt-demo/xjt-weather-mcp@alpha        # alpha 预发布版

release-it 会在发布前自动执行 typecheck 与 build；仅在对应分支上才能发布（见 .release-it.json / .release-it.alpha.json）。

License

MIT