Skip to content
Back to search

model_mcp

把智能体当作 OpenAI 兼容模型后端:通过 MCP 长轮询派活,支持流式输出、工具调用与思考(reasoning_content)。Agent-as-model backend over MCP with an OpenAI-compatible API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/windy-x211--model-mcp/badge.svg)](/listings/windy-x211--model-mcp)

HTML

<a href="/listings/windy-x211--model-mcp"><img src="/api/listings/windy-x211--model-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 201 lines
  1. # model-mcp
  2. 把**智能体 A** 变成对外可用的 **OpenAI 兼容模型服务**,通过 MCP 派活。
  3. - 外部软件(任何 OpenAI SDK / Cline / Dify / 自研系统)调用 `POST /v1/chat/completions`;
  4. - 网关把请求入队,A 用 MCP 工具 `service_wait` **阻塞等待**,领到请求体;
  5. - A 自己推理,用 `stream_emit` 推流、`submit_result` 定稿;
  6. - 网关按 OpenAI 格式把结果回给软件,支持 **流式 / 工具调用 / 思考(reasoning_content)**。
  7. ## 架构
  8. ```
  9. 外部软件(OpenAI 兼容客户端)
  10. │ POST /v1/chat/completions (stream 可选)
  11. ▼
  12. model-mcp 网关(FastAPI + MCP SDK,单进程)
  13. ├─ 队列 / 租约 / 看门狗
  14. ├─ SSE 差分、心跳、回放
  15. └─ /mcp(MCP streamable-http,可选)
  16. ▲ │
  17. │ 工具返回(请求体) │ 工具调用(领活/推流/定稿)
  18. ▼ ▼
  19. 智能体 A(你自己,负责真正的推理)
  20. ```
  21. ## 快速开始
  22. **最省事的方式:双击 `启动模型服务.bat`** —— 无控制台启动桌面窗口(Tk 控制台),窗口内自动在 8765 端口起服务。
  23. 手动启动:
  24. ```powershell
  25. cd F:\PythonProjects\TraeProjects\模型服务mcp
  26. # 1) 装依赖(mcp 必须是 2.x)
  27. F:\anaconda3\python.exe -m pip install -r requirements.txt
  28. # 2) 启动
  29. # 桌面窗口(推荐,内含可复制的 MCP 配置 / 接口信息)
  30. F:\anaconda3\python.exe -m model_mcp.tk_ui --port 8765
  31. # 浏览器控制台版(老方案,仍可用)
  32. F:\anaconda3\python.exe -m model_mcp.launcher --port 8765
  33. # stdio 模式:给桌面智能体连(同时会拉起 HTTP 侧)
  34. F:\anaconda3\python.exe -m model_mcp --transport stdio --port 8765
  35. # 纯 HTTP 模式:A 通过 http://127.0.0.1:8765/mcp 连,软件走 /v1
  36. F:\anaconda3\python.exe -m model_mcp --transport http --port 8765
  37. # 3) 验证
  38. curl.exe http://127.0.0.1:8765/v1/models
  39. ```
  40. ## 桌面窗口(Tk)
  41. 轻量 Tk 窗口,不依赖浏览器。启动后 120ms 内自动起服务(端口可在窗口顶部改),状态灯每 2 秒刷新。
  42. | 标签页 | 内容 | 可复制 |
  43. |---|---|---|
  44. | 1 · MCP 配置 | stdio(JSON:python 路径 / `args` / `cwd` / `PYTHONPATH`)↔ HTTP(URL)单选切换;MCP 端点 | ✅ 配置块 / MCP 地址 |
  45. | 2 · 模型接口 | Base URL、API Key、模型名;openai SDK 流式样例、curl 一行版、端点表 | ✅ 各代码块 / Base URL |
  46. | 3 · 接活提示词 | 发给 A 的 `WORKER_PROMPT` 全文 | ✅ |
  47. | 4 · 状态与日志 | 服务地址、在线 worker、队列深度、超时设置;滚动运行日志 | ✅ 清空日志 |
  48. 窗口顶部:端口输入、启动 / 停止、浏览器版(打开同一份 Web 控制台)。
  49. 关窗时若服务仍在跑会先确认,确认后停服再退出;代码块是只读控件,`Ctrl+C` 复制选中内容,无选区则复制整块。
  50. - **单实例**:同一端口只允许一个窗口,重复双击只会把已存在的窗口切到前台后退出,不会再叠出第二个窗口抢端口;
  51. - **窗口可见**:被系统以隐藏 / 最小化方式拉起时会自动还原并置前;
  52. - **日志**:`logs/tk_ui.log`(滚动 1MB×3)。双击没反应先看这个文件,或改双击 `启动模型服务(调试).bat`(保留控制台,报错直接可见)。
  53. `launcher`(Web 版)与 Tk 版共用同一套 `ServerController`,都可以用 `--port` 指定端口。
  54. ## 浏览器控制台(UI)
  55. 服务起来后打开 <http://127.0.0.1:8765/>,页面按当前运行环境自动生成内容(与 Tk 窗口同一份数据源):
  56. | 区块 | 内容 | 可复制 |
  57. |---|---|---|
  58. | 1 | MCP 配置:stdio(JSON,含 python 路径 / 项目目录 / 端口)、HTTP(URL)+ MCP 端点 | ✅ |
  59. | 2 | 模型接口:Base URL、API Key、模型名、openai SDK / curl / 原生 HTTP 三种示例、端点表 | ✅ |
  60. | 3 | 发给 A 的接活提示词全文 | ✅ |
  61. | 4 | 实时状态(worker 在线、队列)与启动命令 | ✅ |
  62. - 顶部徽标每 2 秒刷新:服务状态、worker 在线数、队列长度;
  63. - 复制走的 `navigator.clipboard`,失败时自动降级为 `execCommand`;
  64. - 配置数据来自 `GET /ui/info`,`/v1` 接口与 `/mcp` 端点同端口共存。
  65. 不想真接智能体时,用自带的模拟 A 跑通链路:
  66. ```powershell
  67. # 终端 1:起服务
  68. F:\anaconda3\python.exe -m model_mcp --transport http --port 8765
  69. # 终端 2:模拟 A 接活
  70. F:\anaconda3\python.exe examples\demo_agent_a.py
  71. # 终端 3:模拟软件调用
  72. F:\anaconda3\python.exe examples\openai_client.py --stream
  73. ```
  74. ## A 侧工作循环
  75. ```text
  76. service_ready → service_wait(阻塞,最多 40s)
  77. ├─ status=idle → 立刻再 service_wait
  78. └─ status=request → 读 messages/tools/params
  79. ├─ stream_emit(累计快照,可多次)
  80. └─ submit_result(定稿)
  81. → 回到 service_wait
  82. ```
  83. 把 `examples/agent_a_prompt.md` 里的提示词直接发给 A 即可让它常驻接活。
  84. ## MCP 工具
  85. | 工具 | 作用 | 关键参数 |
  86. |---|---|---|
  87. | `service_ready` | 上报在岗与能力 | `worker_id`, `models`, `supports`, `capacity` |
  88. | `service_wait` | **阻塞等待请求**(长轮询) | `worker_id`, `timeout_s`, `models` |
  89. | `stream_emit` | 流式推送(累计快照,网关自动差分) | `request_id`, `content`, `reasoning`, `tool_calls` |
  90. | `submit_result` | 定稿 | `request_id`, `content`, `reasoning`, `tool_calls`, `finish_reason`, `usage` |
  91. | `fail_result` | 报错 | `request_id`, `message`, `code` |
  92. | `request_status` | 查状态(是否断连、剩余预算) | `request_id` |
  93. | `service_stats` | 网关与队列状态 | — |
  94. | `service_offline` | 下线 | `worker_id` |
  95. 约定:
  96. - `content` / `reasoning` / `tool_calls` 都传**累计全量**(不是增量),网关做 diff;
  97. - `tool_calls` 是 OpenAI 结构数组,`function.arguments` 是 JSON 字符串;
  98. - 返回 `client_gone=true` 表示调用方已断开,直接放弃该请求;
  99. - 请求超时(默认 600s)、A 失联(默认 120s 无产出)都会自动收尾/重派。
  100. ## OpenAI 兼容接口
  101. | 方法 | 路径 | 说明 |
  102. |---|---|---|
  103. | GET | `/v1/models` | `agent-a` 等模型,附 `x_online` / `x_supports` |
  104. | POST | `/v1/chat/completions` | 支持 `stream:true`(SSE),思考走 `reasoning_content` |
  105. | GET | `/health` `/queue` | 存活与队列状态 |
  106. | POST | `/mcp` | MCP streamable-http 端点 |
  107. ```powershell
  108. curl.exe http://127.0.0.1:8765/v1/chat/completions `
  109. -H "Content-Type: application/json" `
  110. -d '{\"model\":\"agent-a\",\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}]}'
  111. ```
  112. ## 接入配置
  113. Trae / Cline 的 `mcp.json`(`examples/mcp_config_trae.json`):
  114. ```json
  115. {
  116. "mcpServers": {
  117. "model-mcp": {
  118. "command": "F:\\anaconda3\\python.exe",
  119. "args": ["-m", "model_mcp", "--transport", "stdio", "--port", "8765"],
  120. "cwd": "F:\\PythonProjects\\TraeProjects\\模型服务mcp",
  121. "env": { "PYTHONPATH": "F:\\PythonProjects\\TraeProjects\\模型服务mcp" }
  122. }
  123. }
  124. }
  125. ```
  126. Claude Desktop(`%APPDATA%\Claude\claude_desktop_config.json`)写法相同,见 `examples/mcp_config_claude.json`。
  127. 支持 HTTP 的客户端(或另一台机器上的 A):
  128. ```json
  129. { "mcpServers": { "model-mcp": { "url": "http://127.0.0.1:8765/mcp" } } }
  130. ```
  131. ## 配置说明(config.yaml)
  132. | 键 | 默认 | 说明 |
  133. |---|---|---|
  134. | `server.host` / `port` | 127.0.0.1 / 8765 | 监听地址;放开给局域网用 `0.0.0.0` |
  135. | `server.auth_token` | null | 设置后 `/v1/*` 需 `Authorization: Bearer <token>` |
  136. | `models[].name` | agent-a | 软件侧看到的模型名 |
  137. | `queue.wait_timeout_s` | 40 | `service_wait` 单次阻塞上限,**要小于 MCP 客户端超时** |
  138. | `queue.request_deadline_s` | 600 | 单请求总预算,超时回 504 |
  139. | `queue.lease_s` | 120 | A 认领后无产出多久算失联 |
  140. | `queue.reject_when_no_worker` | true | 没有 A 在岗时直接 503 |
  141. | `stream.replay_chunk_chars` / `replay_delay_ms` | 24 / 30 | A 一次性给全文时的回放粒度 |
  142. | `stream.heartbeat_s` | 15 | SSE 心跳间隔 |
  143. ## 测试
  144. ```powershell
  145. F:\anaconda3\python.exe tests\smoke_core.py # 核心:队列/流式/工具/断连
  146. F:\anaconda3\python.exe tests\smoke_mcp_stdio.py # 端到端:stdio MCP + HTTP
  147. F:\anaconda3\python.exe tests\smoke_mcp_http.py # 端到端:MCP over HTTP
  148. ```
  149. ## 常见问题
  150. | 现象 | 原因 / 处理 |
  151. |---|---|
  152. | 软件收到 503 `no_worker` | A 没连上,或没在循环调 `service_wait` |
  153. | A 的 `service_wait` 报超时 | 智能体软件的单次工具调用超时偏小,把 `wait_timeout_s` 调低到 20~30 |
  154. | 流式没有打字效果 | A 只调了 `submit_result`;确认 `stream.replay_chunk_chars > 0` 会自动回放 |
  155. | 断线后 A 还在写 | 看 `stream_emit` 返回的 `client_gone`,为 true 立即停 |
  156. | 中文乱码 | 网关全链路 UTF-8;Windows 控制台看日志乱码不影响接口 |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.