fmsg-mcp 是一个 MCP 服务器，为任意 AI 智能体提供独立的 fmsg 地址，使其能够通过已部署的 fmsg Web API 发送和接收联邦消息。它支持收件箱、会话线程、回复、表情回应、附件交换以及等待新消息等功能。
主要能力
- 为 AI 智能体分配 fmsg 地址，实现消息收发。
- 支持会话线程跟踪、回复、表情回应和附件交换。
- 提供等待新消息的功能，可保持请求打开最长 230 秒（由 FMSG_MCP_WAIT_MAX_SECONDS 控制）。
- 所有工具返回可读的 Markdown 和结构化内容（structuredContent）。
- 提供资源 fmsg://message/{id} 和 fmsg://thread/{id}，以及提示词 chat 和 reply。
- 支持通过 save_attachment 工具将附件直接保存到磁盘（需配置 FMSG_MCP_DOWNLOAD_DIR），避免文件字节进入模型上下文。
- 支持通过 get_attachment_download_url 获取远程附件的 HTTPS 下载链接。
- 对出站消息中的敏感信息（如 API 密钥、令牌等）进行选择性脱敏。
使用方式
连接方式
- OAuth：从 fmsg 托管提供商获取支持 OAuth 的 MCP URL，添加到 AI 宿主并登录。无需 API 密钥或本地安装。
- API 密钥：使用 fmsg 主机签发的 API 密钥（fmsgk_…）进行身份验证。可本地安装或通过 HTTP 使用。
本地安装（stdio）
- 需要 Node.js 22 或更高版本。
- 通过两个环境变量配置一个地址。
- 在 Claude Desktop、Cursor、VS Code 等宿主中添加服务器条目，配置文件位置不同（Claude Desktop: claude_desktop_config.json；Cursor: .cursor/mcp.json；VS Code: .vscode/mcp.json）。
远程模式（Streamable HTTP）
- 一个端点服务多个用户，每个客户端发送自己的 fmsg API 密钥作为 bearer 令牌。
- MCP 端点为 /mcp，/healthz 报告存活状态。
- 可配置 HTTP OAuth 实现浏览器登录，或使用 FMSG_MCP_AUTH_MODE=oauth+api-key 同时接受两种方式。
- 部署在 TLS 终止反向代理后，需设置 FMSG_MCP_ALLOWED_HOSTS 和 FMSG_MCP_ALLOWED_ORIGINS。
客户端库
- 可导入 { FmsgClient } from "@markmnl/fmsg-mcp/client" 复用 Web API 客户端。
- send() 方法在创建草稿前替换正文和主题中的凭证模式，返回替换计数和类型。
- 支持 TokenProvider 接口用于自定义授权集成。
适用场景
- 需要让 AI 智能体之间进行联邦消息通信的场景。
- 多智能体协作、自动化任务中需要消息传递和等待回复的场景。
- 需要交换文件附件但希望避免文件内容进入模型上下文的场景。
- 本地开发或远程共享部署的 AI 宿主环境。
限制
- 不内置托管提供商或身份提供商，需用户自行选择或自托管。
- 发送的消息无法编辑或撤回。
- 附件内联下载默认限制为 256 KiB，更大文件需使用 save_attachment 或 get_attachment_download_url。
- 远程文件下载需要 AI 宿主支持带认证的 HTTP 下载，普通浏览器点击会返回 401。
- 消息大小和接受策略由 fmsg 主机服务强制执行，MCP 仅转发操作并显示上游错误。
- 脱敏功能并非通用数据防泄漏或二进制附件扫描。
- 输出模式为开放和增量式，旧版本缓存的模式可能拒绝新字段，需重新添加连接器。
- 等待消息功能要求代理空闲超时至少 240 秒。
- 需要 Node.js 22 或更高版本。
