MCP Dispatch

mcp调度

通过以下方式为AI编码代理发送本地代理间消息 主控程序.

在同一台机器上运行的多个Claude Code会话（或任何兼容MCP的代理）可以通过共享文件系统中继相互发送消息。没有服务器进程，没有端口，没有网络——只有目录和具有原子写入的JSON文件。

特性

• 非破坏性消息传递 --消息会一直存在，直到被明确确认。不再有因崩溃或压缩而丢失的消息。
• 线程 --将消息分组到对话中 thread_id 和 reply_to.
• 结构化有效载荷 --在人类可读的消息旁边附加机器可读的数据。
• TTL和must_read --时间敏感的邮件会自动过期。关键信息在被确认之前会一直存在。
• 交货收据 — peek() 显示您发送的邮件的已读/未读状态。
• 配置驱动 --TOML配置用于代理名册、目录和限制。或者在没有阵容的情况下保持活力。
• 零基础设施 --文件系统中继在进程崩溃中幸存下来。没有要管理的守护进程。

快速开始

1.安装

需要Python 3.11+和 紫外线.

git clone https://github.com/sophia-labs/mcp-dispatch.git
cd mcp-dispatch
uv sync

对于消息到达时的实时stderr警报（可选）：

uv sync --extra watch

2.配置克劳德代码

添加到您的 ~/.claude.json:

{
  "mcpServers": {
    "dispatch": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-dispatch", "python", "server.py"],
      "env": {
        "MCP_DISPATCH_AGENT_ID": "alice"
      }
    }
  }
}

每个Claude Code窗口都需要一个唯一的 MCP_DISPATCH_AGENT_ID.

3.发送消息

从任何Claude Code会话：

Agent alice: dispatch("Hey bob, I pushed the fix", target="bob")
Agent bob:   peek()  →  sees alice's message
Agent bob:   ack(["msg-abc12345"])  →  message removed

工具

派遣

dispatch(
    message="Deployed to staging",
    target="all",           # or a specific agent name
    priority="normal",      # "normal" or "urgent"
    thread_id="deploy-123", # optional: group into conversation
    reply_to="msg-abc",     # optional: reference specific message
    payload={"commit": "abc123", "env": "staging"},  # optional: structured data
    ttl=3600,               # optional: expire after 1 hour
    must_read=True,         # optional: survive TTL, require explicit ack
)

窥视

peek()                          # new (unread) messages only
peek(include_read=True)         # all unacknowledged messages
peek(thread_id="deploy-123")    # filter by thread

确认

ack(message_ids=["msg-abc", "msg-def"])  # delete specific messages

配置

创建 ~/.config/mcp-dispatch/config.toml:

# Agent roster (omit for dynamic registration — any name accepted)
agents = ["alice", "bob", "carol"]

# Message directory (default: ~/.config/mcp-dispatch/messages)
dispatch_dir = "~/.config/mcp-dispatch/messages"

# Maximum message size in bytes (default: 65536)
max_message_bytes = 65536

# Default TTL in seconds (0 = no expiry)
default_ttl = 0

# Custom MCP instructions template (optional)
# Placeholders: {agent_id}, {agent_list}
# instructions = "You are {agent_id}. Available agents: {agent_list}."

环境变量

动态模式

当否 agents 名册已配置，任何代理名称都可以接受。收件箱目录是按需创建的。这更灵活，但不太安全（拼写错误会产生幻影代理）。

运作原理

• 每个代理都有一个收件箱目录({dispatch_dir}/{agent_name}/)
• 消息是以原子方式编写的JSON文件（tmp+重命名）
• 通过PID文件跟踪存在情况 {dispatch_dir}/.presence/
• 消息有状态： pending → read → 已确认（已删除）
• 背负式交付：每个工具响应都附有待处理的消息
• TTL清理在读取操作时延迟运行
• 可选监视器为操作员打印stderr警报

消息格式

{
  "id": "msg-a1b2c3d4",
  "from": "alice",
  "to": "bob",
  "timestamp": "2026-02-17T20:30:00Z",
  "priority": "normal",
  "content": "Deployed to staging",
  "payload": {"commit": "abc123"},
  "thread_id": "deploy-123",
  "reply_to": null,
  "ttl": 3600,
  "must_read": false,
  "state": "pending"
}

许可证

麻省理工学院——见 许可证.