# 和风天气 MCP 服务 · ModelScope 云端托管版（v1.1.1）

本仓库是 [hefeng-qweather-mcp](https://github.com/fengyucn/hefeng-qweather-mcp)
针对 **ModelScope MCP 广场云端托管（Hosted）** 的适配版本，两处关键适配：

1. **默认 stdio 入口**：无参数调用 `hefeng-qweather-mcp` 直接以 stdio 模式启动
   （原版 typer 无子命令时会打印帮助并以 exit code 2 退出）
2. **HTTP 模式监听 `0.0.0.0`**：云端容器内必须，否则平台网关无法连接；
   端口优先读 `PORT` 环境变量（云平台注入），其次 `MCP_PORT`，默认 8000

上游源码其余部分未做任何改动。

## 根因：为什么原版在 ModelScope 部署不起来

原版入口使用 `typer.Typer()`，只定义了 `http` / `stdio` 两个**子命令**：

```python
app = typer.Typer()

@app.command()
def http() -> None: ...

@app.command()
def stdio() -> None: ...

def main() -> None:
    app()
```

ModelScope 平台拉起 server 时**不传子命令**（对照官方
[modelscope-mcp-server](https://github.com/modelscope/modelscope-mcp-server)：
`argparse` + `--transport` 默认 `stdio`，无参数直接运行）。
原版此时 typer 报 `Missing command.` 并以 **exit code 2 立即退出**，
MCP server 从未启动，stdio 握手永远不会发生，平台即判定部署失败。

本地复现（原版）：

```text
$ hefeng-qweather-mcp
 Usage: ... [OPTIONS] COMMAND [ARGS]...
 Try 'hefeng-qweather-mcp --help' for help.
 ╭─ Error ───────────────────────────╮
 │ Missing command.                  │
 ╰──────────────────────────────────╯
 EXIT CODE: 2                        ← 进程直接退出，服务未启动
```

## 改动内容（相对原版的唯一差异）

在 `main()` 前新增一个默认 callback，无子命令时自动进入 stdio 模式：

```python
@app.callback(invoke_without_command=True)
def default(ctx: typer.Context) -> None:
    """
    默认入口：不带子命令调用时以 stdio 模式启动
    """
    if ctx.invoked_subcommand is None:
        stdio()
```

行为对照：

| 调用方式 | 原版 | 本适配版 |
|---|---|---|
| `hefeng-qweather-mcp`（平台默认方式） | 打印帮助，exit 2 ❌ | **stdio 模式启动** ✅ |
| `hefeng-qweather-mcp stdio` | stdio 启动 ✅ | stdio 启动 ✅（不变） |
| `hefeng-qweather-mcp http` | http 启动 ✅ | http 启动 ✅（不变） |
| `hefeng-qweather-mcp --help` | 显示帮助 ✅ | 显示帮助 ✅（不变） |

已验证：无参数调用可正确完成 MCP `initialize` 握手并返回 `serverInfo`。

## 部署到 ModelScope

1. 将本文件夹内容作为部署源（独立 Git 仓库 / 分支，或替换主仓库部署目录），
   确保仓库**根目录**包含本版的 `pyproject.toml`（版本 1.1.1）与 `src/`。
2. 平台创建/更新 MCP server 时，配置环境变量（**必须**，否则模块导入阶段
   即抛 `ValueError` 退出）：

   ```env
   HEFENG_API_HOST=你的API主机地址   # 如 devapi.qweather.com
   HEFENG_API_KEY=你的API KEY
   ```

3. 若平台支持自定义启动命令，任选其一均可（本版两者都兼容）：

   ```json
   { "command": "hefeng-qweather-mcp" }
   { "command": "hefeng-qweather-mcp", "args": ["stdio"] }
   ```

## 零代码替代方案（如不想发适配版）

若 ModelScope 后台支持配置 command/args，直接把原版启动命令配成
`hefeng-qweather-mcp stdio`（带子命令）即可绕过此问题，无需改任何代码。
适配版的价值在于对任意调用方式都健壮，不依赖平台配置能力。