thiter-mcp 0.1.0__tar.gz

thiter_mcp-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# 测试与缓存
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# 日志与临时文件
+*.log
+proxy.log
+nohup.out
+
+# 系统文件
+.DS_Store
+
+# 沙箱环境残留的临时探针文件（安全策略禁止删除，仅防止误提交）
+/2sddbpwk
+/2x0o06k5
+/2xxsma5z
+/31ulblbs
+/338soufy
+/3e5r8zky
+/4rvet96n
+/60ici7jf
+/8i35yls1
+/_oscc8b6
+/e9ehpqck
+/f6lk466p
+/fbihz25q
+/hx81wb8e
+/ij6rsbqd
+/ks_f9qqg
+/me5awoe4
+/qj8xams3
+/ra9vteb1
+/y6nhap4w
+/yrd7q35z
+/yv865vuv
+*.cpython-313.pyc.*
+.tmp/

thiter_mcp-0.1.0/.workbuddy/memory/2026-10-25.md

@@ -0,0 +1,19 @@
+# 2026-10-25 工作日志
+
+## 春淼项目：方案三（ModelScope MCP 托管部署）实施
+
+- 读取 docs/modelscope.md 后，用户选择方案三：将 proxy.py 改造为 MCP 服务并走魔搭云托管。
+- 从 CNB 仓库 `weiguanghui/chunmiao/tmp-modelsapace-model` 拉取原 proxy.py（FastAPI OpenAI 兼容代理，硬编码 MAS_TOKEN，转发 api-inference.modelscope.cn，模型 qwen/qwen3.5-35b-a3b；test-ai.py 与 proxy.py 字节相同）。
+- 在本工作区创建 PyPI 包 `chunmiao-mcp`（src 布局 + hatchling）：
+  - `src/chunmiao_mcp/server.py`：MCP 官方 SDK mcp 2.x（MCPServer）实现，工具 chat / list_models，默认 stdio，支持 --transport streamable-http；配置全走环境变量（MAS_TOKEN / CHUNMIAO_MODEL / CHUNMIAO_BASE_URL / CHUNMIAO_TIMEOUT）；预期失败抛 ToolError（mcp 2.x 才会把详情透传给客户端）。
+  - 隐私加固：新增 CHUNMIAO_API_KEY 访问密钥（用户明确要求"只有自己可用"），配置后所有工具调用必须携带匹配 key 参数；测试覆盖缺/错/正确 key 三条路径。
+- 用户提供部署页截图确认：魔搭托管部署高级配置含平台级鉴权（Bearer Token / 无鉴权）与有效期（长期 / 24h），传输协议 Streamable HTTP / SSE，函数计算 FC 资源——平台级 Bearer Token 是首选防线，CHUNMIAO_API_KEY 降为可选第二层。已更新 README/docs。
+- pyproject.toml 按用户要求改为 author=thiter、description="thiter MCP 服务：..."。
+- 应用户要求将包名 chunmiao-mcp 全量改名为 thiter-mcp（PyPI 可用）：目录 src/chunmiao_mcp→src/thiter_mcp、模块名、console script、MCPServer("thiter")、README/docs 中所有命令与配置 JSON 同步更新；CHUNMIAO_* 环境变量前缀保留未动（已向用户说明）。e2e 23/23 复测通过。
+- 沙箱残留 22 个 4 字节临时探针文件 + __pycache__ 里的 .pyc.* 垃圾（策略禁止删除），已全部列入 .gitignore 防误提交。
+  - `tests/e2e_test.py` + `tests/stub_upstream.py`：stub 上游端到端测试，23 项全过（stdio + streamable-http、正常/500/401/缺令牌/缺错正确 key）。
+- 环境限制：本机 pip/uv/python -m build 均被安全策略拦截（tempfile 探针文件创建/删除被拒），故未在本地构建 wheel；需用户在本机执行 `uv build && uv publish`。
+- 已向用户说明：PyPI 完全公开（代码人人可见可装，但不含密钥）；魔搭 MCP 广场仅支持公开服务、托管端点公开可达，必须靠 CHUNMIAO_API_KEY 防白嫖；若连代码也不想公开则改用 streamable-http 自托管。
+- README.md 与 docs/modelscope.md 第八节已记录实施情况、部署配置 JSON 与安全说明。
+- 用户澄清：CNB 仓库是私有的（信任 CNB），旧 proxy.py 中的令牌未公开泄露——已把 README/docs 里"已随仓库公开、尽快轮换"的措辞改为"私有仓库未泄露、轮换属可选保险"。
+- 工作区残留一批 4 字节临时探针文件（策略禁止删除），待用户权限下清理。

thiter_mcp-0.1.0/.workbuddy/memory/MEMORY.md

@@ -0,0 +1,19 @@
+# 项目长期记忆（modelscope_project_proxy / 春淼）
+
+## 项目背景
+- 春淼（Chunmiao）：OpenAI 兼容代理 → 已按方案三改造为 MCP 服务，走魔搭 MCP 广场托管部署（7×24，摆脱 DSW 实例 8 小时回收）。
+- 代码仓库（CNB）：`cnb.cool/weiguanghui/chunmiao/tmp-modelsapace-model.git`，main 分支。
+- 上游：`https://api-inference.modelscope.cn/v1`，默认模型 `qwen/qwen3.5-35b-a3b`。
+
+## 技术决策
+- PyPI 包名 `thiter-mcp`（模块 `thiter_mcp`），src 布局 + hatchling，console script `thiter-mcp = thiter_mcp:main`（2026-10-25 由 chunmiao-mcp 改名，PyPI 名称可用；环境变量前缀保留 CHUNMIAO_* 未动）。
+- 框架：MCP 官方 Python SDK mcp 2.x（`from mcp.server.mcpserver import MCPServer`）。注意 mcp 2.x 与 fastmcp 2.x 互斥（fastmcp 要求 mcp<2），且本机无法安装 fastmcp（沙箱拦截 tempfile）。
+- mcp 2.x 约定：预期内失败必须抛 `mcp.server.mcpserver.exceptions.ToolError`，否则详情被屏蔽为 "Error executing tool X"。
+- 托管部署要求：PyPI 包 + `uvx chunmiao-mcp`（stdio）；平台自动部署检测（安装→连接→list_tools）。
+- 配置约定：令牌走环境变量 MAS_TOKEN，不硬编码；CNB 仓库是私有的（用户明确说明，信任 CNB），旧 proxy.py 里的令牌未公开泄露，轮换属可选保险。
+- 隐私边界（用户明确要求"只有自己可用"）：① PyPI 完全公开（代码+元信息人人可见可装，但不含密钥）；② 魔搭托管部署「高级配置」提供平台级鉴权：鉴权类型 Bearer Token / 无鉴权，有效期长期有效 / 24 小时，连接层校验（首选防线，截图确认）；③ 工具级 CHUNMIAO_API_KEY 作为可选第二层；④ 若连代码也不想公开 → 放弃托管，用 streamable-http 自托管 + 反代鉴权。
+- 署名：pyproject 作者为 thiter（2026-10-25 用户指定），描述以 "thiter MCP 服务" 开头；包名 thiter-mcp（已从 chunmiao-mcp 改名）。
+
+## 环境注意事项
+- 本沙箱 pip / uv / python -m build 均不可用（tempfile 探针文件被安全策略拦截），构建发布需在用户本机执行。
+- 测试运行方式：`PYTHONPATH=src python tests/e2e_test.py`（内置 stub，无需真实令牌）。

