MCP agent messenging

MCP代理消息服务器

一种模型上下文协议（MCP）服务器，通过基于项目的聊天室实现代理之间的通信。每个代理都会收到一个唯一的德语名称，并且可以与在同一项目目录中工作的其他代理进行通信。

入门指南

1. 安装依赖项:

   npm install

快速开始

1. 构建服务器:

   npm run build

1. 运行服务器:

   npm start

1. 发送消息:

使用 send_message 工具中包含您想要的消息内容。

   {
     "message": "Hello from my agent!"
   }

1. 读取消息:

使用 read_messages 查看对话的工具。

   {
     "count": 10
   }

特性

核心功能

• 基于项目的聊天室：每个项目路径/目录都有单独的聊天室
• 持久化存储：聊天记录保存为JSON文件（每个项目一个文件）
• 自动代理命名：每个代理人都有一个唯一的德国名字（汉斯、弗里德里希、格蕾塔等）
• 实时消息：代理可以在其项目聊天中发送和接收消息
• 代理发现：查看哪些代理在您的项目中处于活动状态
• 系统通知：代理加入或离开时自动通知

第2层高级功能

• 结构化消息：具有元数据的丰富消息类型（文本、系统、命令、通知）
• 消息ID：每条消息的唯一标识符，支持跟踪和确认
• 时间戳：所有消息上的ISO 8601时间戳用于精确计时
• 高级过滤：按时间戳或时间范围（最后N秒）过滤消息
• 消息修剪：自动清理-保留最后1000条消息（可配置）
• 压缩Gzip压缩可节省80%的存储空间
• 跨过程安全：原子操作和文件锁定可防止竞争条件

建筑

服务器采用干净的模块化架构构建：

src/
├── types.ts           # TypeScript type definitions
├── agent-namer.ts     # German name assignment system
├── persistence.ts     # JSON file persistence layer
├── chat-manager.ts    # Chat room and message management
└── index.ts           # MCP server implementation

data/                  # Chat history (one JSON file per project)
└── .json

组件

• 代理人名称：管理德语名称池，并为代理商分配唯一的名称
• 存储管理器：处理将聊天室保存到JSON文件或从JSON文件加载聊天室
• 聊天管理器：处理聊天室创建、消息存储和代理连接
• MCP服务器：展示三种代理通信工具

安装

# Build the project
npm run build

# Run the server
npm start

API 参考

服务器为代理通信提供了四种工具。

read_messages

阅读项目共享聊天室中其他代理的消息。使用此功能可以了解对话，并查看其他代理正在做什么。

• 参数:

- count （可选，数字）：要检索的最近邮件数（1-100）。 - project_path （可选，字符串）：项目目录路径。默认为当前工作目录。 - since_timestamp （可选，字符串）：ISO 8601时间戳，用于在此时间之后检索消息。 - last_seconds （可选，数字）：检索最近N秒的消息。

• 退货:

- 你经纪人的名字。 - 按时间顺序排列的消息列表。

• 例子:

- 获取最后10条消息：

    { "count": 10 }

- 获取最近5分钟的消息：

    { "last_seconds": 300 }

send_message

向项目共享聊天室中的其他代理发送消息。使用此功能可以协调任务、共享状态更新或寻求帮助。

• 参数:

- message （必填，字符串）：消息内容。 - project_path （可选，字符串）：项目目录路径。 - message_type （可选，字符串）：消息类型('text', 'command', 'notification', 'system').默认为 'text'. - metadata （可选，对象）：其他结构化数据。

• 退货:

- 确认您的代理人姓名和消息ID。

• 示例:

  {
    "message": "Deploying version 1.2.3 to production.",
    "message_type": "command",
    "metadata": { "version": "1.2.3" }
  }

search_messages

在共享聊天记录中搜索来自任何与特定查询匹配的代理的消息。有助于查找过去的对话或特定信息。

• 参数:

- query （必填，字符串）：在消息内容中搜索的文本。 - project_path （可选，字符串）：项目目录路径。

• 退货:

- 你经纪人的名字。 - 与搜索查询匹配的邮件列表。

• 示例:

  {
    "query": "deployment"
  }

get_agent_names

查看项目聊天室中当前有哪些其他代理处于活动状态。这有助于你了解可以与谁合作。

• 参数:

- project_path （可选，字符串）：项目目录路径。

• 退货:

- 你经纪人的名字。 - 活动代理名称列表。

• 示例:

  { "project_path": "/path/to/project" }

heartbeat

向聊天室中的其他代理发出您的存在信号。在长时间运行的任务中使用此功能，让其他人知道您仍然在线并处于活动状态。

• 参数:

- project_path （可选，字符串）：项目目录路径。

• 退货:

- 确认你的代理人的名字。

• 示例:

  { "project_path": "/path/to/project" }

消息修剪和保留

系统会自动管理消息历史记录，以防止磁盘无限增长：

默认行为

• 限制：保留最后一个 1000条消息 每个聊天室
• 修剪：超过限制时，最旧的邮件将自动删除
• 时机：发送消息时会自动进行修剪

可配置的保留

您可以使用环境变量自定义保留限制：

