Reportflow Mcp

Re:port Flow MCP

官方显示名称：Re:port Flow MCP。软件包和实现标识符：reportflow-mcp。旧版搜索别名：ReportFlow MCP Server 和 ReportFlow。

概述

一个 MCP（模型上下文协议）服务，可将你的 Re:port Flow 模板转换为 PDF 报告——发票、合同、对账单，以及你设计的任何内容——直接通过 Claude 或其他兼容 MCP 的 AI Agent 生成。

功能

• 根据自然语言请求生成 PDF，例如 “为 Acme Corp 创建一张总额为 $300 的发票”
• 将你的 Re:port Flow 设计及其参数架构直接作为 MCP 资源提供给 AI
• 批量生成多个 PDF，并将其下载为单个 ZIP 文件
• 将输出保存到用户当前所在的工作区文件夹（支持 Claude Desktop / Claude Code / Cursor / VS Code）

Agent 技能

需要遵循操作流程（而不只是读取协议）的 Agent 应使用 skills/re-port-flow/SKILL.md。将该 目录复制到 Claude Code / Codex 的 .agents/skills 或 Cursor 项目技能 文件夹。PDF 始终通过 https://mcp.re-port-flow.com/mcp 生成。 Hugging Face Space MCP（组织卡片） 仅用于展示——请通过 Space 的 MCP 徽章 → Add to MCP tools 添加， 不要将其用作产品端点的替代品。

设置

Re:port Flow MCP 有两种运行方式——选择适合你的客户端的方式。

远程服务（claude.ai / Web 客户端）——Streamable HTTP

将 Re:port Flow 添加为指向托管端点的自定义连接器：

https://mcp.re-port-flow.com/mcp

在 Claude（claude.ai）中，前往 Settings → Connectors → Add custom connector 并粘贴上方的 URL。身份验证通过应用内 OAuth 处理（参见 身份验证）——无需在本地安装任何内容。

本地服务（Claude Desktop / Claude Code / Cursor）——通过 npx 使用 stdio

将以下内容添加到你的配置文件（.mcp.json、claude_desktop_config.json、~/.cursor/mcp.json 等）：

{
  "mcpServers": {
    "reportflow": {
      "command": "npx",
      "args": ["-y", "reportflow-mcp"]
    }
  }
}

设置就这些。无需环境变量、API 密钥或管理密钥。

VS Code（支持 MCP 的版本）

在 .vscode/mcp.json 中使用相同的 JSON。

要求

• 远程：支持自定义 HTTP 连接器的 MCP 客户端（例如 claude.ai）。无需本地安装。
• 本地（stdio）：22.x 系列中的 Node.js 22.23.4 或更高版本（engines: ^22.23.4），且首次登录时需要有可用的浏览器。请单独安装已修补的 Node.js；npx 会下载 MCP 软件包。最低补丁要求包含 2026-10-21 的 Node.js 安全修复。
• 一个 Re:port Flow 账户（两种方式均需要）。

支持的协议修订版本

两种传输方式（stdio / Streamable HTTP）都通过同一个端点提供两代 MCP 协议：

• 2026-07-28（当前版本）——无状态的逐请求协议。现代客户端通过 server/discover 发现该协议；无需会话标头，请求会在 _meta 中携带协议版本。
• 2025 年版本（2025-11-25、2025-06-18、2025-03-26、2024-11-05、2024-10-07）——经典的 initialize 握手，保留以兼容现有客户端（Claude Desktop、claude.ai 自定义连接器、Cursor、ChatGPT、n8n，等等）。

两种传输方式都会自动选择版本：现代客户端通过 server/discover 探测，旧版客户端继续发送 initialize——两端都无需配置，现有连接也会照常工作。

任一握手还会返回 MCP instructions：一段简短说明，介绍 Re:port Flow 的功能，以及如何获取第一个 PDF（搜索图库 → 复制 → 设置参数 → 生成），让连接后即可主动提出创建文档，而不是等待用户提出请求。客户端会在多大程度上遵循这些说明，由客户端自行决定。

A2A（Agent2Agent）

远程服务还通过 JSON-RPC 绑定支持 A2A v1.0：

• Agent Card：https://mcp.re-port-flow.com/.well-known/agent-card.json
• 端点：POST https://mcp.re-port-flow.com/a2a（SendMessage）

每项 A2A 技能都对应上述某个 MCP 工具（技能 ID 就是工具名称）。发送一条包含数据部分 {"skill": "<tool name>", "arguments": {...}} 的消息；参数需符合该工具的输入架构，调用会使用与 MCP 相同的授权和工作区权限。使用相同的 OAuth 流程进行授权（MCP 访问令牌可直接使用）。不支持流式传输、推送通知和任务检索：每次 SendMessage 都会返回已完成的任务。

