<div align="center">

# acpx-teams

为任意 MCP 客户端实现 Claude Code [智能体团队](https://code.claude.com/docs/en/agent-teams) 协议的 MCP 服务器。

</div>

Claude Code 内置了智能体团队功能（共享任务列表、智能体间消息传递、基于 tmux 的进程管理），但该协议是内部实现，与其自身工具链紧密耦合。本 MCP 服务器将该协议重新实现为独立的 [MCP](https://modelcontextprotocol.io/) 服务器，使其可用于任何 MCP 客户端：[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai) 或任何支持 MCP 的工具。欢迎提交 PR。

## 安装

> **请固定到某个发布标签**（如 `@v0.2.0`），而非 `main`。各版本之间存在破坏性变更。

### 通过 PyPI 安装（推荐）

Claude Code（`.mcp.json`）：

```json
{
  "mcpServers": {
    "acpx-teams": {
      "command": "uvx",
      "args": ["acpx-teams@0.2.0"]
    }
  }
}
```

OpenCode（`~/.config/opencode/opencode.json`）：

```json
{
  "mcp": {
    "acpx-teams": {
      "type": "local",
      "command": ["uvx", "acpx-teams@0.2.0"],
      "enabled": true
    }
  }
}
```

### 通过 Git 安装

Claude Code（`.mcp.json`）：

```json
{
  "mcpServers": {
    "acpx-teams": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/open-deep-crew/acpx-teams-mcp@v0.2.0", "acpx-teams"]
    }
  }
}
```

OpenCode（`~/.config/opencode/opencode.json`）：

```json
{
  "mcp": {
    "acpx-teams": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/open-deep-crew/acpx-teams-mcp@v0.2.0", "acpx-teams"],
      "enabled": true
    }
  }
}
```

## 环境要求

- Python 3.12+
- [tmux](https://github.com/tmux/tmux)
- PATH 中至少有一个编程智能体：[Claude Code](https://docs.anthropic.com/en/docs/claude-code)（`claude`）或 [OpenCode](https://opencode.ai)（`opencode`）
- OpenCode 队友需要设置 `OPENCODE_SERVER_URL` 并在该实例中连接 `acpx-teams` MCP

## 配置

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `CLAUDE_TEAMS_BACKENDS` | 逗号分隔的启用后端列表（`claude`、`opencode`） | 根据连接客户端自动检测 |
| `OPENCODE_SERVER_URL` | OpenCode HTTP API 地址（OpenCode 队友必填） | *(未设置)* |
| `USE_TMUX_WINDOWS` | 在 tmux 窗口而非面板中启动队友 | *(未设置)* |

不设置 `CLAUDE_TEAMS_BACKENDS` 时，服务器会自动检测连接的客户端并仅启用对应后端。显式设置可同时启用多个后端：

```json
{
  "mcpServers": {
    "acpx-teams": {
      "command": "uvx",
      "args": ["acpx-teams@0.2.0"],
      "env": {
        "CLAUDE_TEAMS_BACKENDS": "claude,opencode",
        "OPENCODE_SERVER_URL": "http://localhost:4096"
      }
    }
  }
}
```

## 工具列表

| 工具 | 说明 |
|------|------|
| `team_create` | 创建新的智能体团队（每个会话一个） |
| `team_delete` | 删除团队及所有数据（有队友活跃时失败） |
| `spawn_teammate` | 在 tmux 中启动一个队友 |
| `send_message` | 发送私信、广播（仅 lead）、关闭/计划响应 |
| `read_inbox` | 读取智能体收件箱中的消息 |
| `read_config` | 读取团队配置和成员列表 |
| `task_create` | 创建任务（自动递增 ID） |
| `task_update` | 更新任务状态、负责人、依赖关系或元数据 |
| `task_list` | 列出所有任务 |
| `task_get` | 获取任务完整详情 |
| `force_kill_teammate` | 强制终止队友的 tmux 面板/窗口并清理 |
| `process_shutdown_approved` | 优雅关闭后移除队友 |
| `team_status` | 检查所有队友的实时会话状态 |
| `check_teammate` | 检查单个队友的状态和未读消息 |

## 架构

- **进程管理**：队友默认在 tmux 面板中启动（设置 `USE_TMUX_WINDOWS` 可改为窗口模式），每个队友有唯一的智能体 ID 和颜色标识。
- **消息传递**：JSON 收件箱位于 `~/.claude/teams/<team>/inboxes/`。Lead 可向任何人发消息；队友只能向 lead 发消息。
- **任务管理**：JSON 文件位于 `~/.claude/tasks/<team>/`，支持状态跟踪、所有权和依赖管理。
- **并发控制**：通过 `tempfile` + `os.replace` 实现原子写入，通过 `filelock` 实现跨平台文件锁。

```
~/.claude/
├── teams/<team>/
│   ├── config.json
│   └── inboxes/
│       ├── team-lead.json
│       ├── worker-1.json
│       └── .lock
└── tasks/<team>/
    ├── 1.json
    ├── 2.json
    └── .lock
```

## 许可证

[MIT](./LICENSE)