thiter_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: thiter-mcp
+Version: 0.1.0
+Summary: thiter MCP 服务：把魔搭 ModelScope 大模型包装成 MCP 工具（OpenAI 兼容 messages 格式）
+Author: thiter
+License: MIT
+Keywords: llm,mcp,modelscope,proxy
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.3
+Description-Content-Type: text/markdown
+
+# thiter MCP（thiter-mcp）
+
+把魔搭 ModelScope 的大模型（默认 `qwen/qwen3.5-35b-a3b`）包装成 **MCP 工具**的代理服务，是原 OpenAI 兼容代理 `proxy.py` 的 MCP 化改造版。通过 ModelScope MCP 广场「可托管部署」后，可获得 7×24 小时稳定运行的云端 MCP 端点，不再受 Notebook 实例 8 小时到期回收的限制。
+
+## 项目简介
+
+thiter MCP 基于 MCP 官方 Python SDK（`mcp` 2.x，`MCPServer`）实现，暴露两个工具：
+
+| 工具 | 说明 |
+| --- | --- |
+| `chat` | 与魔搭大模型对话，入参为 OpenAI 兼容的 `messages` 列表，返回 `content` / `model` / `finish_reason` / `usage` |
+| `list_models` | 列出当前令牌可调用的模型 |
+
+特性：
+
+- **默认 stdio 传输**：满足魔搭托管部署要求（PyPI 包 + `uvx` 拉起）
+- **配置全走环境变量**：令牌不落代码，`MAS_TOKEN` 等在平台侧配置注入
+- **访问密钥保护**：配置 `CHUNMIAO_API_KEY` 后，所有工具调用必须携带匹配的 `key` 参数，托管端点公开可达也不会被他人白嫖额度
+- **无状态、不落盘**：适配 serverless 托管环境
+- **可选 HTTP 自托管**：`--transport streamable-http` 可起 Streamable HTTP 服务
+
+## 部署指南
+
+### 方式一：魔搭 MCP 广场托管部署（推荐，7×24 运行）
+
+托管部署要求服务已发布到 PyPI，通过 `uvx` 拉起。步骤如下：
+
+1. **发布到 PyPI**（需 PyPI 账号与 API Token）：
+
+   ```bash
+   uv build                      # 生成 dist/*.whl 与 *.tar.gz
+   uv publish --token <你的PyPI Token>
+   ```
+
+2. **在魔搭 MCP 广场创建服务**：打开 <https://modelscope.cn/mcp/servers/create?template=customize>
+   - 创建类型：自定义创建
+   - 英文名称：`thiter`（将作为服务 ID 的一部分）
+   - 托管类型：**可托管部署**
+   - 服务配置（第二步填写）：
+
+     ```json
+     {
+       "mcpServers": {
+         "thiter": {
+           "command": "uvx",
+           "args": ["thiter-mcp"],
+           "env": {
+             "MAS_TOKEN": "ms-你的魔搭令牌",
+             "CHUNMIAO_API_KEY": "自己定一个强随机密钥"
+           }
+         }
+       }
+     }
+     ```
+
+   - 环境变量：`MAS_TOKEN` 必填；强烈建议同时配置 `CHUNMIAO_API_KEY`（托管端点公开可达，见下方安全说明）；可选 `CHUNMIAO_MODEL`、`CHUNMIAO_BASE_URL`、`CHUNMIAO_TIMEOUT`
+   - 第三步：填写 README 内容
+
+3. 点击创建后，平台会自动执行部署检测（`uvx` 安装包 → 连接 → `list_tools`），通过后即获得托管端点（形如 `https://mcp.api-inference.modelscope.net/<你的服务名>/mcp`），任意 MCP 客户端均可接入。
+
+### 方式二：本地 / 自托管使用
+
+```bash
+# 直接运行（需 Python >= 3.10）
+pip install thiter-mcp
+export MAS_TOKEN="ms-你的魔搭令牌"
+thiter-mcp        # stdio 模式
+```
+
+MCP 客户端配置（Claude Desktop / Cursor / Cherry Studio 等）：
+
+```json
+{
+  "mcpServers": {
+    "thiter": {
+      "command": "uvx",
+      "args": ["thiter-mcp"],
+      "env": {
+        "MAS_TOKEN": "ms-你的魔搭令牌",
+        "CHUNMIAO_API_KEY": "自己定一个强随机密钥"
+      }
+    }
+  }
+}
+```
+
+> 注意：客户端连接托管端点（`https://mcp.api-inference.modelscope.net/<服务名>/mcp`）时无需填 env，
+> 但每次工具调用需在参数里带上 `"key": "<你的 CHUNMIAO_API_KEY>"`。
+
+自托管 Streamable HTTP 模式：
+
+```bash
+thiter-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+# 端点: http://<主机>:8000/mcp
+```
+
+## 使用示例
+
+以 MCP 客户端调用 `chat` 工具为例：
+
+```json
+{
+  "tool": "chat",
+  "arguments": {
+    "messages": [
+      {"role": "system", "content": "你是thiter 助手"},
+      {"role": "user", "content": "你好，介绍一下你自己"}
+    ],
+    "key": "你的 CHUNMIAO_API_KEY",
+    "temperature": 0.7,
+    "max_tokens": 1024
+  }
+}
+```
+
+返回示例：
+
+```json
+{
+  "content": "你好！我是thiter 助手……",
+  "model": "qwen/qwen3.5-35b-a3b",
+  "finish_reason": "stop",
+  "usage": {"prompt_tokens": 20, "completion_tokens": 50, "total_tokens": 70}
+}
+```
+
+与原 `proxy.py` 的差异：原服务暴露 OpenAI HTTP 接口（`/v1/chat/completions`），本服务改为 MCP 工具。原使用 OpenAI SDK 的客户端需迁移为 MCP 调用，`messages` 入参格式保持不变，迁移成本低。
+
+## 环境变量
+
+| 变量 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `MAS_TOKEN` | 是 | 无 | 魔搭 API 访问令牌（ms-xxx） |
+| `CHUNMIAO_API_KEY` | 否 | 无（不启用） | 访问密钥；配置后所有工具调用必须携带匹配的 `key` 参数 |
+| `CHUNMIAO_MODEL` | 否 | `qwen/qwen3.5-35b-a3b` | 默认模型 |
+| `CHUNMIAO_BASE_URL` | 否 | `https://api-inference.modelscope.cn/v1` | 上游 API 地址 |
+| `CHUNMIAO_TIMEOUT` | 否 | `120` | 上游超时（秒） |
+| `CHUNMIAO_TRANSPORT` | 否 | `stdio` | 传输方式（stdio / streamable-http） |
+| `CHUNMIAO_HOST` / `CHUNMIAO_PORT` | 否 | `127.0.0.1` / `8000` | HTTP 模式监听地址 |
+
+## 安全与隐私说明
+
+- **PyPI 是完全公开的**：包发布后，代码人人可查看、下载、安装，作者/描述等元信息也会公开展示。本包不包含任何密钥（`MAS_TOKEN` / `CHUNMIAO_API_KEY` 均走环境变量），公开代码不会泄露你的令牌；如不希望公开关联信息，请使用中性的包名与作者名。
+- **平台级鉴权（推荐，首选防线）**：魔搭托管部署的「高级配置」中可选择 **鉴权类型：Bearer Token**，客户端连接托管端点时必须携带该令牌，连接层即完成校验——对任意 MCP 客户端透明，无需在工具参数里传 key。有效期可选「长期有效」（令牌本身是敏感信息，切勿外泄）或「24 小时」。传输协议支持 Streamable HTTP / SSE，部署在函数计算（FC）资源上。
+- **工具级访问密钥（可选第二层）**：配置 `CHUNMIAO_API_KEY` 后，所有工具调用必须携带匹配的 `key` 参数。平台已开启 Bearer Token 时可留空（省去每次传 key）；追求纵深防御时两者可同时启用。
+- **YOUR_API_KEY 这类变量是上游服务的凭证**：截图中天眼查 MCP 的 `YOUR_API_KEY` 是它调用上游要用的密钥，通过部署页环境变量注入——与本服务 `MAS_TOKEN` 同一模式。代码里不内置任何默认密钥，未配置即不启用。
+- **如果连代码也不想公开**：托管部署（uvx + PyPI）就不适用，改用自托管：`thiter-mcp --transport streamable-http` 部署在自己控制的服务器上，前面再挂反代 + TLS + 鉴权，完全不经过 PyPI 和魔搭广场。
+- **历史令牌处理**：原 `proxy.py` 中硬编码的魔搭令牌仅存在于私有 CNB 仓库内，未对外泄露；新包已彻底移除硬编码（零密钥），旧 proxy.py 退役后该令牌即不再随代码流转。如想更稳妥，仍可在魔搭后台轮换一次，属可选操作。
+
+## 本地开发
+
+```bash
+git clone <仓库地址>
+cd thiter
+uv venv && source .venv/bin/activate
+uv pip install -e .
+python -m thiter_mcp --help
+
+# 端到端测试（内置 stub 上游，无需真实令牌）
+PYTHONPATH=src python tests/e2e_test.py
+```

