Codex 调用桥 bodazi-na/codex-MCP-dsh

Codex 通过 MCP 调用 DSH

把本机安装的 DeepSeek Harness（dsh） 挂成 MCP server，Codex 就能像调用内置工具一样调用它：dsh_task 派一个真实任务（DSH 用自己的技能、记忆和工作区执行）， dsh_status 自检接线。每次调用都会留下一个真实的 DSH 会话，以及一行可审计的调用记录。

flowchart LR
C[Codex] -->|MCP stdio: dsh_task / dsh_status| M[dsh_mcp.mcp_server]
M -->|dsh --profile headless --json| D[DeepSeek Harness]
D -->|读/写工作区、调工具、用技能| W[(workspace + ~/.dsh)]
D -.->|sessionId（可续接）| M
M -->|answer + session_id| C

本机实测：{"answer": "MCP-OK", "session_id": "session-77f0b613-…", "exit_code": 0}；
端到端流程与排障全过程见 docs/codex-mcp-dsh.md。

快速开始（三步）

1) 依赖
uv sync

2) 把配置贴进 Codex（把 <DSH_HOME>、<repo> 换成你的路径）完整可复制版本：examples/codex-config.toml ~/.codex/config.toml 里追加 [mcp_servers.dsh] 与 [mcp_servers.dsh.env]

3) 验证——二选一
python scripts\mcp_smoke.py --task "Reply with exactly: MCP-OK" # 命令行验证
或在 Codex 里说：Call the dsh_status tool exactly once, then reply with the raw JSON

~/.codex/config.toml 的内容（路径改成你自己的）：

[mcp_servers.dsh]
command = '<DSH_HOME>\dsh-runtimes\dsh-primary-runtime\dependencies\python\python.exe'
args = ["-m", "dsh_mcp.mcp_server"]
startup_timeout_sec = 120

[mcp_servers.dsh.env]
PYTHONPATH = '<repo>\src;<repo>\.venv\Lib\site-packages;<repo>\.venv\Lib\site-packages\win32;<repo>\.venv\Lib\site-packages\win32\lib'
DSH_MCP_WORKDIR = '<repo>'
DSH_MCP_STATE_DIR = '<repo>\.dsh-a2a'
DSH_MCP_CALL_LOG = '<repo>\logs\mcp_calls.jsonl'

改完 Codex 的配置要重启 Codex 才生效。

两个工具

| 工具 | 签名 | 作用 |
| dsh_task | prompt, session_id?, timeout_seconds?, json_output? | 跑一个任务并返回最终答复；把返回的 session_id 传回来即续接同一会话；json_output=true 时额外返回 session / exit_code / usage |
| dsh_status | probe_boot? | 报告解析到的 launcher、profile、工作区、状态目录；probe_boot=true 时顺带做一次 profile 预检 |

工具面刻意只有两个——每个工具的 schema 每轮都要付上下文成本。

配置为什么长这样（三个必填点）

| 点 | 缺了会怎样 |
| command 用工作区外的解释器 | 工作区内的 .venv 受 Windows 沙箱限制，它派生的 dsh 写不了 ~/.dsh → EPERM … cordis.yml，每次任务都失败 |
| env.PYTHONPATH | 运行时解释器里没有 dsh_mcp 这个包（它是本仓库源码）→ server 启动即 ModuleNotFoundError: No module named 'dsh_mcp' |
| PYTHONPATH 里带 win32 与 win32\lib | mcp 2.x 在 Windows 上 import pywintypes（pywin32），而 pywin32 靠 .pth 注入路径——PYTHONPATH 不处理 .pth → No module named 'pywintypes' |

排障：失败长什么样

最坑的一种是静默失败：少写 env 时 Codex 不会报"服务器起不来"，它只是拿不到工具，模型会说"我的工具列表里没有 dsh_status"（MCP 只返回空 resources）。

诊断第一条命令：

& '<DSH_HOME>\dsh-runtimes\dsh-primary-runtime\dependencies\python\python.exe' -m dsh_mcp.mcp_server --check
正常：打印 launcher / profile / workdir / state dir

| 现象 | 原因 | 处理 |
| 模型看不到 dsh_status / 只有空 resources | 配置缺 env，server 启动即崩 | 补 [mcp_servers.dsh.env]，见上；用 --check 复现 |
| ModuleNotFoundError: No module named 'dsh_mcp' | 解释器里没装本仓库源码 | PYTHONPATH 加 <repo>\src |
| No module named 'pywintypes' | 少了 pywin32 的两个目录 | PYTHONPATH 加 …\site-packages\win32;…\site-packages\win32\lib |
| EPERM … .dsh\profiles\…\cordis.yml | 解释器在工作区内（沙箱限制） | 换工作区外的解释器（如上），或把 DSH_MCP_DSH_HOME 指到可写目录 |
| could not start … piped stdio: WinError 5 | 在沙箱里跑 | 在普通终端里跑 |
| 改完配置没反应 | MCP server 在 Codex 启动时拉起 | 重启 Codex |

调用记录（审计「谁调过我」）

每次工具调用都会追加一行 JSONL（DSH_MCP_CALL_LOG，默认 logs\mcp_calls.jsonl）：

python scripts\mcp_calls.py --all

when (local) tool ok ms session prompt
2026-10-05 21:29:53 dsh_status ok -
2026-10-05 21:29:57 dsh_task ok 3875 session-1d31559f-… Reply with exactly: CALL-LOG-OK

记录字段：ts(UTC) / tool / ok / duration_ms / prompt_preview / session_id /
exit_code / usage，失败时记诊断后的 error。要进一步取证（模型是否看到工具、每次任务对应的真实 DSH 会话目录等），看 docs/codex-mcp-dsh.md 的「调用记录在哪查」一节。

目录结构（MCP 相关）

src/dsh_mcp/
mcp_server.py MCP server：两个工具 + 调用审计（stdio / streamable-http） dsh_runner.py 执行 dsh --profile headless --json，解析事件、超时、取消 config.py 环境变量、launcher 探测（自动跳过失效 shim） session_store.py session_id 的持久化（支持续接） stub_runner.py 假执行体（--stub，用来零成本验证客户端接线） scripts/ mcp_smoke.py 真实 MCP 客户端：列工具 + dsh_status + 可选跑一个任务 mcp_calls.py 调用记录查看器 fake_dsh.py 离线测试用的假 launcher tests/ 16 条契约测试（离线可跑） examples/ Codex TOML / 通用 stdio JSON / WorkBuddy HTTP docs/ 端到端流程与实测记录 start-mcp.cmd HTTP 传输启动器（默认 http://127.0.0.1:9102/mcp） _common.cmd 解释器与 PYTHONPATH 解析（工作区外解释器 + pywin32 目录）

- HTTP 传输（给只吃远端 URL 的客户端，如 WorkBuddy 的 mcp.json）： .\start-mcp.cmd → {"mcpServers": {"dsh": {"url": "http://127.0.0.1:9102/mcp"}}}
- 契约测试：uv run pytest -q（16 passed）；CI 见 .github/workflows/ci.yml（windows-latest）。

许可

MIT，见 LICENSE。