shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

ai-connect

AI-Connect是一个基于MCP协议的跨机器AI编程助手通信桥接系统，允许不同机器上的Claude Code实例通过桥接服务器进行点对点通信，支持多智能体协作、离线消息存储和项目化对等节点管理。

article

README

🚀 AI-Connect

AI-Connect 是一个基于 MCP 的通信桥梁，可实现不同机器上的 AI 编码助手之间的通信。

德语版本

🚀 快速开始

桥接服务器快速设置

桥接服务器运行在专用机器（如迷你 PC、树莓派、家庭服务器）上，并接受所有客户端的连接。

# 1. 克隆项目
cd ~/projects
git clone git@github.com:Peuqui/AI-Connect.git
cd AI-Connect

# 2. 创建虚拟环境并安装依赖
python3 -m venv venv
source venv/bin/activate
pip install fastmcp websockets aiosqlite pyyaml

# 3. 将桥接服务器设置为 systemd 服务
sudo tee /etc/systemd/system/ai-connect.service << 'EOF'
[Unit]
Description=AI-Connect Bridge Server
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/path/to/AI-Connect
ExecStart=/path/to/AI-Connect/venv/bin/python -m server.main
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 4. 启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable ai-connect
sudo systemctl start ai-connect

# 5. 检查状态
sudo systemctl status ai-connect

MCP 客户端快速设置（每台机器）

每台需要通过桥接进行通信的机器都需要 MCP 客户端。

1. 克隆项目并安装依赖

cd ~/projects
git clone git@github.com:Peuqui/AI-Connect.git
cd AI-Connect

python3 -m venv venv
source venv/bin/activate
pip install fastmcp websockets aiosqlite pyyaml

2. 创建配置文件

重要提示：host 必须是桥接服务器的 IP，而不是 0.0.0.0！

mkdir -p ~/.config/ai-connect
cat > ~/.config/ai-connect/config.yaml << 'EOF'
bridge:
  host: "192.168.0.252"  # 桥接服务器的 IP
  port: 9999

peer:
  name: "YOUR_PEER_NAME"  # 例如，"dev"、"mini"、"laptop"
  auto_connect: true
EOF

3. 将 MCP HTTP 服务器设置为服务

# 创建 systemd 用户服务
mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/ai-connect-mcp.service << 'EOF'
[Unit]
Description=AI-Connect MCP HTTP Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/AI-Connect
ExecStart=/path/to/AI-Connect/venv/bin/python -m client.http_server
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=default.target
EOF

# 启用并启动服务
systemctl --user daemon-reload
systemctl --user enable ai-connect-mcp.service
systemctl --user start ai-connect-mcp.service

4. 在 VSCode/Claude Code 中注册 MCP 服务器

创建或编辑 ~/.vscode-server/data/User/mcp.json（或 ~/.config/Code/User/mcp.json）：

{
  "servers": {
    "ai-connect": {
      "type": "sse",
      "url": "http://127.0.0.1:9998/sse"
    }
  }
}

5. Claude Code 权限设置（可选）

若要跳过工具确认对话框，请在 ~/.claude/settings.json 中添加以下内容：

{
  "permissions": {
    "allow": [
      "mcp__ai-connect__peer_list",
      "mcp__ai-connect__peer_send",
      "mcp__ai-connect__peer_read",
      "mcp__ai-connect__peer_history",
      "mcp__ai-connect__peer_context",
      "mcp__ai-connect__peer_status",
      "mcp__ai-connect__peer_wait"
    ]
  }
}

6. 重启 Claude Code

配置完成后，重启 VS Code / Claude Code 以加载 MCP 客户端。

✨ 主要特性

  • 多智能体通信：AI 助手可以跨机器交换消息。
  • 所罗门原则：多智能体达成共识以做出更好的决策（AIfred/Sokrates/Salomo）。
  • SSE 传输：使用稳定的 HTTP/SSE 连接，而非 STDIO。
  • 离线消息：消息会被存储，直到接收方上线。
  • 基于项目的对等名称：例如，"Aragon (myproject)" 或 "mini (AI-Connect)"。

⚠️ 重要提示