thiter_mcp-0.1.0/README.md

@@ -0,0 +1,161 @@
+# thiter MCP（thiter-mcp）
+
+把魔搭 ModelScope 的大模型（默认 `qwen/qwen3.5-35b-a3b`）包装成 **MCP 工具**的代理服务，是原 OpenAI 兼容代理 `proxy.py` 的 MCP 化改造版。通过 ModelScope MCP 广场「可托管部署」后，可获得 7×24 小时稳定运行的云端 MCP 端点，不再受 Notebook 实例 8 小时到期回收的限制。
+
+## 项目简介
+
+thiter MCP 基于 MCP 官方 Python SDK（`mcp` 2.x，`MCPServer`）实现，暴露两个工具：
+
+| 工具 | 说明 |
+| --- | --- |
+| `chat` | 与魔搭大模型对话，入参为 OpenAI 兼容的 `messages` 列表，返回 `content` / `model` / `finish_reason` / `usage` |
+| `list_models` | 列出当前令牌可调用的模型 |
+
+特性：
+
+- **默认 stdio 传输**：满足魔搭托管部署要求（PyPI 包 + `uvx` 拉起）
+- **配置全走环境变量**：令牌不落代码，`MAS_TOKEN` 等在平台侧配置注入
+- **访问密钥保护**：配置 `CHUNMIAO_API_KEY` 后，所有工具调用必须携带匹配的 `key` 参数，托管端点公开可达也不会被他人白嫖额度
+- **无状态、不落盘**：适配 serverless 托管环境
+- **可选 HTTP 自托管**：`--transport streamable-http` 可起 Streamable HTTP 服务
+
+## 部署指南
+
+### 方式一：魔搭 MCP 广场托管部署（推荐，7×24 运行）
+
+托管部署要求服务已发布到 PyPI，通过 `uvx` 拉起。步骤如下：
+
+1. **发布到 PyPI**（需 PyPI 账号与 API Token）：
+
+   ```bash
+   uv build                      # 生成 dist/*.whl 与 *.tar.gz
+   uv publish --token <你的PyPI Token>
+   ```
+
+2. **在魔搭 MCP 广场创建服务**：打开 <https://modelscope.cn/mcp/servers/create?template=customize>
+   - 创建类型：自定义创建
+   - 英文名称：`thiter`（将作为服务 ID 的一部分）
+   - 托管类型：**可托管部署**
+   - 服务配置（第二步填写）：
+
+     ```json
+     {
+       "mcpServers": {
+         "thiter": {
+           "command": "uvx",
+           "args": ["thiter-mcp"],
+           "env": {
+             "MAS_TOKEN": "ms-你的魔搭令牌",
+             "CHUNMIAO_API_KEY": "自己定一个强随机密钥"
+           }
+         }
+       }
+     }
+     ```
+
+   - 环境变量：`MAS_TOKEN` 必填；强烈建议同时配置 `CHUNMIAO_API_KEY`（托管端点公开可达，见下方安全说明）；可选 `CHUNMIAO_MODEL`、`CHUNMIAO_BASE_URL`、`CHUNMIAO_TIMEOUT`
+   - 第三步：填写 README 内容
+
+3. 点击创建后，平台会自动执行部署检测（`uvx` 安装包 → 连接 → `list_tools`），通过后即获得托管端点（形如 `https://mcp.api-inference.modelscope.net/<你的服务名>/mcp`），任意 MCP 客户端均可接入。
+
+### 方式二：本地 / 自托管使用
+
+```bash
+# 直接运行（需 Python >= 3.10）
+pip install thiter-mcp
+export MAS_TOKEN="ms-你的魔搭令牌"
+thiter-mcp        # stdio 模式
+```
+
+MCP 客户端配置（Claude Desktop / Cursor / Cherry Studio 等）：
+
+```json
+{
+  "mcpServers": {
+    "thiter": {
+      "command": "uvx",
+      "args": ["thiter-mcp"],
+      "env": {
+        "MAS_TOKEN": "ms-你的魔搭令牌",
+        "CHUNMIAO_API_KEY": "自己定一个强随机密钥"
+      }
+    }
+  }
+}
+```
+
+> 注意：客户端连接托管端点（`https://mcp.api-inference.modelscope.net/<服务名>/mcp`）时无需填 env，
+> 但每次工具调用需在参数里带上 `"key": "<你的 CHUNMIAO_API_KEY>"`。
+
+自托管 Streamable HTTP 模式：
+
+```bash
+thiter-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+# 端点: http://<主机>:8000/mcp
+```
+
+## 使用示例
+
+以 MCP 客户端调用 `chat` 工具为例：
+
+```json
+{
+  "tool": "chat",
+  "arguments": {
+    "messages": [
+      {"role": "system", "content": "你是thiter 助手"},
+      {"role": "user", "content": "你好，介绍一下你自己"}
+    ],
+    "key": "你的 CHUNMIAO_API_KEY",
+    "temperature": 0.7,
+    "max_tokens": 1024
+  }
+}
+```
+
+返回示例：
+
+```json
+{
+  "content": "你好！我是thiter 助手……",
+  "model": "qwen/qwen3.5-35b-a3b",
+  "finish_reason": "stop",
+  "usage": {"prompt_tokens": 20, "completion_tokens": 50, "total_tokens": 70}
+}
+```
+
+与原 `proxy.py` 的差异：原服务暴露 OpenAI HTTP 接口（`/v1/chat/completions`），本服务改为 MCP 工具。原使用 OpenAI SDK 的客户端需迁移为 MCP 调用，`messages` 入参格式保持不变，迁移成本低。
+
+## 环境变量
+
+| 变量 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `MAS_TOKEN` | 是 | 无 | 魔搭 API 访问令牌（ms-xxx） |
+| `CHUNMIAO_API_KEY` | 否 | 无（不启用） | 访问密钥；配置后所有工具调用必须携带匹配的 `key` 参数 |
+| `CHUNMIAO_MODEL` | 否 | `qwen/qwen3.5-35b-a3b` | 默认模型 |
+| `CHUNMIAO_BASE_URL` | 否 | `https://api-inference.modelscope.cn/v1` | 上游 API 地址 |
+| `CHUNMIAO_TIMEOUT` | 否 | `120` | 上游超时（秒） |
+| `CHUNMIAO_TRANSPORT` | 否 | `stdio` | 传输方式（stdio / streamable-http） |
+| `CHUNMIAO_HOST` / `CHUNMIAO_PORT` | 否 | `127.0.0.1` / `8000` | HTTP 模式监听地址 |
+
+## 安全与隐私说明
+
+- **PyPI 是完全公开的**：包发布后，代码人人可查看、下载、安装，作者/描述等元信息也会公开展示。本包不包含任何密钥（`MAS_TOKEN` / `CHUNMIAO_API_KEY` 均走环境变量），公开代码不会泄露你的令牌；如不希望公开关联信息，请使用中性的包名与作者名。
+- **平台级鉴权（推荐，首选防线）**：魔搭托管部署的「高级配置」中可选择 **鉴权类型：Bearer Token**，客户端连接托管端点时必须携带该令牌，连接层即完成校验——对任意 MCP 客户端透明，无需在工具参数里传 key。有效期可选「长期有效」（令牌本身是敏感信息，切勿外泄）或「24 小时」。传输协议支持 Streamable HTTP / SSE，部署在函数计算（FC）资源上。
+- **工具级访问密钥（可选第二层）**：配置 `CHUNMIAO_API_KEY` 后，所有工具调用必须携带匹配的 `key` 参数。平台已开启 Bearer Token 时可留空（省去每次传 key）；追求纵深防御时两者可同时启用。
+- **YOUR_API_KEY 这类变量是上游服务的凭证**：截图中天眼查 MCP 的 `YOUR_API_KEY` 是它调用上游要用的密钥，通过部署页环境变量注入——与本服务 `MAS_TOKEN` 同一模式。代码里不内置任何默认密钥，未配置即不启用。
+- **如果连代码也不想公开**：托管部署（uvx + PyPI）就不适用，改用自托管：`thiter-mcp --transport streamable-http` 部署在自己控制的服务器上，前面再挂反代 + TLS + 鉴权，完全不经过 PyPI 和魔搭广场。
+- **历史令牌处理**：原 `proxy.py` 中硬编码的魔搭令牌仅存在于私有 CNB 仓库内，未对外泄露；新包已彻底移除硬编码（零密钥），旧 proxy.py 退役后该令牌即不再随代码流转。如想更稳妥，仍可在魔搭后台轮换一次，属可选操作。
+
+## 本地开发
+
+```bash
+git clone <仓库地址>
+cd thiter
+uv venv && source .venv/bin/activate
+uv pip install -e .
+python -m thiter_mcp --help
+
+# 端到端测试（内置 stub 上游，无需真实令牌）
+PYTHONPATH=src python tests/e2e_test.py
+```

