内容
# reportflow-mcp
[](https://www.npmjs.com/package/reportflow-mcp)
[](https://opensource.org/licenses/MIT)
[](https://smithery.ai/servers/re-port-flow/reportflow-mcp)
一个 MCP（模型上下文协议）服务器，可以将您的 [ReportFlow](https://re-port-flow.com) 模板转换为 PDF 报告 — 发票、合同、报表、您设计的所有内容 — 直接从 Claude、Cursor、VS Code 或任何其他与 MCP 兼容的 AI 代理。
- **托管远程端点**：`https://mcp.re-port-flow.com/mcp` — 无需 npm 和 Node.js 即可从 Claude.ai（网页）工作
- **npm 包**：[`reportflow-mcp`](https://www.npmjs.com/package/reportflow-mcp) — 用于 Claude Desktop / Claude Code / Cursor / VS Code 的本地 stdio 备用方案
- **源代码**：[github.com/re-port-flow/reportflow-mcp](https://github.com/re-port-flow/reportflow-mcp)
- **MCP 注册表**：[`io.github.re-port-flow/reportflow-mcp`](https://registry.modelcontextprotocol.io/v0/servers?search=reportflow)
- **Smithery**：[smithery.ai/servers/re-port-flow/reportflow-mcp](https://smithery.ai/servers/re-port-flow/reportflow-mcp)
## 为什么选择 ReportFlow MCP
多个 MCP 服务器存在于业务文档生成。ReportFlow MCP 在三个方面有所不同。
1. **远程就绪，无需设置** — `https://mcp.re-port-flow.com/mcp` 的托管端点让您可以从 Claude.ai（网页）连接，无需安装 npm 或 Node.js。与其他日式账票（chohyo）MCP 服务器不同，它们仅作为 stdio 形式的本地进程提供，而业务用户无需开发环境即可在第一天开始使用。
2. **无代码模板设计 + 模板市场** — 模板在基于浏览器的图形用户界面编辑器（基于 Konva）中设计，无需代码。免费的 [模板库](https://templates.re-port-flow.com) 涵盖发票、报价、收据、交货单、报告等，因此 AI 代理可以从第一天起调用预制的模板。您无需创建 JSON 模式即可添加模板。
3. **OAuth 2.0 + 动态客户端注册** — 身份验证为 OAuth 2.0（授权码 + PKCE），具有动态客户端注册 — 永远不会向 AI 客户端提供 API 密钥。安全态势与 Claude.ai 的第一方连接器相匹配。
## 功能
- 根据自然语言请求生成 PDF，例如 *"为 Acme Corp 创建一张总额为 330 美元的发票"*
- 将您的 ReportFlow 设计及其参数模式作为 MCP **资源** 公开，以便 AI 可以将它们附加为上下文
- 批量生成多个 PDF 并将它们下载为单个 ZIP 文件
- 将输出保存到 AI 客户端的工作区文件夹（仅限 stdio 模式 — 远程模式返回下载 URL）
## 设置
有两种连接方式。**远程（HTTP）** 是推荐的，因为它适用于 Claude.ai（网页）并且无需安装步骤。如果您特别希望将生成的 PDF 保存到本地工作区文件夹，或者需要在没有托管端点的情况下运行，请使用 **本地（stdio）**。
### 远程（HTTP）— 推荐
无需 npm，无需 Node.js。MCP 客户端在首次连接时打开浏览器进行 OAuth，令牌由服务器端管理。
#### Claude Desktop / Claude Code / Cursor
添加到 `.mcp.json` / `claude_desktop_config.json` / `~/.cursor/mcp.json`：
```json
{
"mcpServers": {
"reportflow": {
"type": "http",
"url": "https://mcp.re-port-flow.com/mcp"
}
}
}
```
#### VS Code（启用 MCP 的版本）
VS Code 在顶级使用 `servers` 而不是 `mcpServers`。添加到 `.vscode/mcp.json`：
```json
{
"servers": {
"reportflow": {
"type": "http",
"url": "https://mcp.re-port-flow.com/mcp"
}
}
}
```
#### Claude Code CLI（一行命令）
```bash
claude mcp add --transport http reportflow https://mcp.re-port-flow.com/mcp
```
#### Claude.ai（网页）
设置 → **连接器** → **添加自定义连接器** → 粘贴 `https://mcp.re-port-flow.com/mcp`。浏览器在第一次使用时打开 OAuth 同意屏幕。
### 本地（stdio）
当您希望将生成的 PDF 保存到 AI 客户端的本地工作区文件夹时，或者当您需要脱机友好型分发时，请使用此方法。需要 Node.js 18+（由 `npx` 自动获取）和本地浏览器进行首次运行的 OAuth。
#### Claude Desktop / Claude Code / Cursor
```json
{
"mcpServers": {
"reportflow": {
"command": "npx",
"args": ["-y", "reportflow-mcp"]
}
}
}
```
#### VS Code
```json
{
"servers": {
"reportflow": {
"command": "npx",
"args": ["-y", "reportflow-mcp"]
}
}
}
```
### 要求
- **远程**：具有 MCP 功能的 AI 客户端（Claude.ai 网页版，Claude Desktop，Cursor，VS Code）+ [ReportFlow](https://re-port-flow.com) 账户。就是这样。
- **本地**：Node.js 18+（由 `npx` 自动获取）+ 具有本地环境的浏览器，用于首次运行的 OAuth + [ReportFlow](https://re-port-flow.com) 账户。
## 用法
### 首次身份验证
重新加载客户端后，询问 AI：
> 使用 ReportFlow 进行身份验证
在远程模式下，浏览器在连接时立即打开。在 stdio 模式下，AI 按需触发 OAuth 流程。登录 → 选择工作区 → 同意，您就完成了。
- **远程**：令牌由服务器端管理和刷新。
- **本地**：令牌存储在 OS 密钥链（macOS 密钥链 / Windows 凭证管理器 / Linux libsecret）中，如果 libsecret 无法使用，则在 `$XDG_STATE_HOME/reportflow-mcp/` 下使用 chmod-0600 文件作为备用方案。
### 生成 PDF
#### 自然语言（最简单）
> 使用发票模板，为 Acme Corp 创建一张总额为 330 美元的 PDF。
AI 将通过 `list_templates` 查找模板，通过 `get_design_parameters` 获取其参数模式，填写值，然后调用 `generate_pdf_sync` — 返回本地文件路径（stdio）或下载 URL（远程）。
#### 斜杠命令
| 命令 | 目的 |
|---|---|
| `/generate_pdf` | 单个 PDF 的逐步配方 |
| `/generate_pdfs` | 批量生成 PDF 的配方 |
| `/reportflow_help` | 快速功能介绍 |
### 文件保存位置
**stdio 模式**，按顺序：
1. 显式用户指令（例如 *"保存到我的桌面"*）
2. 当前打开的工作区根目录（通过 MCP 根目录的 Claude Code / Cursor / VS Code）
3. 作为备用方案的 OS 临时目录
**远程模式**：工具结果包含下载 URL（`fileUrl`）— MCP 客户端无法直接写入您的文件系统。
## 参考
### 工具（由 AI 调用）
每个工具现在都带有 [MCP `ToolAnnotations`](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations) — 一个人类可读的 `title` 加上 `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint` 标志 — 因此具有 MCP 功能的客户端可以渲染有意义的工具名称并路由正确的批准提示。
| 工具 | 标题 | 目的 | 注释 |
|---|---|---|---|
| `authenticate` | 使用 ReportFlow 进行身份验证 | 首次/重新身份验证（打开浏览器） | `openWorldHint: true` |
| `list_templates` | 列出 ReportFlow 模板 | 列出可用设计 | `readOnlyHint: true`，`idempotentHint: true` |
| `get_design_parameters` | 获取模板参数 | 一个设计的 参数模式 | `readOnlyHint: true`，`idempotentHint: true` |
| `generate_pdf_sync` / `_async` | 生成 PDF（同步/异步） | 生成一个 PDF | 非只读，非破坏性 |
| `generate_pdfs_sync` / `_async` | 生成多个 PDF（同步/异步） | 批量生成 PDF，返回 ZIP | 非只读，非破坏性 |
| `download_file`（仅限stdio） | 下载生成的 文件 | 将异步生成的 PDF 保存到磁盘 | `idempotentHint: true` |
| `download_zip`（仅限stdio） | 下载批量 ZIP | 将批量 ZIP 保存到磁盘 | `idempotentHint: true` |
| `suggest_params` | 通过采样建议参数 | 将自然语言简报转换为 `params` JSON（支持采样的客户端） | `readOnlyHint: true` |
在远程（HTTP）模式下，写入文件的工具（`download_file`，`download_zip`，stdio 绑定的 `generate_pdf_sync`）被隐藏 — 远程端点无法访问您的本地磁盘。
### 资源（可作为 AI 上下文附件）
| URI | 内容 |
|---|---|
| `reportflow://designs` | 可用设计列表 |
| `reportflow://designs/{designId}/parameters` | 一个设计的 参数模式 |
| `reportflow://errors` | 来自内容服务的错误消息目录 |
| `reportflow://server-info` | 服务器功能概述和版本 |
### 提示（斜杠命令配方卡）
`/generate_pdf`，`/generate_pdfs`，`/reportflow_help` — 传递参数，AI 遵循预备的工作流程。
## 故障排除
| 症状 | 修复方法 |
|---|---|
| 包含 `需要重新身份验证` 的错误 | 询问 AI：*"使用 ReportFlow 重新身份验证"* |
| `npx` 无法找到包（stdio） | `npm cache clean --force` 然后重试 |
| Linux 上无密钥链（stdio） | 自动备用到 `$XDG_STATE_HOME/reportflow-mcp/` 下的 chmod-0600 文件 |
| 无法通过 SSH / 远程 shell 打开浏览器（stdio） | **在本地计算机上** 进行身份验证；之后缓存的令牌在远程主机上有效 |
| `Rate limit exceeded`（429） | 按工作区限流。等待 `Retry-After` 头中报告的秒数后重试。优先使用异步端点进行批量作业。 |
## 许可证
MIT — 请参阅 [LICENSE](./LICENSE)。
## 链接
- ReportFlow：https://re-port-flow.com
- 官方文档：https://doc.re-port-flow.com/docs/integrations/mcp
- 模板库：https://templates.re-port-flow.com
- npm：https://www.npmjs.com/package/reportflow-mcp
- 问题：https://github.com/re-port-flow/reportflow-mcp/issues