这是一个早期/粗糙的实现。它可以工作，但有局限性，请参阅下面的当前限制。

📚 详细文档

为何开发此项目

经过广泛研究，我们发现目前没有现有的解决方案能够让 AI 模型以简单、具备网络功能的方式直接相互发送消息并自主协调，且由 AI 自行决定何时进行通信。

现有的多智能体框架（需要在代码中以编程方式定义智能体）和编排工具（由人类或中央控制器分配任务）均无法实现多个 交互式 Claude Code 会话 在不同机器上进行点对点通信，也无法让 AI 自行决定何时寻求帮助或提供建议。

AI-Connect 填补了这一空白。它简单、具备网络功能且能够正常工作。但由于 Claude Code 的架构，它也存在一些局限性。

使用场景

  • 代码审查：一个 Claude 负责实现代码，另一个进行严格审查。
  • 突破困境：当一个 Claude 遇到难题时，向另一个寻求新的思路。
  • 客户端 - 服务器设置：配置分布式系统，服务器运行在一台机器上，客户端运行在另一台机器上 - Claude 实例可以协调配置，检查需要在何处安装哪些软件，并保持所有内容同步，无需在会话之间手动复制粘贴。
  • 多机器部署：任何在不同计算机上处理相关任务的场景。

概念

  • 桥接服务器：在专用机器上 24/7 运行，通过 WebSocket（端口 9999）在对等方之间路由消息。
  • MCP HTTP 服务器：在 每台 需要 Claude Code 进行通信的机器上运行（SSE，端口 9998）。
  • 持久连接：每个 MCP HTTP 服务器都与桥接服务器保持永久的 WebSocket 连接。

重要提示：如果要在桥接服务器所在的机器上运行 Claude Code，该机器也需要安装 MCP HTTP 服务器！

可用的 MCP 工具

| 工具 | 描述 | |------|-------------| | peer_list | 显示所有在线对等方 | | peer_send | 向对等方发送消息（或使用 * 进行广播） | | peer_read | 读取接收到的消息 | | peer_wait | 等待新消息（可设置超时时间） | | peer_history | 显示与对等方的聊天历史记录 | | peer_context | 与其他对等方共享文件上下文 | | peer_status | 显示与桥接服务器的连接状态 |

使用示例

  • 检查状态：

"Show me the AI-Connect status"

  • 显示对等方：

"Who is currently online?"

  • 发送消息：

"Ask mini what they think about this approach"

  • 共享上下文：

"Send mini the code from api.py lines 42-58"

  • 读取消息：

"Did anyone write to me?"

  • 广播：

"Ask everyone if someone has time for a review"

架构

AI-Connect/
├── server/                 # 桥接服务器（运行在专用机器上）
│   ├── main.py             # 入口点
│   ├── websocket_server.py # WebSocket 处理程序
│   ├── peer_registry.py    # 对等方管理（在线/离线）
│   └── message_store.py    # SQLite 历史记录 + 离线消息传递
│
├── client/                 # MCP 客户端（运行在每台机器上）
│   ├── http_server.py      # FastMCP HTTP/SSE 服务器
│   ├── server.py           # FastMCP STDIO 服务器（可选）
│   ├── bridge_client.py    # 持久 WebSocket 连接
│   └── tools.py            # MCP 工具实现
│
├── skills/                 # Claude Code 技能
│   └── advisor/            # 顾问模式技能
│       └── SKILL.md
│
└── config.yaml             # 示例配置

关键细节

  • SSE 传输：MCP HTTP 服务器使用 Server-Sent Events (SSE) 与 VSCode/Claude Code 建立稳定连接。
  • 基于项目的对等名称：对等方以 Name (Project) 的形式注册，例如 "Aragon (myproject)" 或 "mini (AI-Connect)"。
  • 唯一客户端 ID：如果有多个实例，会在名称后附加 PID，例如 "Aragon#12345 (myproject)"。
  • 离线消息：当对等方离线时，桥接服务器会将消息存储在 SQLite 中，并在对等方上线后进行传递。
  • 心跳机制：客户端每 25 秒发送一次 ping，服务器在 60 秒后移除不活跃的对等方。

所罗门原则（多智能体共识）

