Metadata-Version: 2.3
Name: wpx-mcpservce1-demo1
Version: 0.1.0
Summary: 查询中国省市区县天气和北京时间的 MCP 服务
Keywords: mcp,weather,china,beijing-time
Author: wangpeixin
Author-email: wangpeixin <2455869905@qq.com>
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet
Requires-Dist: mcp[cli]>=2.3,<3
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# wpx-mcpservce1-demo1

查询中国省、市、区县天气和北京时间的 MCP 服务，由 `mcpServce1` 复制并独立打包。
需要 **Python 3.14 或更新版本**。

提供两个工具：

- `get_weather(region, forecast_days=3)`：查询当前天气及未来 1～7 天预报，返回气温、体感温度、湿度、降水、风速、日出日落和数据时刻。需要联网。
- `get_current_time(region="中国")`：查询日期、时间、星期和 Unix 时间戳，统一使用北京时间（UTC+8）。不需要联网。

## 安装和启动

发布到 PyPI 后，用户可以直接安装：

```shell
python -m pip install wpx-mcpservce1-demo1
wpx-mcpservce1-demo1
```

也可以使用模块入口（与上面的命令等价）：

```shell
python -m wpx_mcpservce1_demo1
```

注意：PyPI 包名和终端命令使用连字符 `wpx-mcpservce1-demo1`，Python 导入名和模块入口使用下划线 `wpx_mcpservce1_demo1`。

默认使用 SSE，在 Cherry Studio 等 MCP 客户端选择 **SSE**，填写：

```text
http://127.0.0.1:8000/sse
```

保持服务终端开启。可用以下参数调整地址或切换连接方式：

```shell
wpx-mcpservce1-demo1 --host 127.0.0.1 --port 8001
wpx-mcpservce1-demo1 --transport streamable-http
wpx-mcpservce1-demo1 --transport stdio
```

Streamable HTTP 默认地址是 `http://127.0.0.1:8000/mcp`。stdio 由 MCP 客户端启动进程，不填写 HTTP 地址。

## MCP 客户端配置（stdio）

安装 [uv](https://docs.astral.sh/uv/getting-started/installation/) 后，发布到 PyPI 的服务可以通过 `uvx` 自动安装并启动，无需本地项目路径：

```json
{
  "mcpServers": {
    "wpx-weather-time": {
      "command": "uvx",
      "args": [
        "--python", "3.14",
        "--from", "wpx-mcpservce1-demo1",
        "wpx-mcpservce1-demo1",
        "--transport", "stdio"
      ]
    }
  }
}
```

在 Cherry Studio 中选择 stdio，命令填写 `uvx`，参数按上面 `args` 的顺序逐项填写。如果已通过 pip 安装，也可以将命令填写为 `wpx-mcpservce1-demo1`，参数填写 `--transport` 和 `stdio`；命令需要在客户端的 PATH 中，或填写可执行文件的绝对路径。

## 查询示例

- 北京现在的天气怎么样？
- 查询浙江省杭州市西湖区未来三天的天气。
- 深圳南山的气温、湿度和风速是多少？
- 查询乌鲁木齐市当前的天气和北京时间。
- 现在上海是几月几日、星期几、几点？

支持中文省、市、区县名称（包括直辖市、港澳），以及随包地区表中的六位行政区划代码。例如 `北京`、`北京市海淀区`、`深圳南山`、`浙江杭州西湖`、`香港`、`澳门`、`110108`。台湾目前仅提供省级代表坐标，可使用 `台湾` 查询。

同名地区（例如“朝阳区”或“南山区”）会返回 `needs_clarification` 和候选项。补充省市或使用候选行政代码重查，不会自动选择第一个结果。未收录或更名地区会明确报错。暂不支持街道和乡镇。

## 数据与限制

- 天气来源：[Open-Meteo](https://open-meteo.com/)，[接口说明](https://open-meteo.com/en/docs)。结果是天气模型的当前估算和预报，并非气象站逐秒实测。使用前请查看服务商最新的使用条款；公共无密钥接口的适用范围与商业方案以服务商说明为准。
- 地区名称和行政中心附近坐标来自 [阿里云 DataV.GeoAtlas](https://datav.aliyun.com/portal/school/atlas/area_selector)，[原始地区索引](https://geo.datav.aliyun.com/areas_v3/bound/all.json)。沿用原服务于 2026-10-23 获取的地区表，包含 34 个省级地区和 3,000 多个行政区记录，保存在 `src/wpx_mcpservce1_demo1/data/regions.json` 中并随安装包分发。源数据的行政区划版本可能滞后。
- 天气代表行政中心附近的一个坐标，无法表示整个省或城市每个位置。建议指定具体城市或区县。
- 天气请求超时为 20 秒。网络失败、限流和接口异常会返回中文错误；缺失气象数值保留为 `null`。
- 时间来自服务所在电脑的系统时钟，固定换算到 UTC+8；请保持系统时钟准确。

## 本地开发、测试和打包

在此文件夹内执行：

```shell
uv sync --locked
uv run --locked python -m unittest discover -s tests -v
uv run --locked wpx-mcpservce1-demo1 --help
uv build --no-sources
```

构建输出在 `dist/` 中，包含 `.whl` 和 `.tar.gz`。发布前，也可以从本地 wheel 安装验证：

```shell
python -m pip install dist/wpx_mcpservce1_demo1-0.1.0-py3-none-any.whl
python -m wpx_mcpservce1_demo1 --help
```

完整的 TestPyPI / PyPI 发布步骤参见项目中的 `PUBLISHING.md`。
