quario

@quario/mcp

让 Agent 将 JSON 数据转换为 PDF、Excel、Word、HTML 或 CSV 报告。 此 MCP 服务为 Claude 和其他 MCP 客户端提供两个工具。validate_report 用于检查报告定义，render_report 用于将其写入文件。一份定义可渲染为全部五种格式，Agent 获得的始终是文件路径，而非文件字节。

• 五种格式。 一份 JSON 定义可渲染为 pdf、xlsx、docx、html 和 csv。
• 可修复的错误。 每个问题都会指出其所在路径，例如 data: expected a JSONPath string。Agent 修复对应位置后再试一次。
• 返回文件，而非字节。 render_report 将文件写入磁盘，并返回路径和大小。无论报告多大，对 Agent 来说都只占一行上下文。
• 由宿主掌控。 查询预算、链接方案、数据根目录和输出目录均由启动配置指定。任何工具参数都无法更改这些设置。
• 不会覆盖文件。 如果名称已存在，会依次添加 -1、-2 等后缀。
• 本地运行。 服务通过 stdio 运行，执行 npx @quario/mcp 即可启动。

render_report 调用及其结果：

{
  "definition": {
    "data": "$.orders[*]",
    "detail": { "columns": [{ "header": "Total", "value": "{{ @.price * @.qty }}" }] }
  },
  "target": "pdf",
  "data": { "orders": [{ "price": 250, "qty": 2 }] },
  "filename": "orders"
}

工具会返回 Wrote orders.pdf (1.3 kB): /tmp/quario-mcp/orders.pdf。

此服务是开源的，但它运行的引擎不是。 此软件包采用 Apache-2.0 许可证。它会安装 quario 和五种渲染目标。这些软件包是依据 Quario License 提供的商业软件。可免费评估。未提供许可证密钥时，每次渲染都会带有未授权标记。

目录

• 开始使用
• 配置
• 信任边界
• validate_report
• render_report
• 此版本未包含的内容
• 开发
• 许可证

---

开始使用

1. 检查 Node。 此服务需要 Node 22 或更高版本。

node --version

2. 将服务添加到客户端。 此软件包包含引擎和五种渲染目标，因此无需安装其他内容。

Claude Code，无密钥评估：

claude mcp add quario -- npx -y @quario/mcp

Claude Code，使用许可证密钥：

claude mcp add quario -e QUARIO_LICENSE=quario_... -- npx -y @quario/mcp

Claude Desktop，在 claude_desktop_config.json 中配置：

{
  "mcpServers": {
    "quario": {
      "command": "npx",
      "args": ["-y", "@quario/mcp"],
      "env": { "QUARIO_LICENSE": "quario_..." }
    }
  }
}

若要在没有密钥的情况下评估，请省略 env 行。

3. 请求生成报告。 重启客户端，然后向 Agent 请求报告：

将这些订单渲染为 PDF，包含产品列和总价列：Desk，250，数量 2。

Agent 会返回所写文件的路径。除非 QUARIO_OUT_DIR 另有指定，否则文件会写入系统临时目录下的 quario-mcp 目录。

4. 允许 Agent 读取你的文件（可选）。 内联数据在任何情况下都可用。若要允许 Agent 通过 dataPath 传入 JSON 文件，请将 QUARIO_DATA_ROOT 设为该文件所在目录。Claude Code 会设置 CLAUDE_PROJECT_DIR；如果未设置 QUARIO_DATA_ROOT，服务会使用该变量。

---

配置

服务器从环境变量读取配置。没有标志，也没有配置文件。空变量视为未设置。

变量	设置	未设置时
QUARIO_LICENSE	许可证密钥	未授权，输出会带有标记
QUARIO_LOCALE	默认 locale	en-US
QUARIO_CURRENCY	默认 currency	无
QUARIO_TIME_ZONE	默认 timeZone	UTC
QUARIO_SCHEMES	href 方案，以逗号分隔	https:,mailto:
QUARIO_MAX_DEPTH	查询预算，或 Infinity	500
QUARIO_MAX_NODES	查询预算，或 Infinity	不限
QUARIO_MAX_RESULTS	查询预算，或 Infinity	不限
QUARIO_DATA_ROOT	dataPath 解析所在的目录	CLAUDE_PROJECT_DIR，否则 dataPath 失败
QUARIO_OUT_DIR	服务器写入的目录	系统临时目录下的 quario-mcp

服务器无法运行的值会导致服务器在启动时停止。 消息会输出到 stderr。这包括无法解析的预算、引擎拒绝的方案、不存在的数据根目录，以及服务器无法创建或写入的输出目录。许可证密钥验证失败是唯一的例外：服务器会启动，输出会带有标记。

信任边界

主机在环境中设置的配置属于主机。调用工具的 Agent 是作者，而引擎会将作者视为不可信。因此，没有任何工具参数会传递到主机设置：查询预算、href 方案、已注册函数、字体、许可证密钥、数据根目录和输出目录都只来自环境。

locale、currency、timeZone 和目标选项是例外。它们会改变报告的呈现方式，而不会改变服务器可以读取、运行或写入的内容，因此调用可以设置这些值。

