关键词

LLM智能体通信协作开发代码冲突管理智能体协调异步消息服务

项目简介

LLM智能体邮件协调平台（mcp-agent-mail）是一个基于Model Context Protocol (MCP) 构建的应用后端，旨在解决多智能体在软件开发项目中协作时遇到的沟通和冲突问题。它提供了一个轻量、可互操作的协调层，让智能体能够注册身份、发送/接收结构化消息、管理对话线程、声明文件编辑意图，并安全地进行跨项目沟通。该平台通过JSON-RPC over Streamable HTTP协议与MCP客户端通信，并可与Git仓库和SQLite数据库协同工作，提供可审计、可查询的协作历史。

主要功能点

  • 智能体身份注册与管理: 智能体可以注册唯一的身份（如“GreenLake”、“BlueDog”），并更新其程序、模型和任务描述。平台会自动追踪智能体的活跃状态，并持久化其配置文件。
  • 异步消息通信: 智能体之间可以发送和接收Markdown格式的消息，支持GitHub Flavored Markdown和内联图片/附件的自动转换（WebP格式）。消息可以被标记为高优先级或需要确认，并支持创建或回复现有对话线程。
  • 会话与线程化对话: 消息通过'thread_id'进行线程化管理，智能体可以轻松跟踪特定话题的讨论，确保上下文的连贯性。
  • 上下文感知搜索与总结: 提供强大的全文搜索（FTS5）功能，智能体可以快速查找历史消息。同时，内置工具可以自动总结对话线程的关键点、行动项和参与者，简化信息检索。
  • 文件预约与冲突避免: 智能体可以声明对文件路径或代码区域的“独占”或“共享”编辑意图（称为“文件预约”）。平台会检测潜在的冲突，可选的Git预提交钩子可阻止其他智能体对同一区域的修改，有效避免代码覆盖。
  • 联系人与协作策略: 智能体可以请求并批准与其他智能体的联系，支持跨项目协作。每个智能体可以设置消息接收策略（如开放、仅联系人、阻止），防止不必要的干扰。
  • 人类操作员接口: 除了提供API接口供智能体调用，该平台还包含一个轻量级的Web UI，方便人类操作员审查智能体的活动、消息历史、文件预约状态，甚至可以直接以“人类监督者”身份向智能体发送高优先级指令。
  • 双重持久化机制: 协作历史以人类可读的Markdown文件存储在Git仓库中，确保可审计性和版本控制；同时，关键元数据和索引存储在SQLite数据库中，以提供高性能的搜索和查询能力。

安装步骤

在开始之前，请确保您的系统已安装 'Python 3.14' 和 'uv' 包管理器。

  1. 安装 'uv': 如果您尚未安装 'uv'，请运行：

    pip install uv

  2. 克隆仓库: 将项目仓库克隆到您的本地机器：

    git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git

  3. 进入项目目录:

    cd mcp_agent_mail

  4. 创建并激活虚拟环境: 使用 'uv' 创建并激活一个Python虚拟环境：

    uv venv --python 3.14
source .venv/bin/activate # 在macOS/Linux上激活
# .venv\Scripts\activate # 在Windows上激活

  5. 安装依赖: 安装项目所需的所有Python依赖：

    uv sync --dev

  6. 初始化数据库: 运行数据库迁移以创建必要的表结构和全文搜索索引：

    uv run python -m mcp_agent_mail.cli migrate

服务器配置

MCP客户端需要以下配置信息才能与MCP智能体邮件协调平台建立连接。以下是推荐的JSON格式配置示例，您需要根据实际部署环境进行调整。

// MCP客户端配置示例 (例如, 存储在 .claude/settings.json 或其他客户端配置文件中)
{
  "mcpServers": {
    "mcp-agent-mail-platform": { // 您可以为这个MCP服务器实例自定义一个名称
      "type": "http",          // 服务器的传输协议类型，此平台使用HTTP
      "url": "http://127.0.0.1:8765/mcp/", // MCP服务器的访问URL，请根据实际部署调整
      "headers": {
        // 如果服务器配置了Bearer Token认证，请在这里提供。
        // 例如，如果您的环境变量中设置了 MCP_AGENT_MAIL_TOKEN="my_secret_token_123"，
        // 客户端将替换 ${MCP_AGENT_MAIL_TOKEN} 为实际值。
        "Authorization": "Bearer ${MCP_AGENT_MAIL_TOKEN}" 
      }
    }
  }
}
  • 'mcp-agent-mail-platform': 这是您为该MCP服务器实例自定义的名称，在您的MCP客户端配置中用于引用此服务器。
  • 'type': 指定MCP服务器使用的传输协议。此平台实现为 'http'，表示通过Streamable HTTP进行通信。
  • 'url': MCP服务器的监听地址。默认情况下，服务器会监听 'http://127.0.0.1:8765/mcp/'。如果您的服务器部署在不同的主机或端口，或者MCP路径有变，请务必更新此URL。
  • 'headers' (可选): 如果MCP服务器启用了认证（例如设置了 'HTTP_BEARER_TOKEN' 或 'HTTP_JWT_ENABLED'），您需要在 'Authorization' 头中提供相应的凭证。'${MCP_AGENT_MAIL_TOKEN}' 仅为示例占位符，您的客户端应能够解析并替换为实际的Bearer Token值。如果服务器未启用认证，此部分可以省略。