thiter_mcp-0.1.0/docs/modelscope.md

@@ -0,0 +1,145 @@
+MARKDOWN
+# 春淼项目背景与部署方案
+
+## 一、项目概述
+
+- **项目名称**：春淼（Chunmiao）
+- **项目类型**：OpenAl 兼容代理服务
+- **核心文件**：`proxy.py`、`test-ai.py`、`.gitignore`
+- **项目目标**：提供一个 OpenAI API 兼容的代理服务，将请求转发到后端模型
+
+## 二、代码仓库与平台
+
+- **代码托管平台**：CNB（Cloud Native Build，腾讯云原生构建平台）
+- **远端仓库地址**：`cnb.cool/weiguanghui/chunmiao/tmp-modelsapace-model.git`
+- **仓库认证方式**：Access Token 认证
+- **当前分支**：main（已 push 完成，`Resolving deltas: 100% (357/357)`）
+- **最近提交**：已删除缓存/临时文件，后续通过 `.gitignore` 避免误传
+
+## 三、当前运行环境
+
+- **运行平台**：ModelScope Notebook（魔搭社区 Notebook）
+- **实例类型**：DSW-CPU（CPU 计算实例）
+- **实例规格**：DSW-CPU
+- **工作目录**：`/mnt/workspace/`
+- **持久化存储**：`/mnt/workspace/` 下的文件在实例回收后仍保留
+- **关键限制**：单次实例剩余时长约 8 小时（当前显示 06:47:19），到期自动回收实例，proxy.py 会随之中断
+
+
+## 四、核心需求
+
+保证 `proxy.py` 进程持续可用，满足以下场景的自动恢复：
+- 进程意外崩溃或被 kill
+- 服务器/实例重启
+- 实例到期回收后重新启动时自动拉起
+
+## 五、解决方案详述
+
+### 方案一：systemd 系统服务（推荐，需 sudo 权限）
+
+**原理**：将 proxy.py 注册为系统服务，由 systemd 管理生命周期。
+
+**配置文件**：`/etc/systemd/system/proxy.service`
+[Unit]
+Description=Chunmiao Proxy Service
+After=network.target
+[Service]
+Type=simple
+WorkingDirectory=/mnt/workspace
+ExecStart=/usr/bin/python3 /mnt/workspace/proxy.py
+Restart=on-failure
+RestartSec=5
+[Install]
+WantedBy=multi-user.target
+ 
+**启用命令**：
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now proxy.service
+效果：
+开机自动启动 proxy.py
+进程挂掉后 5 秒自动拉起（Restart=on-failure）
+需要 root/sudo 权限
+局限：无法突破 DSW 实例的 8 小时到期回收限制，实例回收后服务仍会中断。
+方案二：crontab 定时检查（无 sudo 权限时可用）
+原理：每分钟检查 proxy.py 进程是否存在，不存在则用 nohup 拉起。
+检查脚本： /mnt/workspace/check_proxy.sh 
+BASH
+#!/bin/bash
+if ! pgrep -f "proxy.py" > /dev/null; then
+    cd /mnt/workspace && nohup python3 proxy.py > proxy.log 2>&1 &
+fi
+crontab 配置：
+BASH
+* * * * * /mnt/workspace/check_proxy.sh
+效果：
+无需 sudo 权限
+进程挂掉后最多 1 分钟被拉起
+不够优雅，不如 systemd 稳定
+局限：同样无法突破实例到期回收限制。
+方案三：ModelScope MCP 部署服务（长期运行方案）
+平台：ModelScope MCP 部署服务（https://modelscope.cn/mcp/servers/create）
+原理：将服务改造为符合 MCP 协议的服务，通过魔搭云端托管，平台分配稳定计算资源 7×24 小时运行。
+配置方式：在 MCP 部署页面选择「自定义 MCP」，填写 JSON 配置：
+JSON
+{
+  "command": "python",
+  "args": ["proxy.py"],
+  "env": {}
+}
+要求：
+proxy.py 需要改造为符合 MCP 协议的服务（建议使用 FastMCP 框架包装）
+支持 Stdio 或 SSE 通信方式
+平台自动管理资源，不受 Notebook 到期回收限制
+效果：
+7×24 小时持续运行
+云端托管，无需自己维护服务器
+自动负载均衡和故障恢复
+六、方案对比
+维度    systemd    crontab    MCP 部署
+自动拉起    是（立即）    是（延迟1分钟）    是
+开机自启    是    否    是
+24小时运行    否（受实例回收限制）    否（受实例回收限制）    是
+权限要求    sudo    无    无（需符合MCP协议）
+稳定性    高    中    高
+改造成本    低    低    中（需改造为MCP协议）
+七、结论与建议
+短期测试/开发阶段：
+使用 systemd（有 sudo）或 crontab（无 sudo）保证 proxy.py 进程稳定
+注意 DSW 实例 8 小时到期限制，到期前手动重启或重新启动实例
+长期生产运行：
+将 proxy.py 改造为 MCP 协议服务（使用 FastMCP 等框架包装）
+通过 ModelScope MCP 部署服务托管，彻底解决实例回收问题
+享受云端 7×24 小时稳定运行，无需自己维护服务器
+代码管理：
+远端仓库： cnb.cool/weiguanghui/chunmiao/tmp-modelsapace-model.git 
+确保  .gitignore  配置完善，避免缓存文件、临时文件误传
+当前 main 分支已包含最新提交（删除缓存/临时文件）
+
+## 八、方案三实施记录（2026-10-25）
+
+已按方案三完成 proxy.py 的 MCP 化改造，代码位于本仓库工作区：
+
+- **包结构**：`src/thiter_mcp/`（server.py 工具实现 + __main__.py 入口），`pyproject.toml`（hatchling 构建，包名 `thiter-mcp`）
+- **技术栈**：MCP 官方 Python SDK（mcp 2.x，MCPServer），httpx 调用上游；默认 stdio 传输（满足魔搭托管部署要求），支持 `--transport streamable-http` 自托管
+- **工具**：`chat`（OpenAI 兼容 messages 入参，返回 content/model/finish_reason/usage）、`list_models`；均支持 `key` 访问密钥参数
+- **配置**：全部走环境变量（MAS_TOKEN 必填，CHUNMIAO_MODEL / CHUNMIAO_BASE_URL / CHUNMIAO_TIMEOUT 可选），令牌不再硬编码
+- **隐私保护**：隐私分三层——① 代码公开但零密钥（MAS_TOKEN / CHUNMIAO_API_KEY 全走环境变量，无默认值）；② 平台级鉴权：托管部署「高级配置」可选鉴权类型 Bearer Token（连接层校验，推荐）+ 有效期长期/24 小时；③ 工具级 CHUNMIAO_API_KEY（可选第二层，调用带 key 参数）。传输协议支持 Streamable HTTP / SSE（函数计算 FC 资源）
+- **测试**：`tests/e2e_test.py` 内置 stub 上游，覆盖 stdio / streamable-http 双传输、正常调用、上游 500、错误令牌 401、缺 MAS_TOKEN 等路径，17 项全部通过
+- **与原 proxy.py 的差异**：OpenAI HTTP 接口（/v1/chat/completions）改为 MCP chat 工具，原 OpenAI SDK 客户端需迁移为 MCP 调用（messages 格式不变）
+
+### 待用户操作（需要账号权限，无法代执行）
+
+1. 发布到 PyPI：`uv build && uv publish --token <PyPI Token>`
+2. 魔搭 MCP 广场创建（https://modelscope.cn/mcp/servers/create?template=customize），托管类型选「可托管部署」，服务配置：
+   {"mcpServers": {"thiter": {"command": "uvx", "args": ["thiter-mcp"], "env": {"MAS_TOKEN": "ms-你的魔搭令牌", "CHUNMIAO_API_KEY": "自己定一个强随机密钥"}}}}
+   注意：① PyPI 完全公开（代码与元信息人人可见，但不含密钥），作者已署名 thiter，包名/描述如不想关联真实身份应保持中性；② 部署页高级配置务必选「鉴权类型: Bearer Token」（连接层防护，首选），有效期长期有效时令牌自身妥善保管；CHUNMIAO_API_KEY 作为可选第二层；③ 若连代码也不想公开则放弃托管，改用 streamable-http 自托管 + 反代鉴权。
+3. 平台自动部署检测（uvx 安装 → 连接 → list_tools）通过后获得托管端点
+
+### 令牌说明（非紧急）
+
+CNB 仓库为私有，原 proxy.py 中硬编码的魔搭令牌未对外泄露；新 MCP 包已零密钥化（全部走环境变量），旧 proxy.py 退役后令牌不再随代码流转。轮换令牌属可选保险，不强制。
+
+---
+
+以上就是本次实施记录。部署过程中如遇到问题，把报错发我即可。