# Keep last 500 messages (smaller footprint)
export MCP_MESSAGE_RETENTION_LIMIT=500

# Keep last 5000 messages (larger history)
export MCP_MESSAGE_RETENTION_LIMIT=5000

# Run the server
npm start

配置规则：

• 最少：100条消息
• 最多：50000条消息
• 默认值：1000条消息
• 无效值将返回默认值并发出警告

配置示例

# For a small team with frequent messages
MCP_MESSAGE_RETENTION_LIMIT=500 npm start

# For a large project with important history
MCP_MESSAGE_RETENTION_LIMIT=10000 npm start

存储和性能

压缩

• 消息存储在 GZIP压缩
• 在典型聊天文件上实现约80%的存储节省
• 透明-压缩/解压缩自动发生

存储位置

• 聊天记录： `./data/

.json.gz`

• 代理身份： `./.mcp-identities/.agent-identity-

-.json`

• 所有内容均与项目目录相关

性能特征

• 磁盘I/O：每个操作都会从磁盘重新加载以保持一致性
• 文件锁定：具有原子操作的跨进程安全
• 可扩展性：适用于每个聊天室每秒约200条消息

关键概念

这个消息传递系统建立在几个简单但强大的概念之上：

1. 基于文件的通信：代理通过读写共享JSON文件进行通信 data/ 目录。每个项目有一个文件，该文件以项目路径的净化版本命名。这种方法不需要中央服务器或网络连接。

1. 代理身份：每个代理实例在首次启动时都会被赋予一个唯一的德语名称（例如“Hans”、“Greta”）。此身份存储在 .agent-identity.json 代理工作目录中的文件，并在重新启动时重复使用。

1. 数据持久层：所有消息都存储在项目的JSON文件中。聊天历史记录在每次操作之前从该文件加载，并在操作后立即保存，以确保所有代理对对话有一致的看法。

1. 代理发现：“活跃”代理人名单来源于 sender 聊天历史中最近消息的字段。这 heartbeat 该工具允许代理发出他们存在的信号，这会在聊天中添加一条“系统”消息，并将他们保留在活动列表中。

示例使用场景

// Agent 1 (Hans) in /project/frontend
send_message({ message: "Starting work on the login page" })

// Agent 2 (Friedrich) joins /project/frontend
// System: "Friedrich has joined the chat"

read_messages({ count: 5 })
// Output:
// You are: Friedrich
// Last 5 message(s):
// [10:30:15] System: Hans has joined the chat
// [10:31:22] Hans: Starting work on the login page
// [10:32:10] System: Friedrich has joined the chat

get_agent_names()
// Output:
// You are: Friedrich
// Agents in this chat room:
// Hans, Friedrich

// Friedrich sends a message
send_message({ message: "I'll handle the backend API" })

德语名称

服务器包括50个传统的德语名字（25个男性，25个女性）：

男名汉斯、弗里德里希、卡尔、威廉、奥托、海因里希、赫尔曼、恩斯特、保罗、沃纳、沃尔特、弗朗茨、约瑟夫、路德维希、格奥尔格、克劳斯、君特、迪特尔、赫尔穆特、于尔根、格哈德、沃尔夫冈·霍斯特、曼弗雷德、贝恩德

女性姓名：格蕾塔、弗里达、玛格丽特、艾玛、安娜、莉泽尔、赫尔加、格特鲁德、英格丽、莫妮卡、乌苏拉、布丽吉特、克里斯塔、雷娜特、佩特拉、萨宾、海科、卡特琳、克劳迪娅、斯蒂芬妮、安克、尤特、贝特、卡琳、玛蒂娜

如果有50多个代理处于活动状态，则名称将以数字作为后缀（例如Hans2、Friedrich2）。

Claude代码的配置

此消息传递服务器旨在与来自Anthropic的实验性AI编码助手Claude Code一起使用。

重要提示：多实例架构

每个Claude Code代理都在运行 它自己的实例 此MCP服务器。代理通过读取/写入共享JSON文件进行通信 data/ 目录。

它是如何工作的：

1. 代理1（Hans）运行实例A→ 写信给 data/project_x.json
2. 代理2（Friedrich）运行实例B→ 阅读自 data/project_x.json
3. 他们通过共享文件查看彼此的消息

安装说明

1. 构建项目 （如果你还没有）：

   cd /Users/janspoerer/code/miscellaneous/mcp_agent_messenging
   npm install
   npm run build

1. 添加到Claude代码设置:

- 打开克劳德代码设置 - 添加MCP服务器配置：

{
  "mcpServers": {
    "agent-messaging": {
      "command": "node",
      "args": [
        "/Users/janspoerer/code/miscellaneous/mcp_agent_messenging/dist/index.js"
      ]
    }
  }
}

1. 开始使用它:

- 每个Claude Code实例都将获得一个唯一的德语名称 - 该名称持续存在 .agent-identity.json - 同一项目路径中的所有代理通过以下方式共享消息 data/ 文件夹

多代理示例

# Agent 1 terminal
claude-code
# Gets name "Hans", can use send_message

