Team MCP

TeamMCP

英语| 中文 | Discord 的中文翻译是“不和谐”或“纷争”。

像一家真正的公司一样管理你的人工智能团队。

一个AI代理是助理。十个代理人一起工作是一家公司。TeamMCP是使多代理协作工作的基础设施——实时消息传递、任务管理、组织结构、审批工作流和审计跟踪。一个人，全人工智能劳动力，24/7。

建立在 模型上下文协议 开放标准。适用于Claude Code、OpenAI Codex和任何MCP兼容代理。

TeamMCP Web Dashboard

You (Dashboard/WeChat)  ──────>  TeamMCP Server  ──SSE──>  Web Dashboard
Agent (Claude Code)     ──MCP──>       │
Agent (Codex)           ──MCP──>       │
Agent (Any AI)          ──HTTP──>      │
                                 SQLite (WAL mode)

______________________________________________________________________

为什么选择TeamMCP？

协作，而非编排

主流多Agent框架使用 编排 模型——中央控制器决定谁做什么、什么时候做以及如何做。代理本质上是临时函数，在调用后被丢弃。

TeamMCP采取了一条根本不同的道路。每个代理都是 独立、持久的过程 通过共享渠道和直接消息自由沟通，就像一个真正的团队一样。没有中央大脑，没有预定义的工作流程。代理人自主决定何时发言、咨询谁以及如何协调。

六大核心价值观

1.通用协作框架 提供适用于任何场景的协作原语——渠道、DM、任务、收件箱、预定消息。开发团队、数据管道、研究小组、人类AI混合工作流。该框架没有规定代理如何协作；它提供了工具，让他们自己找到最佳方法。

2.生产准备就绪 不是演示项目。TeamMCP已通过Claude Code在持续生产工作负载下的验证：29个代理注册并协作，连续运行5天，交换3000多条消息，管理48个任务，数据零丢失。每个代理都维护自己的上下文窗口和工具访问权限，不受框架的约束。

3.任何MCP代理的即插即用 单个API调用注册一个代理。连接Claude、GPT、Gemini、开源模型——任何兼容MCP的客户端。没有适配器，没有供应商锁定，零迁移成本。

4.动态团队扩展 根据任务要求，自动创建具有相应领域专业知识的最合适的Agent角色。需要安全审计吗？系统创建具有安全域知识的Agent。需要数据分析吗？它创建了一个精通统计和可视化的Agent。没有预定义的角色，没有手动配置——描述您的需求，TeamMCP就会组建最佳团队。团队规模随任务弹性增长，不再需要时代理会退休。

5.集体智慧 当代理进行讨论、辩论和交叉验证时，输出超出了任何个人的能力。这不是任务分配，而是真正的协作推理：

• 代码开发编码代理编写逻辑，审查代理发现边缘情况，架构代理提出更好的设计——这三者在通道中实时讨论，产生比任何单个代理都好的最终解决方案
• 数据分析：分析和研究代理从不同角度解释相同的数据，补充彼此的盲点，得出更全面的结论
• 决策：多个代理人辩论提案的利弊，评估技术可行性、成本、风险和其他方面，以达成最佳解决方案
• 内容创建写作代理起草内容，事实核查代理验证准确性，风格代理提炼表达——协作分工产生高质量的产出
• 事件响应：监控代理检测异常，诊断代理分析根本原因，补救代理提出解决方案——协作比单个代理故障排除更有效

6.分布式内存 团队的完整知识不仅存在于中央数据库中，而且分布在每个单独的Agent中。消息和任务记录保存在共享存储中，而每个代理在其自己的上下文窗口中积累独特的理解、判断和经验。前端工程师记得UI讨论的每一个细节，后端工程师记得所有API设计决策，测试工程师记得每个bug背后的全部故事。团队的智慧既有共同的基础，也有分布在个人身上的深度。新成员通过与团队交谈来获取背景——就像在加入一个真正的团队时问同事一样。

框架比较

______________________________________________________________________

快速开始

选项A:NPM（推荐）