---

validate_report

读取定义并检查问题，但不渲染定义。

字段	类型	说明
definition	对象	必填
targets	"html" | "pdf" | "xlsx" | "docx" | "csv" 数组	可选。针对每个目标检查 required

definition 字段包含报告文档的完整 JSON Schema，包括描述，因此 Agent 可以直接从工具本身了解文档的语义。服务器会根据该 Schema 检查封装对象，并将未经检查的定义交给引擎。引擎会在故障所在的路径上将其报告为一个问题，这比列出所有验证失败的子 Schema 更有助于 Agent。

问题属于成功结果，而不是错误。结果包含带有 { problems, warnings } 的 structuredContent，以及一个包含相同对象 JSON 文本的文本块。两份副本都完整，因为一个客户端会向模型提供结构化副本，另一个客户端则会提供文本。

• 问题的格式为 { path, source?, message, code?, start?, end? }。如果引擎有定位到的诊断信息，code、start 和 end 会取自该信息。
• 警告的格式为 { path, message }。

render_report

将定义渲染为一种目标格式，并将输出写入文件。

字段	类型	说明
definition	object	必填
target	"html" | "pdf" | "xlsx" | "docx" | "csv"	必填
data	any JSON value	data 和 dataPath 必须且只能提供其中一个
dataPath	string	数据根目录内的 JSON 文件
params	object	可选。定义中 params 的值
locale	string	可选。本次调用中覆盖 QUARIO_LOCALE
currency	string	可选。本次调用中覆盖 QUARIO_CURRENCY
timeZone	string	可选。本次调用中覆盖 QUARIO_TIME_ZONE
filename	string	可选。文件名（不含路径），见下文
options	object	可选。xlsx 的 page、meta 和 filter

该工具会根据目标格式规划定义，因此如果该目标不包含某项 required 声明，就会产生问题。存在问题的定义会返回与 validate_report 相同的 { problems, warnings }，并标记为 isError。

options 会传递给目标工厂。服务端会拒绝 fonts 和 paths。未知键会返回工厂自身的错误消息。csv 目标不接受任何选项。

渲染数据

• data 和 dataPath 必须且只能提供其中一个。两者都提供或都不提供都会报错。
• dataPath 会在数据根目录内解析。服务端会在解析符号链接后检查路径，因此链接无法指向根目录之外。没有数据根目录时，服务端会拒绝 dataPath。
• 文件内容必须是 JSON。无法解析的文件会返回服务端自身的错误消息，不会返回文件文本。
• 图像有两种形式。{ "$image": "assets/logo.png" } 指向数据根目录内的文件。{ "$base64": "<base64>" } 将字节以内联方式传递。优先使用 $image，因为 base64 图片会在每次调用时占用 Agent 的上下文。
• 仅含 $image 或 $base64 这一键的对象会在渲染前解码为字节。这适用于任意深度的数据，无论数据以内联方式提供还是存储在文件中。定义照常读取这些字节：=$.input.logo。
• $image 路径会相对于数据根目录解析，包括在 dataPath 文件内的路径。服务端会在解析符号链接后检查路径。文件必须是 PNG 或 JPEG。服务端不会读取其他文件。因此，数据文件引用无法将任意文件复制到文档中。没有数据根目录时，服务端会拒绝 $image。
• 无论数据引用同一文件多少次，服务端每次调用都只读取该文件一次。
• 拒绝操作时会返回错误，并指出该路径在数据中的位置，例如 $.input.logo。这适用于非 base64 字符串，以及不存在、指向根目录之外或并非图像的 $image。

输出文件

每种目标格式都会写入文件并返回其位置，绝不会返回文件内容。

• 文件会写入 QUARIO_OUT_DIR。
• filename 是文件名，不含分隔符，且不能是 ..。服务端会强制使用目标格式的扩展名。未提供 filename 时，文件名为 report-<timestamp>.<ext>。
• 服务端绝不会覆盖已有文件。若文件名已存在，会依次添加 -1、-2 等后缀。
• 结果包含 structuredContent，内容为 { path, target, bytes }，以及文本 Wrote <name> (<size>): <absolute path>。

---

此版本未包含

已注册函数、主机字体和远程传输。

---

开发

npm run check 是本地检查关卡。它会运行格式检查、lint、死代码检查、大小预算检查、单元测试和类型测试套件，以及复杂度检查。CI 会运行同一关卡。本地 check 通过，就意味着拉取请求也会通过。

AGENTS.md 记录了此代码库的约定。docs/adr 记录了读者最容易撤销的决策。

---

许可证

版权所有 2026 Robin van der Vleuten

依据 Apache License, Version 2.0（“许可证”）授权； 除非遵守许可证，否则不得使用此文件。 您可以通过以下地址获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则按“原样”提供软件， 不附带任何明示或暗示的保证或条件。 有关许可证规定的权限和限制，请参阅许可证。

此服务安装的 quario 和 @quario/* 软件包有各自的许可证。请参阅这些软件包各自的 LICENSE 文件。