Skip to content
MailAgent

MCP 接入与 skill pack

This content is not available in your language yet.

如果你的 agent 跑在 MCP 客户端里（Claude Desktop / Claude Code / 任意 MCP host），不用裸调 REST —— MailAgent 提供一个 MCP stdio server mailagent-mcp，把 Skill manifest 里 mcp_exposed=true 的工具自动暴露成 MCP tools。

mailagent-mcp（MCP stdio server）

Section titled “mailagent-mcp（MCP stdio server）”

mailagent-mcp 是个 console script（pip install -e ".[cli,dev]" 后可用），跑 MCP stdio JSON-RPC（initialize / tools/list / tools/call）。它不自己实现业务，只把请求经 Bearer key 转发给 serve-api 的 /api/skills/invoke。

工具从 manifest 的 mcp_exposed 字段生成，命名 mailagent_<skill>_<tool>（如 mailagent_search_email_search）。

两个环境变量

Section titled “两个环境变量”
变量作用默认
MAILAGENT_API_BASEserve-api 地址本机 http://127.0.0.1:8200
MAILAGENT_AGENT_KEYscoped Bearer key（mak_…）无（必填）

远程打 https://mail.chenge.ink。手动起一次验证：

Terminal window
MAILAGENT_API_BASE=http://127.0.0.1:8200 \
MAILAGENT_AGENT_KEY=mak_… \
  mailagent-mcp

它会等 MCP 客户端经 stdin 发 JSON-RPC —— 正常情况由客户端拉起，不用手动跑，这步只是确认 console script 在 PATH 里。

Claude Desktop / Claude Code 配置

Section titled “Claude Desktop / Claude Code 配置”

MCP 客户端用一段 JSON 声明怎么拉起 server。把 mailagent-mcp 配成一个 stdio MCP server：

{
  "mcpServers": {
    "mailagent": {
      "command": "mailagent-mcp",
      "env": {
        "MAILAGENT_API_BASE": "http://127.0.0.1:8200",
        "MAILAGENT_AGENT_KEY": "mak_…"
      }
    }
  }
}
  • Claude Desktop：写进 claude_desktop_config.json 的 mcpServers。
  • Claude Code：等价的 MCP server 注册。
  • command 若不在 PATH，用绝对路径 ./venv/bin/mailagent-mcp。

这份 JSON 不用手写 —— skill pack 直接导出一份现成的（见下）。

skill pack：一键导出 + 自检

Section titled “skill pack：一键导出 + 自检”

scripts/export_skill_pack.py 把对外交付面打成一个目录，给你现成的客户端配置 + 文档 + 自检脚本：

Terminal window
python scripts/export_skill_pack.py     # → dist/mailagent-skill-pack/（gitignored）

产物：

文件内容
README接入说明
mcp-config.example.json上面那段 MCP 配置的现成模板
manifest.json完整 Skill manifest
openapi.jsonREST 端点的 OpenAPI 描述
selftest.sh安全自检脚本
skills/<skill>/SKILL.md5 个 skill 各一份说明

自检

Section titled “自检”

selftest.sh 只跑安全动作（health / manifest / search / report_list；report.run 为 opt-in），不碰写 / 发：

Terminal window
MAILAGENT_API_BASE=http://127.0.0.1:8200 \
MAILAGENT_AGENT_KEY=mak_… \
  bash dist/mailagent-skill-pack/selftest.sh

它验证：key 有效（非 403）→ manifest 能取（按 scope 过滤）→ 一个只读 tool 能跑通。接进 MCP 客户端前先跑它，能在客户端层之外把鉴权 + 连通性问题先排掉。

与 CLI-as-MCP 的区别

Section titled “与 CLI-as-MCP 的区别”

深入了解

Section titled “深入了解”