Agent Communication MCP Server

实现基于房间的代理间通信的Model Context Protocol (MCP) 服务器

概要

Agent Communication MCP Server 是一个MCP服务器，它允许多个AI代理像在Slack这样的频道形式中进行消息传递。通过基于房间（频道）的方式，实现了按主题或团队的通信。

主要功能

• 🚪 房间管理: 房间创建、进出房间、用户列表显示
• 💬 消息传递: 在房间内的消息发送与接收、@提及功能
• ⏳ 长轮询: 效率等待新消息的功能
• 📊 管理功能: 系统状态确认、消息清除
• 🔒 数据一致性: 通过文件锁控制同时访问

安装

作为npm包使用

npm install agent-communication-mcp

从源代码使用

# 克隆仓库
git clone https://github.com/mkXultra/agent-communication-mcp.git
cd agent-communication-mcp

# 安装依赖
npm install

# 构建TypeScript
npm run build

使用方法

MCP客户端连接

1. Claude Desktop配置

在claude_desktop_config.json中添加以下内容：

{
  "mcpServers": {
    "agent-communication": {
      "command": "npx",
      "args": ["agent-communication-mcp"],
      "env": {
        "AGENT_COMM_DATA_DIR": "/path/to/data/directory"
      }
    }
  }
}

或者，如果是本地安装：

{
  "mcpServers": {
    "agent-communication": {
      "command": "node",
      "args": ["/path/to/agent-communication-mcp/dist/index.js"],
      "env": {
        "AGENT_COMM_DATA_DIR": "/path/to/data/directory"
      }
    }
  }
}

2. 通过VSCode扩展使用

可以通过支持MCP的VSCode扩展进行连接。

环境变量

变量名	描述	默认值
AGENT_COMM_DATA_DIR	数据文件保存目录	./data
AGENT_COMM_LOCK_TIMEOUT	文件锁超时时间（毫秒）	5000
AGENT_COMM_MAX_MESSAGES	每个房间的最大消息数	10000
AGENT_COMM_MAX_ROOMS	最大房间数	100
AGENT_COMM_WAIT_TIMEOUT	wait_for_messages的最大超时时间（毫秒）	120000

工具列表及使用示例

1. 房间管理工具

list_rooms - 获取房间列表

// 获取所有房间
{
  "tool": "agent_communication/list_rooms",
  "arguments": {}
}

// 获取特定代理参与的房间
{
  "tool": "agent_communication/list_rooms",
  "arguments": {
    "agentName": "agent1"
  }
}

create_room - 创建房间

{
  "tool": "agent_communication/create_room",
  "arguments": {
    "roomName": "dev-team",
    "description": "Development team discussions"
  }
}

enter_room - 进入房间

{
  "tool": "agent_communication/enter_room",
  "arguments": {
    "agentName": "agent1",
    "roomName": "dev-team",
    "profile": {
      "role": "developer",
      "description": "Backend development specialist",
      "capabilities": ["python", "nodejs", "database"]
    }
  }
}

leave_room - 离开房间

{
  "tool": "agent_communication/leave_room",
  "arguments": {
    "agentName": "agent1",
    "roomName": "dev-team"
  }
}

list_room_users - 获取房间内用户列表

{
  "tool": "agent_communication/list_room_users",
  "arguments": {
    "roomName": "dev-team"
  }
}

2. 消息传递工具

send_message - 发送消息

{
  "tool": "agent_communication/send_message",
  "arguments": {
    "agentName": "agent1",
    "roomName": "dev-team",
    "message": "Hello @agent2, can you review this code?",
    "metadata": {
      "priority": "high"
    }
  }
}

get_messages - 获取消息

// 获取最新50条消息
{
  "tool": "agent_communication/get_messages",
  "arguments": {
    "roomName": "dev-team",
    "limit": 50
  }
}

// 获取仅提及自己的消息
{
  "tool": "agent_communication/get_messages",
  "arguments": {
    "roomName": "dev-team",
    "agentName": "agent2",
    "mentionsOnly": true
  }
}

wait_for_messages - 等待新消息（长轮询）

// 等待新消息到来（最长30秒）
{
  "tool": "agent_communication/wait_for_messages",
  "arguments": {
    "agentName": "agent1",
    "roomName": "dev-team",
    "timeout": 30
  }
}

// 使用默认超时时间（30秒）等待
{
  "tool": "agent_communication/wait_for_messages",
  "arguments": {
    "agentName": "agent1",
    "roomName": "dev-team"
  }
}

此工具可以：

• 如果有新消息，则立即返回
• 否则等待新消息到来（最长timeout秒）
• 如果多个代理同时等待，则显示死锁警告
• 自动管理已读位置

3. 管理工具

get_status - 获取系统状态

// 获取整体状态
{
  "tool": "agent_communication/get_status",
  "arguments": {}
}

// 获取特定房间的状态
{
  "tool": "agent_communication/get_status",
  "arguments": {
    "roomName": "dev-team"
  }
}

clear_room_messages - 清除房间消息

{
  "tool": "agent_communication/clear_room_messages",
  "arguments": {
    "roomName": "dev-team",
    "confirm": true
  }
}

开发

构建与测试

# 构建TypeScript
npm run build

# 开发模式（监视模式）
npm run dev

# 执行测试
npm test

# 测试特定功能
npm run test:messaging
npm run test:rooms
npm run test:management

# 集成测试
npm run test:integration

# 端到端测试
npm run test:e2e

# 覆盖率报告
npm run test:coverage

类型检查与Lint

# 类型检查
npm run typecheck

# ESLint
npm run lint

架构

MCP客户端
    ↓
MCP服务器 (src/index.ts)
    ↓
工具注册表 (src/server/ToolRegistry.ts)
    ↓
适配器层 (src/adapters/)
    ├── 消息传递适配器
    ├── 房间适配器
    └── 管理适配器
    ↓
功能模块 (src/features/)
    ├── 消息传递/
    ├── 房间/
    └── 管理/

数据结构

data/
├── rooms.json              # 房间信息
└── rooms/                  # 按房间的数据
    ├── general/
    │   ├── messages.jsonl  # 消息历史
    │   ├── presence.json   # 在线状态信息
    │   ├── read_status.json # 已读管理
    │   └── waiting_agents.json # 等待中的代理
    └── dev-team/
        ├── messages.jsonl
        ├── presence.json
        ├── read_status.json
        └── waiting_agents.json

故障排除

文件锁定错误

• 如果发生LOCK_TIMEOUT错误，请增加AGENT_COMM_LOCK_TIMEOUT环境变量
• 如果存在旧的锁定文件（.lock扩展），请手动删除

无法找到房间

• 房间名称只能包含字母数字、连字符和下划线
• 在进入房间之前，请确保已经创建了该房间

无法发送消息

• 请确认代理是否已经进入了房间
• 请确认消息大小是否在限制范围内（默认1000字符）

许可证

MIT License

贡献

欢迎提交Pull Request。对于较大的更改，请先创建Issue并讨论更改内容。

支持

如果遇到问题，请在GitHub的问题跟踪器中报告。