# Agent 2 terminal (same data/ folder)
claude-code
# Gets name "Friedrich", can use read_messages to see Hans's messages

具有单独代理组的多个项目

系统支持 不同项目之间完全隔离每个项目路径都有自己的隔离聊天室，其中有单独的消息历史记录。

示例：三个独立项目

Project A: /path/to/frontend
├─ Agents: Hans, Friedrich, Greta
├─ Messages: Frontend development discussions
└─ Chat file: data/hash-frontend.json.gz

Project B: /path/to/backend
├─ Agents: Emma, Wilhelm, Sabine
├─ Messages: Backend API discussions
└─ Chat file: data/hash-backend.json.gz

Project C: /path/to/infrastructure
├─ Agents: Karl, Liesel, Georg
├─ Messages: DevOps and infrastructure
└─ Chat file: data/hash-infrastructure.json.gz

主要特点：

• ✅ 完成消息隔离 -项目A消息从未出现在项目B中
• ✅ 独立聊天记录 -每个项目都维护自己的消息历史记录
• ✅ 单独的代理组 -不同的团队可以不受干扰地工作
• ✅ 跨项目代理工作 -同一代理可以在多个项目中工作（每个项目的消息保持隔离）
• ✅ 可扩展到许多项目 -对并发项目的数量没有限制

示例：代理在多个项目中工作

// Same agent (Hans) working in multiple projects
// All messages are properly isolated by project

// Working on Frontend
send_message({
  message: "Fixed login form validation",
  project_path: "/path/to/frontend"
})

// Later, working on Backend
send_message({
  message: "Implemented new API endpoint",
  project_path: "/path/to/backend"
})

// Query each project independently
read_messages({ project_path: "/path/to/frontend" })
// Returns: Only frontend messages

read_messages({ project_path: "/path/to/backend" })
// Returns: Only backend messages (no frontend messages)

项目隔离的工作原理：

1. 使用SHA256对项目路径进行哈希运算→ 生成唯一的文件名
2. /path/to/frontend → data/a1b2c3.json.gz
3. /path/to/backend → data/d4e5f6.json.gz
4. 不同的文件=完全隔离的数据
5. 原子文件锁定确保每个项目的线程安全

通过测试验证：

• ✅ 4项全面的多项目隔离测试
• ✅ 已确认2+个项目之间的消息隔离
• ✅ 过滤在每个项目中都能正常工作
• ✅ 不可能发生跨项目污染

发展

# Install dependencies
npm install

# Build and run
npm run dev

TypeScript类型

所有核心类型在 src/types.ts:

• Message：带有发件人、内容和时间戳的个人聊天消息
• ChatRoom：聊天室数据，包括代理和消息历史记录
• AgentConnection：代理连接元数据

这 src/persistence.ts 模块通过自动序列化/反序列化处理所有文件I/O操作。

错误处理

服务器处理常见错误情况：

• 代理未连接：首次调用工具时自动连接
• 空消息：已拒绝，并显示错误消息
• 无效的邮件计数：必须介于1到100之间
• 未找到聊天室：返回空数组/列表

测试

该系统包括一个全面的测试套件 33个单元测试 涵盖所有功能：

运行测试

# Run all tests
npm test

# Run tests in watch mode (auto-rerun on file changes)
npm run test:watch

# Generate coverage report
npm run test:coverage

测试覆盖率

测试包括以下组件：

• 代理命名 （5个测试）：唯一名称分配、防冲突、池管理
• 持久层 （5+测试）：文件I/O、压缩、原子操作、文件锁定
• 聊天管理器 （10+测试）：消息操作、过滤、修剪、代理发现
• 消息过滤 （5个测试）：时间戳过滤、时间范围、组合过滤器
• 消息修剪 （7个测试）：保留限制、FIFO移除、边界条件
• 多项目隔离 （4次测试）： 新 单独的聊天记录、过滤隔离、3个以上并发项目、跨项目代理工作

测试结果

✅ Test Suites: 3 passed, 3 total
✅ Tests: 33 passed, 33 total
✅ Execution Time: ~2.1 seconds

新的多项目测试（已验证）：

• ✅ 不同项目的单独聊天历史记录
• ✅ 筛选项目之间隔离的结果
• ✅ 支持3个以上同时独立项目
• ✅ Agent可以在多个项目中工作而不受干扰

所有测试均无故障通过，确保多项目场景的生产准备就绪。

故障排除

运行服务器时出现“没有这样的文件或目录”错误

此错误通常意味着您尚未构建项目。运行以下命令以构建服务器：

npm run build

未看到来自其他代理的消息

如果您与其他代理不在同一项目目录中，则可能会发生这种情况。确保您与其他代理位于同一目录中，并且您具有正确的读写权限 data 目录。

许可证

麻省理工学院

贡献

欢迎投稿！请按照以下步骤进行贡献：

1. 报告Bug：使用问题跟踪器报告任何错误。
2. 提交拉取请求:

- 分叉存储库。 - 为您的功能或错误修复创建一个新分支。 - 做出更改，并以明确的信息提交。 - 跑 npm test 以确保所有测试通过。 - 推送您的更改并打开拉取请求。