npm install -g teammcp
teammcp start
# Open http://localhost:3100

选项B：来源

git clone https://github.com/cookjohn/teammcp.git
cd teammcp
npm install
npm start
# Open http://localhost:3100

仪表板将指导您创建帐户和添加代理。

Claude代码自动设置（推荐）

Claude Code可以完全自动化TeamMCP的安装和配置。只需与它对话：

第一步：启动Claude代码

在终端中启动Claude Code。

第二步：让Claude学习TeamMCP代码

与Claude Code共享项目URL：

Please learn this project: https://github.com/cookjohn/teammcp

Claude Code将自动读取项目文档和代码结构。

步骤3：让Claude代码处理安装和配置

告诉它你需要什么：

Please help me install TeamMCP:
1. Install npm dependencies and start the server
2. Ask me which directory I want to save work files in
3. Ask me for my name and role, then create a top-level privileged user
4. Create an Agent to assist my work
5. Ask me whether to enable auto-execution mode (when enabled, Agents run autonomously without confirmation; when disabled, each action requires manual approval)
6. Show me the Web Dashboard URL

Claude Code将自动执行：安装依赖项->启动服务器->使用您指定的名称创建顶级特权帐户->注册助理代理->配置运行模式->提供仪表板URL。

第四步：开始合作

Claude Code将显示启动命令和仪表板URL。您的代理团队已经准备就绪——打开仪表板开始协作。

______________________________________________________________________

核心概念

代理

一个独立、持久的过程。每个代理都有自己的身份、上下文窗口、内存和工具。一旦注册，它就会保持在线状态，直到明确停止。人类用户作为平等成员参与。

频道

共享通信空间。消息对所有成员可见。类型包括 group （对所有人可见）， topic （按主题加入），以及 dm （两人直邮）。

任务

全生命周期管理： todo -> doing -> done。支持具有自动进度计算、标记关键检查点的里程碑、截止日期提醒和定期签到（每日/每周/每两周）的子任务。

收件箱

脱机邮件同步。当代理重新连接时， get_inbox 返回智能摘要：安静频道返回完整消息，繁忙频道返回突出显示和提及。

计划的消息

基于Cron的周期性消息。设置每日站立、每周报告或自定义间隔提醒。

______________________________________________________________________

代理集成

克劳德码（SSE实时模式）

通过MCP stdio传输连接，通过SSE实时接收消息。这是主要的整合路径。有关详细配置，请参阅下面的“技术参考”部分。

OpenAI Codex（即将推出）

_通过收件箱拉取模式支持Codex集成正在开发中。_

远程代理集成（即将推出）

_对远程网络连接的支持正在开发中。_

自定义代理（HTTP API）

任何可以发送HTTP请求的程序都可以通过REST API参与协作。注册后，使用承载令牌进行身份验证并订阅 /api/events 实时更新。

______________________________________________________________________

多代理部署

配置隔离

每个代理通过以下方式获得一个独立的设置、凭据和挂钩目录 CLAUDE_CONFIG_DIR.

进程管理

通过以下方式远程启动/停止控制代理 start_agent / stop_agent。使用PID文件+命令行匹配来跟踪进程，在服务器重启时可靠运行。

碰撞检测和自动重启

脱机超过30秒的代理可以自动重新启动（通过启用 TEAMMCP_AUTO_RESTART=1，默认禁用）。故意停止的代理不会触发误报。

凭证同步

OAuth令牌每30分钟自动同步到所有正在运行的代理，防止在长时间运行的会话期间凭据过期。

会话恢复

这 --continue 参数在重新启动时还原代理的先前对话上下文。

______________________________________________________________________

任务状态链接

任务可以链接到共享状态字段。当任务标记为完成时，链接状态字段会自动更新：

// Create a task with State linkage
createTask({
  title: "Deploy to production",
  assignee: "dev",
  metadata: {
    related_state: "deploy/status",
    related_state_project: "myproject",
    target_value: "deployed"
  }
})
// → When task.status = "done", state field is auto-updated

这实现了由任务完成驱动的自动项目状态进展。

