金大哥 - mcp_agent_mail MCP 详情

article

README

🚀 MCP Agent Mail

MCP Agent Mail 是一个专为编码代理设计的类邮件协调层，以仅支持 HTTP 的 FastMCP 服务器形式呈现。它为代理提供了易于记忆的身份、收件箱/发件箱、可搜索的消息历史记录，以及自愿的文件保留“租约”，以避免相互干扰。

🚀 快速开始

一键安装

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes

上述命令会执行以下操作：

若缺少 uv 则进行安装，并在当前会话中更新 PATH。
创建 Python 3.14 虚拟环境，并使用 uv 安装依赖项。
运行自动检测集成，以连接支持的代理工具。
在端口 8765 上启动 MCP HTTP 服务器，并打印一个掩码令牌。
在 scripts/ 目录下创建辅助脚本（包括 run_server_with_token.sh）。

若你想指定特定位置或选项，可添加如 --dir <path>、--project-dir <path>、--no-start、--start-only、--port <number> 或 --token <hex> 等标志。

若遇到端口冲突：可使用 --port 指定不同的端口（默认端口为 8765）：

# 自定义端口安装
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes

# 或在安装后使用 CLI 命令
uv run python -m mcp_agent_mail.cli config set-port 9000

手动安装

克隆仓库，在 Python 3.14 虚拟环境中使用 uv 进行设置和安装（若没有 uv，需先进行安装），然后运行 scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh。这将自动为你安装的各种编码代理工具进行设置，并在端口 8765 上启动 MCP 服务器。若你日后想再次运行 MCP 服务器，只需运行 scripts/run_server_with_token.sh：

# 安装 uv（若尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# 克隆仓库
git clone https://github.com/Dicklesworthstone/mcp_agent_mail
cd mcp_agent_mail

# 创建 Python 3.14 虚拟环境并安装依赖项
uv python install 3.14
uv venv -p 3.14
source .venv/bin/activate
uv sync

# 检测已安装的编码代理，进行集成，并在端口 8765 上启动 MCP 服务器
scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh

# 之后，使用相同的令牌再次运行 MCP 服务器
scripts/run_server_with_token.sh

# 现在，只需在其他控制台中启动 Codex - CLI、Claude Code 或其他代理工具；它们应该可以使用邮件工具。以下是一段现成的文本，你可以添加到现有的 AGENTS.md 或 CLAUDE.md 文件末尾，以帮助你的代理更好地利用新工具。

# 安装后更改端口
uv run python -m mcp_agent_mail.cli config set-port 9000

✨ 主要特性

身份管理：为编码代理提供临时但持久的身份，便于识别和跟踪。
消息传递：支持发送和接收包含图像的 GitHub 风格 Markdown 消息，方便信息交流。
搜索与汇总：可对对话进行搜索、汇总和线程化管理，提高信息检索效率。
文件保留：允许代理声明对文件或文件通配符的保留租约，避免冲突。
目录查看：可查看活动代理、程序/模型和活动的目录，了解整体情况。

💻 使用示例

基础用法

# 一键安装
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes

高级用法

# 自定义端口安装
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --port 9000 --yes

📚 详细文档

集成 Beads（依赖感知任务规划）

Beads 是一个轻量级任务规划器（bd CLI），它与 Agent Mail 互补，将状态和依赖关系集中管理，而 Agent Mail 负责消息传递、文件保留和审计跟踪。项目地址：steveyegge/beads

网页界面（面向人类的邮件查看器）

服务器提供了一个轻量级、服务器渲染的网页界面，供人类使用。你可以浏览项目、代理、收件箱、单个消息、附件、文件保留信息，并在支持 FTS5 时进行全文搜索（自动回退到 LIKE 查询）。

静态邮箱导出（共享和分发存档）

share 命令组可将项目的邮箱导出为一个便携式、只读的捆绑包，任何人都可以在浏览器中查看。这适用于审计人员、利益相关者或团队成员，他们可以在不启动完整 MCP Agent Mail 堆栈的情况下浏览线程、搜索历史记录或证明交付时间线。

🔧 技术细节

核心架构

HTTP 服务器：仅支持 HTTP 的 FastMCP 服务器，采用可流式 HTTP 协议，不使用 SSE 和 STDIO。
持久化模型：采用双持久化模型，将人类可读的 Markdown 文件存储在每个项目的 Git 仓库中，同时使用 SQLite 进行快速搜索、目录查询和文件保留/租约管理。
查询方式：采用“目录/LDAP”风格的查询方式，为代理提供易于记忆的形容词 + 名词名称。
文件保留：提供咨询性的文件保留功能，可选择使用预提交钩子来强制执行。
资源层：提供方便的读取资源层，如 resource://inbox/{agent}。

数据模型（SQLite）