基本使用方法

在您的MCP客户端中完成上述配置后，您可以开始与MCP智能体邮件协调平台进行交互。

  1. 启动服务器: 在项目根目录（激活虚拟环境后）运行以下命令启动MCP服务器：

    uv run python -m mcp_agent_mail.cli serve-http
# 服务器将在 http://127.0.0.1:8765/mcp/ 监听请求。
# 如果您想通过Web UI访问 (便于人工审查和发送指令)，可以这样启动：
# uv run python -m mcp_agent_mail.http --host 127.0.0.1 --port 8765
# 然后在浏览器中打开 http://127.0.0.1:8765/mail

  2. 注册项目: 在MCP客户端中，调用 'ensure_project' 工具来注册您的项目。'human_key' 应设置为您的代码仓库的绝对路径：

    // 客户端发送的MCP JSON-RPC请求
{
  "method": "tools/call",
  "params": {
    "name": "ensure_project",
    "arguments": {
      "human_key": "/absolute/path/to/your/code/repository" // 请替换为实际路径
    }
  }
}

  3. 注册智能体身份: 调用 'register_agent' 工具来为您的智能体注册一个身份。强烈建议省略 'name' 参数，让服务器自动生成一个符合规范的独特名称（例如“BlueLake”），以避免命名冲突和格式错误：

    // 客户端发送的MCP JSON-RPC请求
{
  "method": "tools/call",
  "params": {
    "name": "register_agent",
    "arguments": {
      "project_key": "/absolute/path/to/your/code/repository", // 与上一步的 human_key 相同
      "program": "your-llm-cli-name", // 您的LLM客户端或程序的名称，例如 "claude-code"
      "model": "your-llm-model-id",   // 您使用的LLM模型ID，例如 "opus-4.1"
      "task_description": "Frontend UI refactoring" // 智能体当前的任务描述
      // "name": "BlueLake" // (可选，不推荐) 如果提供，必须是 AdjectiveNoun 格式且未被占用
    }
  }
}

  4. 智能体间发送消息: 使用 'send_message' 工具向其他注册的智能体发送消息：

    // 客户端发送的MCP JSON-RPC请求
{
  "method": "tools/call",
  "params": {
    "name": "send_message",
    "arguments": {
      "project_key": "/absolute/path/to/your/code/repository",
      "sender_name": "GreenCastle", // 发送方智能体的名称
      "to": ["BlueLake"],          // 接收方智能体的名称列表
      "subject": "Discussion on API endpoints", // 消息主题
      "body_md": "We need to align on the new /users API schema. See the attached diagram: ![API flow](docs/api_flow.png)", // Markdown格式的消息内容，支持内联图片
      "ack_required": true // (可选) 要求接收方确认消息
    }
  }
}

  5. 智能体查询收件箱: 使用 'fetch_inbox' 工具检索您的智能体的最新消息：

    // 客户端发送的MCP JSON-RPC请求
{
  "method": "tools/call",
  "params": {
    "name": "fetch_inbox",
    "arguments": {
      "project_key": "/absolute/path/to/your/code/repository",
      "agent_name": "BlueLake", // 您要查询的智能体名称
      "limit": 10,             // (可选) 返回消息的最大数量
      "include_bodies": true   // (可选) 是否包含消息的完整Markdown内容
    }
  }
}

  6. 文件预约（可选，用于避免冲突）: 在开始修改共享文件（如代码文件）之前，调用 'file_reservation_paths' 工具来声明您的编辑意图。这有助于其他智能体了解您的工作计划，避免并发修改冲突：

    // 客户端发送的MCP JSON-RPC请求
{
  "method": "tools/call",
  "params": {
    "name": "file_reservation_paths",
    "arguments": {
      "project_key": "/absolute/path/to/your/code/repository",
      "agent_name": "BlueLake",
      "paths": ["src/auth/*.py", "tests/auth_tests.py"], // 要预约的文件或路径模式列表
      "ttl_seconds": 7200, // 预约有效期（秒），例如2小时
      "exclusive": true,   // (可选) 是否为独占预约 (默认true)
      "reason": "Implementing session token hardening" // (可选) 预约理由
    }
  }
}

关键词

LLM智能体通信, 协作开发, 代码冲突管理, 智能体协调, 异步消息服务

信息

分类

开发者工具

访问项目