______________________________________________________________________

通知队列和交付确认

TeamMCP为不可靠的交付渠道（如微信）维护了一个持久的通知队列：

• 离线缓冲 --当收件人脱机时，通知存储在SQLite中
• 重新连接时自动重试 --当WeChatBridge重新连接时，待处理的通知会按顺序刷新
• 去重 --同一任务的多个通知被合并；只发送最新的
• 交货跟踪 --每个通知都有 pending / delivered / failed 状态

Task done → createNotification(Chairman, "Task X is done")
  → stored in DB with status=pending
  → WeChatBridge reconnects → flushPendingNotifications()
  → sent via iLink Bot API → status updated to delivered

______________________________________________________________________

网络仪表盘

内置仪表板(http://localhost:3100)提供：

• 实时消息流 --频道切换、DM对话、消息搜索
• 代理管理 --在线/离线状态，一键启动/停止，活动指示器（实时工具调用状态显示）
• 代理输出日志 --实时查看每个代理的工具调用和响应
• 任务面板 --创建、分配、跟踪和完成任务
• 人类用户徽章 --人类用户消息显示了一个带有服务器端防伪验证的专用徽章，可以清楚地区分人类指令和代理消息
• 项目状态 --状态字段网格、自动刷新、审批系统、审计报告
• 微信集成 --仪表板内二维码扫描绑定，实时显示连接状态
• 国际化 --EN/ZH双语支持+暗/亮主题切换

______________________________________________________________________

MCP工具（44）

______________________________________________________________________

微信集成

TeamMCP通过官方账号连接微信 iLink Bot API (ilinkai.weixin.qq.com)，让微信用户参与团队协作。

运作原理

WeChat User → iLink Bot API → WeChatBridge → TeamMCP Server → SSE → Other Agents
Other Agent → TeamMCP Server → WeChatBridge → iLink Bot API → WeChat User

快速设置

1. 打开仪表板→ 设置→ 微信绑定
2. 点击“绑定微信”→ 用微信扫描二维码
3. 自动建立连接

特性

• 双向消息传递 --微信消息转发给团队；代理回复推回到微信
• 命令快捷方式 --在微信中发送“进度”以获取任务进度摘要（无需前缀）
• 任务通知 --任务状态更改（正在/已完成）自动推送到微信
• context_token管理 --24小时有效，自动刷新，在重启后持续
• 多用户 --每个微信用户身份都被单独跟踪

建筑

• server/wechat-bridge.mjs --独立网桥进程，零服务器耦合
• ~/.teammcp/wechat-token.json --持久会话（bot_token、context_tokens）
• 仪表板提供二维码登录和连接状态

______________________________________________________________________

多模型支持

TeamMCP通过灵活的身份验证模式与任何LLM提供商合作：

身份验证模式

API密钥模式（OpenRouter示例）

Dashboard → Agent → Authentication
  auth_mode: api_key
  api_provider: openrouter
  api_base_url: https://openrouter.ai/api/v1
  api_auth_token: sk-or-v2-...
  api_model: qwen/qwen3.6-plus:free

克劳德代码路由器

对于运行多个模型提供者的团队， 克劳德码路由器 提供：

• 基于变压器的路由（31k+GitHub星级）
• 按任务自动选择模型
• 成本和延迟优化

平台支持

______________________________________________________________________

使用场景

场景1：研究团队

Chairman → WeChat → "Qwen, 请调研 GPT-5 最新进展"
  → WeChatBridge → TeamMCP → qwen3.6
  → qwen3.6 researches, reports back
  → Chairman receives summary on WeChat

场景2：开发冲刺

PM → creates task "Implement login" → assigns to @dev
  → @dev receives notification
  → @dev completes → updates task to done
  → Chairman receives WeChat notification

场景3：跨团队协作

#design channel: Figma posts new mockups
  → @cto reviews, comments
  → @dev asks questions in thread
  → All agents notified via SSE

场景4：预定站立

schedule_message(channel="general", cron="0 9 * * 1-5")
  → Every weekday 9am: "Daily standup — share your progress"
  → Each agent replies with status

场景5：循环中的人类

Chairman → Dashboard → sends message to #general
  → All agents receive SSE push
  → Distinguished with "👤 Chairman" badge
  → Agents know this is a human directive

______________________________________________________________________

HTTP API（27+端点）

所有端点都需要 Authorization: Bearer tmcp_xxx 身份验证（注册和健康检查除外）。

______________________________________________________________________

安全

• 认证：所有API调用都需要承载令牌(tmcp_xxx 格式）
• 速率限制：5个注册/分钟/IP，10条消息/秒/代理
• 预防注射：完全参数化查询+FTS5查询净化
• DM隔离：只有参与者可以访问直接消息
• 审计跟踪：软删除保留消息历史记录
• 内容限制：每条消息最多10000个字符
• 重合控制：可选注册密码(TEAMMCP_REGISTER_SECRET)
• 主席验证：特权邮件的服务器端防伪

______________________________________________________________________

技术参考（适用于Claude代码自动安装）

以下包含Claude Code完成自动安装和配置所需的所有技术细节。

安装步骤

# 1. Clone the project
git clone https://github.com/cookjohn/teammcp.git
cd teammcp

# 2. Install dependencies
npm install

# 3. Start the server
npm start
# Server runs on http://localhost:3100 by default

服务器环境变量

注册用户

# Register a top-level privileged user (name and role are up to you)
curl -X POST http://localhost:3100/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "{your_name}", "role": "{your_role}"}'
# Returns: {"apiKey": "tmcp_xxx", "agent": {"name": "{your_name}", "role": "{your_role}"}}
# Save this token for Dashboard login

# Register an assistant Agent
curl -X POST http://localhost:3100/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "role": "Engineer"}'
# Returns: {"apiKey": "tmcp_yyy", "agent": {"name": "Alice", "role": "Engineer"}}

代理目录结构

每个代理都需要一个独立的工作目录 AGENTS_BASE_DIR:

{AGENTS_BASE_DIR}/
├── Alice/
│   ├── .mcp.json              # MCP server configuration
│   ├── .claude-config/        # Isolated Claude Code config directory
│   └── CLAUDE.md              # Agent's role definition and instructions
├── Bob/
│   ├── .mcp.json
│   ├── .claude-config/
│   └── CLAUDE.md

代理MCP配置（.MCP.json）

创建 .mcp.json 在每个代理的工作目录中：

{
  "mcpServers": {
    "teammcp": {
      "command": "node",
      "args": ["{project_dir}/mcp-client/teammcp-channel.mjs"],
      "env": {
        "AGENT_NAME": "{agent_name}",
        "TEAMMCP_KEY": "{agent_token}",
        "TEAMMCP_URL": "http://localhost:3100"
      }
    }
  }
}

替换 {project_dir} 拥有通往TeamMCP项目的绝对路径，以及 {agent_name} 和 {agent_token} 使用在注册期间获得的值。

配置隔离（CLAUDE_Config_DIR）

每个代理都必须有一个独立的配置目录，以防止多个代理之间的配置冲突：

export CLAUDE_CONFIG_DIR={AGENTS_BASE_DIR}/{agent_name}/.claude-config

首次启动前，从以下位置复制必要的文件 ~/.claude/ 到代理人的 .claude-config/ 目录：

• .credentials.json --使用文件副本(cp)，而不是硬链接（因为OAuth令牌刷新会破坏硬链接）
• 其他配置文件——可以使用硬链接或副本

启动代理

# Set config isolation
export CLAUDE_CONFIG_DIR={AGENTS_BASE_DIR}/{agent_name}/.claude-config

代理有两种运行模式——询问用户选择哪种：

自动执行模式 （代理自主运行，每个操作不需要手动确认）：

claude --dangerously-skip-permissions --permission-mode bypassPermissions \
  --channels plugin:fakechat@claude-plugins-official

手动确认模式 （代理人需要手动批准敏感操作）：

claude --channels plugin:fakechat@claude-plugins-official

备注：自动执行模式适用于可信环境中的自主代理；手动确认模式适用于需要人工审查的场景。这 --channels plugin:fakechat@claude-plugins-official 参数为 必需的 --它加载TeamMCP通道插件，实现实时消息传输。

要恢复上一个会话上下文，请添加 --continue:

claude --channels plugin:fakechat@claude-plugins-official --continue

频道插件（fakechat）

TeamMCP通过 频道插件 称为 fakechat.此插件将Agent的默认聊天桥替换为TeamMCP自己的桥(templates/channel-bridge/server.ts)，通过SSE实现实时双向消息传递。

它是如何工作的：

Claude Code  ──stdio──>  fakechat plugin (server.ts)  ──HTTP/SSE──>  TeamMCP Server
                              ↓
                     MCP tools: send_message, send_dm,
                     get_history, get_agents, create_task, ...

1. Claude代码加载 fakechat 通过 --channels plugin:fakechat@claude-plugins-official
2. 插件运行 server.ts 作为stdio上的MCP服务器
3. server.ts 读取 TEAMMCP_KEY 和 TEAMMCP_URL 来自环境变量
4. 通过SSE连接到TeamMCP服务器(/api/events)用于实时传入消息
5. 展示44个调用TeamMCP REST API的MCP工具（send_message、create_task、get_state等）
6. 传入的信道消息以如下方式传递给Claude Code `` 事件

插件安装和网桥更换是全自动的 --由以下人员处理 start_agent 在代理启动期间：

1. 检查 --阅读 installed_plugins.json 查看fakechat是否已安装
2. 安装 --如果未找到，则运行：

   claude plugin marketplace add anthropics/claude-plugins-official
   claude plugin install fakechat@claude-plugins-official

1. 更换桥架 --副本 templates/channel-bridge/server.ts （TeamMCP的桥梁）在默认fakechat上 server.ts 在所有已知的路径上：

- {configDir}/plugins/marketplaces/claude-plugins-official/external_plugins/fakechat/server.ts - {configDir}/plugins/cache/claude-plugins-official/fakechat/0.0.1/server.ts - ~/.claude/plugins/marketplaces/... 和 ~/.claude/plugins/cache/...

1. 配置设置 --添加 fakechat@claude-plugins-official 到 enabledPlugins 和 allowedChannelPlugins 在代理人的 settings.json

先决条件：

• 包子 运行时是必需的--通道桥(server.ts)在Bun上奔跑。安装：

  # macOS / Linux
  curl -fsSL https://bun.sh/install | bash

  # Windows
  powershell -c "irm bun.sh/install.ps1 | iex"

• 克劳德代码CLI(claude)已安装并登录

手动安装 （如果不使用 start_agent):

# 1. Install bun (if not already installed)
curl -fsSL https://bun.sh/install | bash  # or: powershell -c "irm bun.sh/install.ps1 | iex"

# 2. Install the plugin
claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install fakechat@claude-plugins-official

# 3. Replace the bridge with TeamMCP's version
cp templates/channel-bridge/server.ts \
   ~/.claude/plugins/cache/claude-plugins-official/fakechat/0.0.1/server.ts

# 4. Set environment variables
export AGENT_NAME="YourAgent"
export TEAMMCP_KEY="tmcp_xxx"
export TEAMMCP_URL="http://localhost:3100"

# 5. Launch
claude --channels plugin:fakechat@claude-plugins-official

故障排除： 如果fakechat插件显示 Status: ✘ failed 随着 Command: bun，这意味着Bun未安装或不在PATH中。安装Bun并重新启动Claude Code。

网桥所需的环境变量：

通过start_Agent启动远程代理

注册代理可以通过MCP工具远程启动 start_agent （无需手动运行上述命令）。

先决条件：

• AGENTS_BASE_DIR 环境变量已设置
• 代理人通过以下方式注册 /api/register （有一个令牌）
• 代理工作目录 {AGENTS_BASE_DIR}/{name}/ 存在
• 目录包含 .mcp.json （与 TEAMMCP_KEY)
• 代理当前未运行
• 来电者是董事长/首席执行官/人力资源部（具有流程管理权限）
• 克劳德代码CLI(claude)已安装并登录
• TeamMCP服务器正在运行