身份验证

远程（claude.ai）

添加连接器时，Claude 会为你运行 OAuth 流程：登录 → 选择工作区 → 同意。令牌由客户端持有——无需管理本地钥匙串或浏览器步骤。

本地（stdio）

重新加载 MCP 客户端后，向 AI 提出请求：

使用 Re:port Flow 进行身份验证

浏览器窗口将会打开。登录 → 选择工作区 → 同意，即可完成。令牌会存储在你的操作系统钥匙串中（macOS Keychain / Windows Credential Manager / Linux libsecret）；如果不可用，则回退到 chmod-0600 文件，并会自动刷新令牌。

使用示例

以下示例均为可直接粘贴的提示词；AI 会选择合适的工具。

1. 生成单个 PDF（列表 → 架构 → 生成）

使用发票模板，为 Acme Corp 创建一份总额为 $330 的 PDF。

AI 会使用 list_templates 列出设计，通过 get_design_parameters 获取参数架构，填入数值，然后调用 generate_pdf_sync。

• 远程：返回 fileUrl——Re:port Flow Web 应用的输出历史记录页面（需要登录）。这不是直接下载文件的链接。
• 同步生成会在 60 秒后超时（API 返回 504）；对于可能需要更长时间的任务，请使用 generate_pdfs_async。
• 本地：也会保存文件并返回其绝对路径。

2. 批量生成多个 PDF

使用对账单模板，为每位客户生成一份 PDF （Acme $100、Globex $250、Initech $80），并将它们一起发给我。

• 本地（stdio）：generate_pdfs_sync 会将所有文件写入一个 ZIP 文件，保存到你的工作区。
• 远程：generate_pdfs_async 会运行批量任务，并返回请求 ID 和输出历史记录页面 URL（url）。get_generation_status 会告知你批量任务何时完成或失败。

3. 异步生成，然后下载（本地）

在后台启动合同 PDF 的生成，完成后再下载。

AI 会调用 generate_pdf_async（立即返回 requestId），使用 get_generation_status 检查进度，然后调用 download_file 保存生成完成的 PDF。批量处理对应的工具是 generate_pdfs_async → download_zip。如果文件仍在生成时尝试下载，工具会返回 FILE_NOT_READY，并告知需要等待的秒数，而不是直接失败。这些下载工具仅支持 stdio；在远程服务上，同步/异步工具会改为返回输出历史页面 URL。

requestId、fileId 和 designId 是较短的字母数字字符串（例如 0eUDdgAjNXrrItA2），不是 UUID。

**提示 — 自然语言参数：**在支持 Sampling 的客户端上，你可以询问 “为 A社 的 $1,000 发票起草参数”，AI 会调用 suggest_params，将需求转换为有效的 params 对象，然后再生成。

4. 从零开始创建模板（图库 → 复制 → 生成）

我还没有任何模板——为 Acme Corp 创建一份发票 PDF。

当 list_templates 返回空结果时，AI 会使用 search_gallery_templates 搜索公开模板图库，向你展示候选项，将你选中的模板通过 copy_gallery_template 复制到你的工作区，然后继续正常流程（get_design_parameters → generate_pdf_sync）。模板始终会复制到你在 OAuth 授权页面上选择的工作区——AI 无法指定其他工作区。

如果搜索没有结果，返回内容会附带一个指向模板图库网站的 templateSite 链接，你可以在那里浏览设计。分享你喜欢的页面 URL（/templates/{slug}），AI 就会根据该 slug 复制模板。

斜杠命令

命令	用途
/generate_pdf	单个 PDF 的分步操作指南
/generate_pdfs	批量生成 PDF 的操作指南
/reportflow_help	快速了解功能

文件保存位置（本地模式）

输出位置按以下顺序确定：

1. 用户的明确指示（例如 “保存到我的桌面”）
2. 当前打开的工作区根目录（Claude Code / Cursor / VS Code）
3. 回退到操作系统临时目录

构建自己的 Agent

上述设置假设 MCP 客户端会自行管理连接和登录。如果你要自己编写 Agent——使用 Hugging Face Agents、自定义工具循环或原始 HTTP——可以直接访问托管端点：

https://mcp.re-port-flow.com/mcp

• agents.md — 面向 Agent 的指南：传输详情、十个 HTTP 工具、OAuth 流程、模型选择，以及 Agent 必须遵守的规则（绝不编造业务数据；copy_gallery_template 不具备幂等性；passthrough 值会写入 PDF 的元数据）。
• examples/ — 可运行的 Python、JavaScript 和 curl 客户端，以及一个用于完成 OAuth 流程并打印访问令牌的脚本。

无需凭据即可使用 initialize 和 tools/list，因此你可以先发现工具集，再接入身份验证。每次 tools/call 都需要 Bearer 令牌。

