Skip to main content
Glama
Lavender3533

dsh-codex-bridge

by Lavender3533

dsh-codex-bridge

DSH 插件 / MCP 服务器 — 让 Codex、Claude Code、Cursor 等 MCP 客户端将 DSH 当作外部可恢复子代理使用。

flowchart LR
  C[Codex / Claude Code / Cursor / any MCP client] -->|MCP SSE| B[DSH Bridge :3101]
  B -->|spawn detached| S[Supervisor]
  S -->|dsh --profile headless| W[DSH Worker]
  S -->|持久化| F[(~/.dsh/tasks/)]

Features

  • 5 MCP tools: dsh_task_start, dsh_task_poll, dsh_task_cancel, dsh_task_list, dsh_get_status

  • Async task model: start returns immediately, poll for events via cursor

  • Resumable: bridge restart recovers running tasks, orphans dead ones

  • Visual dashboard: http://127.0.0.1:3101/agents — frosted glass UI

  • REST API: full task management API

  • SSE stream: real-time task events

  • Security: bearer token, 127.0.0.1 only, cwd restriction

Related MCP server: iStdBMAD

Quick Start

# 1. Install as DSH plugin
dsh plugin --profile web add dsh-codex-bridge

# 2. Set token (optional, has dev default)
export DSH_CODEX_BRIDGE_TOKEN="your-32-char-token"

# 3. Start DSH
dsh web

# 4. Open dashboard
open http://127.0.0.1:3101/agents

MCP Tools

Tool

Description

dsh_task_start

Start an async task, returns taskId + dashboardUrl

dsh_task_poll

Read events incrementally by cursor (≤64 KiB)

dsh_task_cancel

Cancel a running task

dsh_task_list

List all tasks with status

dsh_get_status

Bridge health and stats

State Machine

queued → running → succeeded
                 → failed
                 → timed_out
                 → cancelled
                 → orphaned

Codex Configuration

[mcp_servers.dsh_agent]
url = "http://127.0.0.1:3101/sse"
bearer_token_env_var = "DSH_CODEX_BRIDGE_TOKEN"
startup_timeout_sec = 10
tool_timeout_sec = 45
enabled_tools = [
  "dsh_task_start",
  "dsh_task_poll",
  "dsh_task_cancel",
  "dsh_task_list",
  "dsh_get_status"
]

API Endpoints

Method

Path

Description

GET

/api/agents/tasks

List tasks

GET

/api/agents/tasks/:taskId

Task detail

POST

/api/agents/tasks

Create task

POST

/api/agents/tasks/:taskId/cancel

Cancel task

POST

/api/agents/tasks/:taskId/retry

Retry task

GET

/api/agents/tasks/:taskId/events

Get events (cursor)

GET

/api/agents/tasks/:taskId/files/:file

Download artifact

GET

/api/agents/stream

SSE event stream

Dashboard

The dashboard at http://127.0.0.1:3101/agents provides:

  • Left panel: task list with status filter

  • Center: real-time event stream (stdout/stderr/status)

  • Right panel: task details (PID, timing, artifacts)

  • Dark/light mode: follows system preference

Architecture

dsh-codex-bridge/
├── lib/
│   ├── index.js          DSH plugin entry + MCP server + REST API
│   ├── dashboard.html    Visual dashboard (single-file HTML/CSS/JS)
│   └── supervisor.mjs    Detached supervisor process
├── package.json
├── cordis.patch.yml
└── LICENSE

License

MIT

Related MCP Connectors

Related MCP Servers