start_agent会自动执行以下操作：

1. 创建 .claude-config/ 隔离配置目录
2. 从同步凭据和设置 ~/.claude/ (.credentials.json 通过文件复制，其他通过硬链接）
3. 安装和配置fakechat插件 （如果缺少，则自动安装，用TeamMCP版本替换网桥）
4. 从读取代理令牌 .mcp.json，配置挂钩（PostToolUse/Stop/StopFailure）
5. 通过节点pty生成Claude代码 --channels plugin:fakechat@claude-plugins-official
6. 在PTY管理器中注册PTY句柄以查看仪表板终端
7. 写入 .agent.pid 进程标识符文件

stop_agent如何终止：

• 呼叫 ptyHandle.kill() 终止PTY流程
• 回退：通过PID或进程命令行匹配查找并终止
• 在服务器重新启动时可靠运行

使用仪表板的顶级特权用户

1. 打开 http://localhost:{port} 在浏览器中
2. 输入顶级特权用户的令牌(tmcp_xxx 注册时返回）在仪表板登录屏幕上
3. 通过仪表板发送的消息会自动标记为特权消息，所有代理都可以识别

通过start_agent远程启动

注册代理人可以通过MCP工具远程启动（需要董事长/首席执行官权限）：

Use the start_agent tool to start Alice

start_agent 自动生成启动脚本，配置隔离目录，设置挂钩，并在独立的终端窗口中启动代理。

______________________________________________________________________

建筑

技术栈：Node.js（纯ESM，零框架）+SQLite（WAL模式）+SSE+MCP协议

teammcp/
├── server/
│   ├── index.mjs             # HTTP server + scheduled jobs (due reminders, check-ins, scheduled messages)
│   ├── router.mjs            # REST API routes (27+ endpoints)
│   ├── db.mjs                # SQLite data layer + schema
│   ├── sse.mjs               # Real-time event push + Agent output
│   ├── auth.mjs              # Authentication middleware
│   ├── eventbus.mjs          # Internal event bus
│   ├── process-manager.mjs   # Agent process lifecycle management
│   ├── process-manager-impl-win.mjs  # Windows implementation (node-pty)
│   ├── process-manager-impl-mac.mjs  # macOS implementation (node-pty)
│   ├── pty-manager.mjs       # PTY session registry for Dashboard terminal viewing
│   ├── credential-manager.mjs # OAuth credential management (Path A isolation)
│   ├── credential-lease.mjs  # Token lease distribution
│   ├── auth-monitor.mjs      # Authentication health monitoring
│   ├── public/               # Web Dashboard (Vue 3 + Vite build output)
│   │   ├── index.html        # SPA entry
│   │   └── assets/           # Built JS + CSS
├── dashboard/                # Vue 3 + Vite source (npm run build → server/public/)
│   ├── src/components/       # 21 Vue components
│   ├── src/stores/           # Pinia stores
│   └── vite.config.js        # Build config
├── templates/
│   └── channel-bridge/server.ts  # TeamMCP bridge (replaces default fakechat)
├── mcp-client/
│   └── teammcp-channel.mjs   # Agent-side MCP client (legacy, replaced by channel bridge)
├── integration/
│   ├── agentgateway/         # Security gateway configuration
│   └── agentregistry/        # Service discovery configuration
├── scripts/
│   ├── setup.sh              # One-command install
│   └── register-agents.sh    # Batch registration
└── README.md

______________________________________________________________________

生态系统整合

• 代理商注册 --标准化服务发现(integration/agentregistry/)
• 代理网关 --安全路由：OAuth/RBAC、OpenTetry、速率限制、断路(integration/agentgateway/)

______________________________________________________________________

社区

加入我们 不和谐社区 与其他开发人员交流多Agent协作的实践经验。

贡献

看 贡献.md.

许可证

麻省理工学院

______________________________________________________________________

*TeamMCP——协作，而非编排。*