Hugging Face

Re:port Flow 已发布在 Hub 上，地址为 huggingface.co/reportflow。Hugging Face SDK 没有自己的 MCP OAuth 流程，因此请使用 examples/oauth/get-token.sh 获取一次令牌，并将其注入 Authorization 标头——参见 examples/python/hf_mcp_client.py 和 examples/javascript/hf-mcp-client.mjs。

参考

工具（由 AI 调用）

工具	用途
authenticate	首次认证／重新认证
list_templates	列出可用设计
get_design_parameters	获取设计的参数架构
generate_pdf_sync / _async	生成单个 PDF（同步调用返回路径；异步调用返回请求 ID）
generate_pdfs_sync / _async	生成多个 PDF（返回 ZIP 文件）
get_generation_status	检查异步请求（requestId）：processing / completed / failed，并提供失败的 code 和 message
download_file / download_zip	下载异步工具生成的文件（仅限 stdio）。文件仍在生成时，返回 FILE_NOT_READY 和需要等待的秒数
suggest_params	通过 MCP Sampling 将自然语言需求转换为 params JSON（需要支持 Sampling 的客户端）
search / fetch	ChatGPT 连接器约定工具（单个字符串参数），封闭范围（openWorldHint: false）——只读取你自己工作区的内部模板目录，不访问网络。search 按名称查找模板；fetch 按 ID 返回模板的参数架构。这些轻量封装基于 list_templates / get_design_parameters，使 ChatGPT（包括未启用 Developer Mode 的 Plus/Pro 用户）能够发现并查看模板。
search_gallery_templates	按关键词／类别搜索公开模板库（无需认证）。返回尚未添加到你工作区的候选模板——复制之前，不能使用它们的 slug 生成 PDF。
get_gallery_template	获取某个公开模板库模板的完整详情（通过 slug，无需认证）
copy_gallery_template	写入工具。 将模板复制到你已授权的工作区（目标工作区由访问令牌固定，不能作为参数传入）。返回可用于 get_design_parameters / generate_pdf_sync 的 designId + version。每次调用都会创建一个新设计，不会复用先前的副本。

资源（可附加为 AI 上下文）

URI	内容
reportflow://designs	可用设计列表
reportflow://designs/{designId}/parameters	单个设计的参数架构
reportflow://errors	Content Service 错误消息目录
reportflow://server-info	服务功能概览

提示词（斜杠命令操作指南）

/generate_pdf、/generate_pdfs、/reportflow_help——传入参数后，AI 会按照预设工作流执行。

故障排除

现象	解决方法
错误中包含 re-authentication required	请求 AI：“使用 Re:port Flow 重新认证”
npx 找不到软件包	运行 npm cache clean --force，然后重试
Linux 上没有可用的密钥链	自动回退到 $XDG_STATE_HOME/reportflow-mcp/ 下权限为 chmod-0600 的文件
通过 SSH／远程 Shell 无法打开浏览器	在本地机器上认证一次；之后，缓存的令牌可在远程主机上使用

隐私

Re:port Flow MCP 是一个轻量客户端：它将你的请求转发到你自己的 Re:port Flow 账户，并返回生成的 PDF。它不会向第三方出售或分享 你的数据。认证令牌存储在本地（操作系统密钥链，或回退使用 chmod-0600 文件）， 且只会发送给 Re:port Flow 自己的服务——在 OAuth 登录期间， 以及作为每次已认证 API 调用中的 Bearer 凭据（列出模板、生成或下载 PDF）。 这些令牌绝不会与任何第三方分享。

完整隐私政策——包括收集哪些信息、保留多久以及如何处理——请参阅：lp.re-port-flow.com

安全性

托管端点会验证 Host 标头（防范 DNS 重绑定），并根据 MCP Streamable HTTP 规范的安全要求，使用 403 Forbidden 拒绝结构无效的 Origin 标头。身份验证仅使用 Bearer 令牌——不使用 Cookie，且 CORS 从不允许携带凭据。完整的策略及其威胁模型详见 docs/security.md（日语）。

支持

需要帮助、发现了 Bug，或对目录审核有疑问？

• Re:port Flow（隐私与支持）：https://lp.re-port-flow.com
• GitHub Issues：https://github.com/re-port-flow/reportflow-mcp/issues

许可证

MIT——请参阅 LICENSE。

链接

• Re:port Flow：https://re-port-flow.com
• 隐私与支持：https://lp.re-port-flow.com
• npm：https://www.npmjs.com/package/reportflow-mcp
• Hugging Face：https://huggingface.co/reportflow
• Agent 指南：agents.md
• 示例：examples/
• Issues：https://github.com/re-port-flow/reportflow-mcp/issues