Exchange Mail MCP Server

面向企业内网自建 Microsoft Exchange 的安全邮件 MCP Server。V1 支持邮件列表、搜索、读取、附件下载、文件夹列表、发送和回复，并通过应用级成员授权、EWS Impersonation、签名引用、幂等控制、发送配额和追加式审计约束访问。

当前实现不会在导入或构建 Runtime 时连接 Exchange。只有显式启动服务并调用邮件 Tool，或显式执行 EWS 探测命令时，才会访问配置的固定 EWS Endpoint。

安全边界

• Agent 永远拿不到 Exchange Service Account 密码。
• Tool 参数中的邮箱、邮件 ID、附件 ID 和用户身份均不作为授权依据。
• 身份仅来自 MCP HTTP 边界验证后的 RS256 JWT：sub 是员工，client_id 是应用。
• USER 只能访问和使用自己的邮箱；ADMIN 可查看应用纳管邮箱，但只能使用应用超级邮箱发送或回复。
• 不支持 SEND_AS、删除、移动、转发、批量发送、发送附件、日历和 RAG。
• 所有已认证邮件操作进入 HMAC 审计链；发送和回复还受应用策略、配额和幂等状态机约束。

详细设计：

• 安全设计
• 数据模型与接口契约
• Exchange 环境检查清单
• 内网部署与运维

环境要求

• Python 3.13
• 单进程、单 worker
• Windows 或 Linux 内网主机
• Mock 模式不需要 Exchange
• EWS 模式需要固定 HTTPS Endpoint、Service Account 和 Exchange Impersonation

本地安装

py -3.13 -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"

requirements-win-py313.lock 仅固定生产运行依赖；requirements-win-py313-dev.lock 在其上增加 pytest、mypy、ruff 等开发工具。scripts/download-wheels.ps1 默认只下载生产 wheel，传入 -IncludeDev 才下载开发工具。部署到不同操作系统时必须在对应联网环境重新生成锁文件并重新执行全部测试，不能直接复用 Windows wheel。

复制 .env.example 中的变量到进程环境。项目不会自动读取仓库中的 .env，避免意外加载错误环境；生产环境应由 Windows Service、systemd 或受控启动脚本注入变量。

HMAC keyring 是 UTF-8 JSON：

{
  "current_kid": "2026-08-v1",
  "keys": {
    "2026-08-v1": "base64url-encoded-random-key-at-least-32-bytes"
  }
}

审计和引用必须使用不同密钥。JWT 只配置本地 RSA 公钥，禁止把私钥部署到 MCP Server。

本机开发可显式启用 MAIL_MCP_DEV_AUTH_ENABLED=true，但仅允许 development/test 环境和 127.0.0.1/::1/localhost 监听，同时必须配置至少 32 字符的随机 MAIL_MCP_DEV_AUTH_TOKEN、固定 MAIL_MCP_DEV_AUTH_SUB 与 MAIL_MCP_DEV_AUTH_CLIENT_ID。生产环境强制拒绝该模式。

初始化应用与成员

.venv\Scripts\mail-mcp.exe init-db --database C:\mail-mcp\data\mail.db

.venv\Scripts\mail-mcp.exe app-upsert `
  --database C:\mail-mcp\data\mail.db `
  --client-id mail-agent `
  --name "POC Mail Agent" `
  --super-mailbox super@company.com `
  --allow-external

.venv\Scripts\mail-mcp.exe member-upsert `
  --database C:\mail-mcp\data\mail.db `
  --client-id mail-agent `
  --user-sub employee-1001 `
  --role USER `
  --mailbox employee@company.com

.venv\Scripts\mail-mcp.exe member-upsert `
  --database C:\mail-mcp\data\mail.db `
  --client-id mail-agent `
  --user-sub admin-1001 `
  --role ADMIN

新应用默认禁止外发。当前 POC 只有在明确传入 --allow-external 后才允许外部收件人。

启动

$env:WEB_CONCURRENCY = "1"
.\scripts\start-server.ps1

默认监听 127.0.0.1:8000，MCP Endpoint 为 /mcp。内网开放时必须放在反向代理 TLS 后面，并限制来源网络。程序会持有 SQLite 文件旁的进程锁；第二实例会启动失败。

发送与回复是有副作用的 Tool。Agent 必须先向用户展示预览并取得明确确认；MCP 不接受模型传入的 confirmed=true 一类布尔值作为可信审批。

Mock 到真实 EWS 的顺序

1. 先配置应用和成员，再以 Mock 模式启动；系统会为每个启用的纳管邮箱生成 Inbox、Sent Items、一封示例邮件和一个小附件，然后执行全部单元及 MCP HTTP 测试。
2. 向管理员确认 Exchange Build、EWS Endpoint、TLS 链、认证方式和 Impersonation Scope。
3. 在回环地址执行只读能力探测，记录实际 Build 和支持字段。
4. 使用专用测试邮箱验证列表、搜索、读取、附件元数据和未读状态不变。
5. 经人工批准后验证个人邮箱发送与原生 Reply。
6. 验证超级邮箱发送、ReplyAll 和管理员跨邮箱关联回复。
7. 核对 Sent Items、审计链和相同幂等键只产生一封邮件。

未经实际环境验证，不声明兼容某个 Exchange Build。实现按未知偏老版本设计：NTLM 默认、Autodiscover 关闭、字段按服务端实际版本判断、旧版无 text_body 时回退普通正文、线程头不支持时返回 THREAD_LINK_BEST_EFFORT。

只读探测不会发送或回复邮件，但会连接 EWS 并读取一个样本。只有人工确认后才运行：

$env:MAIL_MCP_EWS_PASSWORD = "<由受控 Secret 注入>"
.venv\Scripts\mail-mcp.exe ews-probe `
  --endpoint https://mail.company.com/EWS/Exchange.asmx `
  --username "DOMAIN\svc-mail" `
  --mailbox ews-test@company.com `
  --ca-bundle C:\mail-mcp\secrets\internal-ca.pem `
  --confirm-network-read-only

命令行不接受密码参数，避免凭据进入 shell 历史。Basic 还必须额外传入 --auth-type basic --allow-basic。

质量检查

.venv\Scripts\ruff.exe check src tests
.venv\Scripts\mypy.exe src
.venv\Scripts\python.exe -m pytest --cov=mail_mcp --cov-report=term-missing -q

真实 EWS 测试必须标记为 pytest.mark.ews；缺少真实环境时跳过，不等同于兼容性验证通过。