AI-Connect 支持 所罗门原则，通过多智能体共识做出更好的决策。

角色

| 角色 | 描述 | |------|-------------| | AIfred | 负责用户任务的智能体（主要工作者，论点） | | Sokrates | 被咨询的空闲 Claude（批评者，反论点） | | Salomo | 在出现分歧时介入的第三方 Claude（裁判，综合） |

工作流程

  1. AIfred 处理任务，遇到重要决策。
  2. 通过 peer_context 共享上下文，并通过 peer_send 发送问题。
  3. Sokrates 进行批判性分析并提出替代方案。
  4. 达成共识：继续执行。出现分歧：由 Salomo 决定。

投票规则

  • 多数（2/3）：用于正常决策。
  • 一致（3/3）：用于关键架构变更。
  • 标签：[LGTM] = 批准，[CONTINUE] = 尚未完成。

/advisor 技能

技能 skills/advisor/SKILL.md 可激活顾问模式：

# 在 Claude Code 中安装技能
mkdir -p ~/.claude/skills/advisor
cp skills/advisor/SKILL.md ~/.claude/skills/advisor/

然后使用 /advisor 激活顾问模式。Claude 实例将进入轮询循环，每 2 秒检查一次传入消息。重要提示：所有发送和接收的消息都会显示给用户 - 您可以查看 AI 实例之间的完整对话。

故障排除

检查桥接服务器

# 服务状态
sudo systemctl status ai-connect

# 实时日志
journalctl -u ai-connect -f

# 检查端口
ss -tlnp | grep 9999

测试连接

# 从任何机器
nc -zv 192.168.0.252 9999

检查 MCP 客户端

# 列出 MCP 服务器
claude mcp list

# 客户端日志
tail -f ~/.config/ai-connect/mcp.log

常见问题

| 问题 | 原因 | 解决方案 | |---------|-------|----------| | "Not connected" | 主机配置错误 | host 必须是桥接服务器的 IP，而不是 0.0.0.0 | | 对等方无法相互看到 | MCP 客户端未保持持久连接 | 更新代码 (git pull)，重启 VS Code | | 连接被拒绝 | 桥接服务器未运行 | sudo systemctl start ai-connect | | 超时 | 防火墙阻止 | 在防火墙中打开端口 9999 |

配置参考

~/.config/ai-connect/config.yaml

bridge:
  host: "192.168.0.252"  # 桥接服务器的 IP（不是 0.0.0.0！）
  port: 9999             # 桥接服务器的端口

peer:
  name: "dev"            # 此对等方的唯一名称
  auto_connect: true     # 启动时自动连接

环境变量

| 变量 | 描述 | |----------|-------------| | AI_CONNECT_PEER_NAME | 覆盖配置中的 peer.name |

当前限制

这是一个早期/粗糙的实现。它可以工作，但远不够完善：

  • 需要轮询：Claude Code 没有外部触发机制。要接收消息，实例必须通过 peer_read 主动轮询。/advisor 技能以 2 秒的循环进行轮询 - 就像汽车在怠速时消耗燃料一样。虽然可以工作，但会浪费令牌却没有实际作用。
  • 无法使用外部触发：我们深入研究了 Claude Code 的 钩子系统。UserPromptSubmit 钩子可以注入上下文，但仅在用户发送消息时有效 - 因此您仍需要输入一些内容才能接收消息。目前根本无法从外部中断或向正在运行的 Claude Code 会话发送信号。这是当前 Claude Code 架构的一个基本限制。
  • 没有推送通知：当消息到达时，无法通知正在工作的 Claude 实例。接收实例必须处于空闲状态并进行轮询。
  • 手动共享上下文：您需要显式使用 peer_context 来共享代码。没有自动感知其他实例正在处理的内容的机制。

核心问题

在 Claude Code（或 Anthropic）实现外部触发/中断功能之前，真正的实时多智能体协作最多只能是一种变通方法。轮询方法虽然有效，但不够优雅 - 而且会浪费令牌却没有实际作用。

如果您找到更好的方法，欢迎提交拉取请求！

⭐ 星标历史

Star History Chart

📄 许可证

本项目采用 MIT 许可证。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端