thiter_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "thiter-mcp"
+version = "0.1.0"
+description = "thiter MCP 服务：把魔搭 ModelScope 大模型包装成 MCP 工具（OpenAI 兼容 messages 格式）"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "thiter" }]
+keywords = ["mcp", "modelscope", "llm", "proxy"]
+dependencies = [
+    "mcp>=2.3,<3",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+thiter-mcp = "thiter_mcp:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

thiter_mcp-0.1.0/src/thiter_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""thiter MCP 服务包入口。"""
+
+from .server import __version__, main, mcp
+
+__all__ = ["__version__", "main", "mcp"]

thiter_mcp-0.1.0/src/thiter_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""支持 `python -m thiter_mcp` 方式启动。"""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

thiter_mcp-0.1.0/src/thiter_mcp/server.py

@@ -0,0 +1,214 @@
+"""thiter MCP 服务：把魔搭 ModelScope 大模型包装成 MCP 工具。
+
+用法：
+    thiter-mcp                    # 默认 stdio 传输（魔搭托管部署用）
+    thiter-mcp --transport streamable-http --port 8000   # 自托管 HTTP
+
+环境变量：
+    MAS_TOKEN          必填，魔搭 API 访问令牌（ms-xxx）
+    CHUNMIAO_API_KEY   可选，访问密钥；配置后所有工具调用必须携带匹配的 key 参数
+    CHUNMIAO_MODEL     默认模型，默认 qwen/qwen3.5-35b-a3b
+    CHUNMIAO_BASE_URL  上游地址，默认 https://api-inference.modelscope.cn/v1
+    CHUNMIAO_TIMEOUT   上游超时（秒），默认 120
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import Any
+
+import httpx
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+
+__version__ = "0.1.0"
+
+mcp = MCPServer("thiter")
+
+
+def _config() -> dict[str, Any]:
+    """读取环境变量配置（每次调用时读取，便于测试与热更新）。"""
+    return {
+        "token": os.environ.get("MAS_TOKEN", "").strip(),
+        "model": os.environ.get("CHUNMIAO_MODEL", "qwen/qwen3.5-35b-a3b").strip(),
+        "base_url": os.environ.get(
+            "CHUNMIAO_BASE_URL", "https://api-inference.modelscope.cn/v1"
+        ).rstrip("/"),
+        "timeout": float(os.environ.get("CHUNMIAO_TIMEOUT", "120")),
+    }
+
+
+def _check_token() -> str:
+    token = _config()["token"]
+    if not token:
+        raise ToolError(
+            "未配置 MAS_TOKEN 环境变量。请在魔搭 MCP 服务配置的 env 中填入你的魔搭令牌（ms-xxx）。"
+        )
+    return token
+
+
+def _check_access(key: str | None) -> None:
+    """访问密钥校验：服务端配置 CHUNMIAO_API_KEY 后，所有工具调用必须携带匹配的 key。
+
+    魔搭托管端点是公开可达的，这道校验保证只有知道密钥的人能使用，
+    避免他人调用时消耗你的魔搭额度。
+    """
+    expected = os.environ.get("CHUNMIAO_API_KEY", "").strip()
+    if not expected:
+        return  # 未配置则不启用
+    if not key or key != expected:
+        raise ToolError(
+            "访问密钥无效：请在工具参数中提供正确的 key（需与服务端 CHUNMIAO_API_KEY 一致）"
+        )
+
+
+@mcp.tool()
+async def chat(
+    messages: list[dict[str, Any]],
+    key: str | None = None,
+    model: str | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    top_p: float | None = None,
+) -> dict[str, Any]:
+    """与thiter代理背后的魔搭大模型对话（OpenAI 兼容 messages 格式）。
+
+    Args:
+        messages: OpenAI 格式的消息列表，例如 [{"role": "user", "content": "你好"}]
+        key: 访问密钥（服务端配置 CHUNMIAO_API_KEY 后必填，需一致）
+        model: 可选，覆盖默认模型（如 qwen/qwen3.5-35b-a3b）
+        temperature: 可选，采样温度
+        max_tokens: 可选，最大生成 token 数
+        top_p: 可选，核采样参数
+
+    Returns:
+        dict: {"content": 回复文本, "model": 模型, "finish_reason": 结束原因, "usage": 用量统计}
+    """
+    _check_access(key)
+    cfg = _config()
+    token = _check_token()
+
+    payload: dict[str, Any] = {
+        "model": model or cfg["model"],
+        "messages": messages,
+        "stream": False,  # MCP 工具返回为单条消息，不支持流式
+    }
+    for key, value in (
+        ("temperature", temperature),
+        ("max_tokens", max_tokens),
+        ("top_p", top_p),
+    ):
+        if value is not None:
+            payload[key] = value
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+    }
+
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                f"{cfg['base_url']}/chat/completions",
+                json=payload,
+                headers=headers,
+                timeout=cfg["timeout"],
+            )
+    except httpx.TimeoutException as exc:
+        raise ToolError(f"上游请求超时（{cfg['timeout']}s）") from exc
+    except httpx.HTTPError as exc:
+        raise ToolError(f"上游请求失败: {exc}") from exc
+
+    if resp.status_code != 200:
+        # 不返回令牌，避免泄露
+        raise ToolError(f"上游返回 HTTP {resp.status_code}: {resp.text[:500]}")
+
+    data = resp.json()
+    choices = data.get("choices") or []
+    if not choices:
+        raise ToolError(f"上游响应缺少 choices 字段: {str(data)[:500]}")
+
+    message = choices[0].get("message") or {}
+    return {
+        "content": message.get("content", ""),
+        "model": data.get("model", payload["model"]),
+        "finish_reason": choices[0].get("finish_reason"),
+        "usage": data.get("usage"),
+    }
+
+
+@mcp.tool()
+async def list_models(key: str | None = None) -> dict[str, Any]:
+    """列出当前代理可调用的模型列表。
+
+    Args:
+        key: 访问密钥（服务端配置 CHUNMIAO_API_KEY 后必填，需一致）
+    """
+    _check_access(key)
+    cfg = _config()
+    token = _check_token()
+    headers = {"Authorization": f"Bearer {token}"}
+
+    try:
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(
+                f"{cfg['base_url']}/models",
+                headers=headers,
+                timeout=min(cfg["timeout"], 30),
+            )
+        if resp.status_code == 200:
+            return resp.json()
+    except httpx.HTTPError:
+        pass
+
+    # 上游不可用时退化为已配置的默认模型
+    return {
+        "object": "list",
+        "data": [
+            {"id": cfg["model"], "object": "model", "owned_by": "modelscope"}
+        ],
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="thiter-mcp",
+        description="thiter MCP 服务：把魔搭 ModelScope 大模型包装成 MCP 工具",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "streamable-http"],
+        default=os.environ.get("CHUNMIAO_TRANSPORT", "stdio"),
+        help="传输方式，默认 stdio（魔搭托管部署使用 stdio）",
+    )
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("CHUNMIAO_HOST", "127.0.0.1"),
+        help="streamable-http 模式监听地址",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("CHUNMIAO_PORT", "8000")),
+        help="streamable-http 模式监听端口",
+    )
+    args = parser.parse_args()
+
+    if not _config()["token"]:
+        # stdio 模式下严禁写 stdout（协议通道），日志一律走 stderr
+        print("⚠️ 未检测到 MAS_TOKEN 环境变量，调用工具时会报错", file=sys.stderr)
+
+    if args.transport == "stdio":
+        mcp.run(transport="stdio")
+    else:
+        print(
+            f"🚀 thiter MCP 服务启动（streamable-http）: http://{args.host}:{args.port}/mcp",
+            file=sys.stderr,
+        )
+        mcp.run(transport="streamable-http", host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

thiter_mcp-0.1.0/tests/e2e_test.py

@@ -0,0 +1,319 @@
+"""thiter MCP 端到端测试：stdio + streamable-http 双传输，覆盖正常/错误/缺令牌路径。
+
+运行方式：
+    PYTHONPATH=src python tests/e2e_test.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import socket
+import sys
+import threading
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.client.streamable_http import streamable_http_client
+
+from stub_upstream import start_stub  # noqa: E402  (tests 目录在同级)
+
+SRC = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src"))
+
+PASSED: list[str] = []
+FAILED: list[str] = []
+
+
+def check(name: str, cond: bool, detail: str = "") -> None:
+    if cond:
+        PASSED.append(name)
+        print(f"  ✅ {name}")
+    else:
+        FAILED.append(f"{name} :: {detail}")
+        print(f"  ❌ {name} :: {detail}")
+
+
+def free_port() -> int:
+    s = socket.socket()
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+def server_env(
+    base_url: str,
+    token: str | None = "test-token",
+    extra: dict | None = None,
+) -> dict:
+    env = dict(os.environ)
+    env["PYTHONPATH"] = SRC + os.pathsep + env.get("PYTHONPATH", "")
+    env["CHUNMIAO_BASE_URL"] = base_url
+    if token is None:
+        env.pop("MAS_TOKEN", None)
+    else:
+        env["MAS_TOKEN"] = token
+    for k, v in (extra or {}).items():
+        if v is None:
+            env.pop(k, None)
+        else:
+            env[k] = v
+    return env
+
+
+def stdio_params(
+    base_url: str,
+    token: str | None = "test-token",
+    extra: dict | None = None,
+) -> StdioServerParameters:
+    return StdioServerParameters(
+        command=sys.executable,
+        args=["-m", "thiter_mcp"],
+        env=server_env(base_url, token, extra),
+    )
+
+
+def tool_payload(result) -> dict:
+    """从 CallToolResult 中取结构化结果。"""
+    if result.structured_content:
+        return result.structured_content
+    for block in result.content:
+        if getattr(block, "type", None) == "text":
+            return json.loads(block.text)
+    raise AssertionError(f"工具无有效返回: {result}")
+
+
+async def test_stdio(base_url: str) -> None:
+    print("\n[1] stdio 传输测试")
+    params = stdio_params(base_url)
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            tools = await session.list_tools()
+            names = {t.name for t in tools.tools}
+            check("list_tools 暴露 chat 与 list_models", {"chat", "list_models"} <= names, str(names))
+
+            chat_tool = next(t for t in tools.tools if t.name == "chat")
+            schema = chat_tool.input_schema
+            check(
+                "chat 入参 messages 为必填",
+                "messages" in schema.get("properties", {})
+                and "messages" in schema.get("required", []),
+                json.dumps(schema, ensure_ascii=False),
+            )
+
+            # 正常调用
+            r = await session.call_tool(
+                "chat",
+                {
+                    "messages": [{"role": "user", "content": "你好"}],
+                    "temperature": 0.7,
+                    "max_tokens": 100,
+                },
+            )
+            check("chat 正常调用无错误", not r.is_error, str(r.content))
+            payload = tool_payload(r)
+            check(
+                "chat 返回 stub 内容",
+                payload.get("content") == "stub回复[你好]",
+                json.dumps(payload, ensure_ascii=False),
+            )
+            check(
+                "chat 返回 usage/finish_reason",
+                payload.get("finish_reason") == "stop"
+                and (payload.get("usage") or {}).get("total_tokens") == 33,
+                json.dumps(payload, ensure_ascii=False),
+            )
+
+            # 上游 500 错误路径
+            r = await session.call_tool(
+                "chat", {"messages": [{"role": "user", "content": "请触发错误"}]}
+            )
+            check("chat 上游报错时 isError=True", r.is_error, str(r.content))
+            check(
+                "chat 错误信息含 500 与上游信息",
+                "500" in str(r.content) and "stub upstream error" in str(r.content),
+                str(r.content),
+            )
+
+            # 错误令牌路径
+            r = await session.call_tool(
+                "list_models",
+            )
+            check("list_models 正常返回", not r.is_error, str(r.content))
+            models = tool_payload(r)
+            ids = [m.get("id") for m in models.get("data", [])]
+            check(
+                "list_models 返回 stub 模型列表",
+                "qwen/qwen3.5-35b-a3b" in ids and "qwen/qwen-plus" in ids,
+                json.dumps(models, ensure_ascii=False),
+            )
+
+
+async def test_stdio_bad_token(base_url: str) -> None:
+    print("\n[2] stdio 错误令牌测试（上游 401）")
+    params = stdio_params(base_url, token="wrong-token")
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            r = await session.call_tool(
+                "chat", {"messages": [{"role": "user", "content": "hi"}]}
+            )
+            check("错误令牌时 isError=True", r.is_error, str(r.content))
+            check(
+                "错误信息含 HTTP 401",
+                "401" in str(r.content),
+                str(r.content),
+            )
+            check(
+                "错误信息不泄露令牌",
+                "wrong-token" not in str(r.content),
+                str(r.content),
+            )
+
+
+async def test_stdio_no_token(base_url: str) -> None:
+    print("\n[3] stdio 缺 MAS_TOKEN 测试")
+    params = stdio_params(base_url, token=None)
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            r = await session.call_tool(
+                "chat", {"messages": [{"role": "user", "content": "hi"}]}
+            )
+            check("缺令牌时 isError=True", r.is_error, str(r.content))
+            check(
+                "缺令牌提示配置 MAS_TOKEN",
+                "MAS_TOKEN" in str(r.content),
+                str(r.content),
+            )
+
+
+async def test_streamable_http(base_url: str) -> None:
+    print("\n[4] streamable-http 传输测试（自托管模式）")
+    port = free_port()
+    env = server_env(base_url)
+    proc = await asyncio.create_subprocess_exec(
+        sys.executable,
+        "-m",
+        "thiter_mcp",
+        "--transport",
+        "streamable-http",
+        "--host",
+        "127.0.0.1",
+        "--port",
+        str(port),
+        env=env,
+        stdout=asyncio.subprocess.DEVNULL,
+        stderr=asyncio.subprocess.DEVNULL,
+    )
+    try:
+        url = f"http://127.0.0.1:{port}/mcp"
+        # 等待服务就绪
+        for _ in range(50):
+            try:
+                async with streamable_http_client(url) as (read, write):
+                    async with ClientSession(read, write) as session:
+                        await session.initialize()
+                        tools = await session.list_tools()
+                        check(
+                            "HTTP 模式暴露 chat 与 list_models",
+                            {"chat", "list_models"} <= {t.name for t in tools.tools},
+                        )
+                        r = await session.call_tool(
+                            "chat", {"messages": [{"role": "user", "content": "HTTP测试"}]}
+                        )
+                        check("HTTP 模式 chat 调用成功", not r.is_error, str(r.content))
+                        payload = tool_payload(r)
+                        check(
+                            "HTTP 模式返回 stub 内容",
+                            payload.get("content") == "stub回复[HTTP测试]",
+                            json.dumps(payload, ensure_ascii=False),
+                        )
+                break
+            except Exception:
+                await asyncio.sleep(0.2)
+        else:
+            check("HTTP 服务可就绪", False, "连接超时")
+    finally:
+        proc.terminate()
+        await proc.wait()
+
+
+async def test_stdio_api_key(base_url: str) -> None:
+    print("\n[5] 访问密钥测试（CHUNMIAO_API_KEY=secret-123）")
+    extra = {"CHUNMIAO_API_KEY": "secret-123"}
+
+    # 缺 key
+    params = stdio_params(base_url, extra=extra)
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            r = await session.call_tool(
+                "chat", {"messages": [{"role": "user", "content": "hi"}]}
+            )
+            check("缺 key 时 isError=True", r.is_error, str(r.content))
+            check(
+                "缺 key 提示提供 key",
+                "key" in str(r.content),
+                str(r.content),
+            )
+
+    # 错误 key
+    params = stdio_params(base_url, extra=extra)
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            r = await session.call_tool(
+                "chat",
+                {"messages": [{"role": "user", "content": "hi"}], "key": "wrong"},
+            )
+            check("错误 key 时 isError=True", r.is_error, str(r.content))
+
+    # 正确 key
+    params = stdio_params(base_url, extra=extra)
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            r = await session.call_tool(
+                "chat",
+                {
+                    "messages": [{"role": "user", "content": "带密钥"}],
+                    "key": "secret-123",
+                },
+            )
+            check("正确 key 时调用成功", not r.is_error, str(r.content))
+            payload = tool_payload(r)
+            check(
+                "正确 key 返回 stub 内容",
+                payload.get("content") == "stub回复[带密钥]",
+                json.dumps(payload, ensure_ascii=False),
+            )
+            r = await session.call_tool("list_models", {"key": "secret-123"})
+            check("list_models 正确 key 成功", not r.is_error, str(r.content))
+
+
+async def main() -> None:
+    stub, port = start_stub()
+    threading.Thread(target=stub.serve_forever, daemon=True).start()
+    base_url = f"http://127.0.0.1:{port}/v1"
+    try:
+        await test_stdio(base_url)
+        await test_stdio_bad_token(base_url)
+        await test_stdio_no_token(base_url)
+        await test_streamable_http(base_url)
+        await test_stdio_api_key(base_url)
+    finally:
+        stub.shutdown()
+
+    print(f"\n===== 结果: {len(PASSED)} 通过, {len(FAILED)} 失败 =====")
+    if FAILED:
+        for f in FAILED:
+            print(f"  - {f}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

thiter_mcp-0.1.0/tests/stub_upstream.py

@@ -0,0 +1,116 @@
+"""本地测试用 stub：模拟魔搭 api-inference 的 /v1 接口。
+
+- GET  /v1/models            返回模型列表（校验 Bearer test-token）
+- POST /v1/chat/completions  返回 OpenAI 格式补全；消息含「触发错误」时返回 500
+"""
+
+from __future__ import annotations
+
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+TOKEN = "test-token"
+
+
+class StubHandler(BaseHTTPRequestHandler):
+    def _json(self, code: int, obj: dict) -> None:
+        body = json.dumps(obj, ensure_ascii=False).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _authorized(self) -> bool:
+        return self.headers.get("Authorization") == f"Bearer {TOKEN}"
+
+    def do_GET(self) -> None:
+        if not self._authorized():
+            self._json(401, {"error": {"message": "invalid token"}})
+            return
+        if self.path == "/v1/models":
+            self._json(
+                200,
+                {
+                    "object": "list",
+                    "data": [
+                        {
+                            "id": "qwen/qwen3.5-35b-a3b",
+                            "object": "model",
+                            "owned_by": "modelscope",
+                        },
+                        {
+                            "id": "qwen/qwen-plus",
+                            "object": "model",
+                            "owned_by": "modelscope",
+                        },
+                    ],
+                },
+            )
+        else:
+            self._json(404, {"error": {"message": "not found"}})
+
+    def do_POST(self) -> None:
+        if not self._authorized():
+            self._json(401, {"error": {"message": "invalid token"}})
+            return
+        length = int(self.headers.get("Content-Length", 0))
+        try:
+            payload = json.loads(self.rfile.read(length) or b"{}")
+        except json.JSONDecodeError:
+            self._json(400, {"error": {"message": "bad json"}})
+            return
+
+        if self.path != "/v1/chat/completions":
+            self._json(404, {"error": {"message": "not found"}})
+            return
+        if payload.get("stream"):
+            self._json(400, {"error": {"message": "stub does not support stream"}})
+            return
+
+        messages = payload.get("messages") or []
+        last_user = next(
+            (m.get("content", "") for m in reversed(messages) if m.get("role") == "user"),
+            "",
+        )
+        if "触发错误" in last_user:
+            self._json(500, {"error": {"message": "stub upstream error"}})
+            return
+
+        self._json(
+            200,
+            {
+                "id": "chatcmpl-stub",
+                "object": "chat.completion",
+                "model": payload.get("model", "unknown"),
+                "choices": [
+                    {
+                        "index": 0,
+                        "message": {
+                            "role": "assistant",
+                            "content": f"stub回复[{last_user}]",
+                        },
+                        "finish_reason": "stop",
+                    }
+                ],
+                "usage": {
+                    "prompt_tokens": 11,
+                    "completion_tokens": 22,
+                    "total_tokens": 33,
+                },
+            },
+        )
+
+    def log_message(self, *args) -> None:  # 静默
+        pass
+
+
+def start_stub() -> tuple[ThreadingHTTPServer, int]:
+    server = ThreadingHTTPServer(("127.0.0.1", 0), StubHandler)
+    return server, server.server_address[1]
+
+
+if __name__ == "__main__":
+    server, port = start_stub()
+    print(f"stub listening on http://127.0.0.1:{port}/v1")
+    server.serve_forever()