projects(id, human_key, slug, created_at)
agents(id, project_id, name, program, model, task_description, inception_ts, last_active_ts, attachments_policy, contact_policy)
messages(id, project_id, sender_id, thread_id, subject, body_md, created_ts, importance, ack_required, attachments)
message_recipients(message_id, agent_id, kind, read_ts, ack_ts)
file_reservations(id, project_id, agent_id, path_pattern, exclusive, reason, created_ts, expires_ts, released_ts)
agent_links(id, a_project_id, a_agent_id, b_project_id, b_agent_id, status, reason, created_ts, updated_ts, expires_ts)
project_sibling_suggestions(id, project_a_id, project_b_id, score, status, rationale, created_ts, evaluated_ts, confirmed_ts, dismissed_ts)
fts_messages(message_id UNINDEXED, subject, body) + 触发器用于增量更新

📄 许可证

文档中未提及相关信息。

📋 配置参考

| 名称 | 默认值 | 描述 | | ---- | ---- | ---- | | STORAGE_ROOT | ~/.mcp_agent_mail_git_mailbox_repo | 每个项目的仓库和 SQLite 数据库的根目录 | | HTTP_HOST | 127.0.0.1 | HTTP 传输的绑定主机 | | HTTP_PORT | 8765 | HTTP 传输的绑定端口 | | HTTP_PATH | /mcp/ | MCP 端点挂载的 HTTP 路径 | | HTTP_JWT_ENABLED | false | 启用 JWT 验证中间件 | | HTTP_JWT_SECRET | | HS* 算法的 HMAC 密钥（开发环境） | | HTTP_JWT_JWKS_URL | | 用于公钥验证的 JWKS URL | | HTTP_JWT_ALGORITHMS | HS256 | 允许的算法的 CSV 列表 | | HTTP_JWT_AUDIENCE | | 预期的 aud（可选） | | HTTP_JWT_ISSUER | | 预期的 iss（可选） | | HTTP_JWT_ROLE_CLAIM | role | 包含角色的 JWT 声明名称 | | HTTP_RBAC_ENABLED | true | 强制执行只读与工具的 RBAC | | HTTP_RBAC_READER_ROLES | reader,read,ro | 读者角色的 CSV 列表 | | HTTP_RBAC_WRITER_ROLES | writer,write,tools,rw | 写者角色的 CSV 列表 | | HTTP_RBAC_DEFAULT_ROLE | reader | 无角色时使用的角色 | | HTTP_RBAC_READONLY_TOOLS | health_check,fetch_inbox,whois,search_messages,summarize_thread,summarize_threads | 只读工具名称的 CSV 列表 | | HTTP_RATE_LIMIT_ENABLED | false | 启用令牌桶限流器 | | HTTP_RATE_LIMIT_BACKEND | memory | memory 或 redis | | HTTP_RATE_LIMIT_PER_MINUTE | 60 | 旧的每个 IP 的限制（回退） | | HTTP_RATE_LIMIT_TOOLS_PER_MINUTE | 60 | 工具调用的每分钟限制 | | HTTP_RATE_LIMIT_TOOLS_BURST | 0 | 工具的可选突发限制（0 = 自动 = rpm） | | HTTP_RATE_LIMIT_RESOURCES_PER_MINUTE | 120 | 资源读取的每分钟限制 | | HTTP_RATE_LIMIT_RESOURCES_BURST | 0 | 资源的可选突发限制（0 = 自动 = rpm） | | HTTP_RATE_LIMIT_REDIS_URL | | 用于多工作进程限制的 Redis URL | | HTTP_REQUEST_LOG_ENABLED | false | 打印请求日志（Rich + JSON） | | LOG_JSON_ENABLED | false | 输出 structlog JSON 日志 | | INLINE_IMAGE_MAX_BYTES | 65536 | send_message 期间内联 WebP 图像的阈值（字节） | | CONVERT_IMAGES | true | 将图像转换为 WebP（并可选地内联小图像） | | KEEP_ORIGINAL_IMAGES | false | 除了 WebP 之外，还存储原始图像字节（附件/原始文件/） | | LOG_LEVEL | INFO | 服务器日志级别 | | HTTP_CORS_ENABLED | false | 启用 CORS 中间件 | | HTTP_CORS_ORIGINS | | 允许的源的 CSV 列表（例如，https://app.example.com,https://ops.example.com） | | HTTP_CORS_ALLOW_CREDENTIALS | false | 允许 CORS 上的凭证 | | HTTP_CORS_ALLOW_METHODS | * | 允许的方法的 CSV 列表或 * | | HTTP_CORS_ALLOW_HEADERS | * | 允许的头的 CSV 列表或 * | | HTTP_BEARER_TOKEN | | 静态令牌（仅在 JWT 禁用时使用） | | HTTP_ALLOW_LOCALHOST_UNAUTHENTICATED | true | 允许本地主机请求无需身份验证（开发便利） | | HTTP_OTEL_ENABLED | false | 启用 OpenTelemetry 仪表化 | | OTEL_SERVICE_NAME | mcp-agent-mail | 遥测服务名称 | | OTEL_EXPORTER_OTLP_ENDPOINT | | OTLP 导出器端点 URL | | APP_ENVIRONMENT | development | 环境名称（开发/生产） | | DATABASE_URL | sqlite+aiosqlite:///./storage.sqlite3 | SQLAlchemy 异步数据库 URL | | DATABASE_ECHO | false | 调试时回显 SQL 语句 | | GIT_AUTHOR_NAME | mcp-agent | Git 提交作者姓名 | | GIT_AUTHOR_EMAIL | mcp-agent@example.com | Git 提交作者电子邮件 | | LLM_ENABLED | true | 启用 LiteLLM 进行线程摘要和发现 | | LLM_DEFAULT_MODEL | gpt - 5 - mini | 默认 LiteLLM 模型标识符 | | LLM_TEMPERATURE | 0.2 | LLM 文本生成的温度 | | LLM_MAX_TOKENS | 512 | LLM 完成的最大令牌数 | | LLM_CACHE_ENABLED | true | 启用 LLM 响应缓存 | | LLM_CACHE_BACKEND | memory | LLM 缓存后端（memory 或 redis） | | LLM_CACHE_REDIS_URL | | LLM 缓存的 Redis URL（如果后端 = redis） | | LLM_COST_LOGGING_ENABLED | true | 记录 LLM API 成本和令牌使用情况 | | FILE_RESERVATIONS_CLEANUP_ENABLED | false | 启用过期文件保留的后台清理 | | FILE_RESERVATIONS_CLEANUP_INTERVAL_SECONDS | 60 | 文件保留清理任务的间隔 | | FILE_RESERVATION_INACTIVITY_SECONDS | 1800 | 保留被视为过时之前的不活动阈值（秒） | | FILE_RESERVATION_ACTIVITY_GRACE_SECONDS | 900 | 最近邮件/文件系统/Git 活动的宽限期，以保持保留活动 | | FILE_RESERVATIONS_ENFORCEMENT_ENABLED | true | 在冲突的文件保留时阻止消息写入 | | ACK_TTL_ENABLED | false | 启用逾期 ACK 扫描（日志/面板；见视图/资源） | | ACK_TTL_SECONDS | 1800 | 逾期 ACK 的年龄阈值（秒） | | ACK_TTL_SCAN_INTERVAL_SECONDS | 60 | 逾期 ACK 的扫描间隔 | | ACK_ESCALATION_ENABLED | false | 启用逾期 ACK 的升级 | | ACK_ESCALATION_MODE | log | log 或 file_reservation 升级模式 | | ACK_ESCALATION_CLAIM_TTL_SECONDS | 3600 | 升级文件保留的 TTL | | ACK_ESCALATION_CLAIM_EXCLUSIVE | false | 使升级文件保留具有排他性 | | ACK_ESCALATION_CLAIM_HOLDER_NAME | | 拥有升级文件保留的运维代理名称 | | CONTACT_ENFORCEMENT_ENABLED | true | 在消息传递之前强制执行联系策略 | | CONTACT_AUTO_TTL_SECONDS | 86400 | 自动批准的联系人的 TTL（1 天） | | CONTACT_AUTO_RETRY_ENABLED | true | 在策略违规时自动重试联系请求 | | MESSAGING_AUTO_REGISTER_RECIPIENTS | true | 在 send_message 期间自动创建缺失的本地收件人并重试路由 | | MESSAGING_AUTO_HANDSHAKE_ON_BLOCK | true | 当联系策略阻止传递时，尝试进行联系握手（自动接受）并重试 | | TOOLS_LOG_ENABLED | true | 记录工具调用以进行调试 | | LOG_RICH_ENABLED | true | 启用 Rich 控制台日志记录 | | LOG_INCLUDE_TRACE | false | 包括跟踪级别的日志 | | TOOL_METRICS_EMIT_ENABLED | false | 定期发出工具使用指标 | | TOOL_METRICS_EMIT_INTERVAL_SECONDS | 60 | 指标发出的间隔 | | RETENTION_REPORT_ENABLED | false | 启用保留/配额报告 | | RETENTION_REPORT_INTERVAL_SECONDS | 3600 | 保留报告的间隔（1 小时） | | RETENTION_MAX_AGE_DAYS | 180 | 保留策略报告的最大年龄 | | QUOTA_ENABLED | false | 启用配额强制执行 | | QUOTA_ATTACHMENTS_LIMIT_BYTES | 0 | 每个项目的最大附件存储（0 = 无限制） | | QUOTA_INBOX_LIMIT_COUNT | 0 | 每个代理的最大收件箱消息数（0 = 无限制） | | RETENTION_IGNORE_PROJECT_PATTERNS | demo,test*,testproj*,testproject,backendproj*,frontendproj* | 保留/配额报告中忽略的项目模式的 CSV 列表 | | AGENT_NAME_ENFORCEMENT_MODE | coerce | 代理命名策略：strict（拒绝无效的形容词 + 名词名称），coerce（如果无效则自动生成），always_auto（始终自动生成） |

mcp_agent_mail