Talonic

@talonic/mcp

Talonic 官方 MCP 服务。 通过模型上下文协议，让任何 AI Agent 都能从任何文档中提取经过架构验证的结构化数据，包括 PDF、扫描件、发票、合同和表单。

状态： 稳定，已列入官方 MCP Registry，标识为 io.github.talonicdev/talonic-mcp。共有 36 个公开工具和 2 个资源，其中包括 7 个用于 External 模式 Talonic Apps 的决策任务工具（尚未通过生产环境验证，运行在平台的 decide 层级——需要具有单个应用 decide 授权的 tlnc_ 密钥，或具有 apps:decide 作用域且角色为 senior_member 或更高的 OAuth 会话）；其余工具均已通过生产环境端到端验证（包括 Claude.ai 托管连接器），每个工具都会渲染自己的 ChatGPT Apps SDK 小组件卡片。可作为本地 stdio 进程运行，供桌面端/IDE 客户端使用；也可作为托管式 Streamable HTTP 服务运行在 mcp.talonic.com，供 Claude.ai 连接器使用。

你将获得什么

一次安装，即可让 Agent 使用完整的文档提取工作流：

• talonic://schemas — 已保存的架构列表。
• talonic://webhooks/reference — webhook 事件类型、投递语义、签名验证和重试策略。

每个工具的描述都面向大模型编写，并明确说明 何时使用 / 何时不要使用，让 Agent 无需额外提示即可选对工具。

为什么使用它

当 Agent 需要从 PDF、扫描件或格式混乱的文档中提取结构化数据时，常见做法是先进行原始 OCR，再调用大模型——但结果往往不稳定：表格会变得乱七八糟，日期会被误读，总计金额也会出错。talonic_extract 则会返回经过架构验证的 JSON，其中包含每个字段的置信度评分、检测到的文档类型，以及用于后续调用的稳定 ID。完整流程（上传 → OCR → 提取 → 验证）会在服务端通过一次请求运行。

快速开始

1. 获取 API 密钥（30 秒）

每位用户都会使用各自独立的 Talonic 工作区——你的文档和架构只有你自己可以访问。

1. 在 app.talonic.com 注册——免费套餐每天可提取 50 次，无需信用卡。
2. 进入 Settings → API Keys → Create New Key。
3. 将 tlnc_… 值复制到 MCP 客户端配置中（见下方示例）。

Claude.ai 无需 API 密钥。托管连接器使用 OAuth——Claude.ai 通过 PKCE 处理身份验证，并存储自己的短期令牌。API 密钥仅适用于本地 stdio 安装（Claude Desktop、Cursor、Cline、Continue、Cowork）以及 API 密钥 URL 回退方式。

2. 安装

所有本地客户端都以相同方式启动服务——在 env 代码块中填写密钥，运行一行 npx 命令即可。无需克隆或构建：

{
  "command": "npx",
  "args": ["-y", "@talonic/mcp@latest"],
  "env": { "TALONIC_API_KEY": "tlnc_..." }
}

**固定版本。**试用时使用 @latest 即可。对于生产环境和 CI，请固定版本（例如 @talonic/[email protected]），以免某个版本悄然更改 Agent 所依赖的工具描述、验证规则或响应结构。审阅 CHANGELOG 后再更新固定版本。

客户端配置

{
  "mcpServers": {
    "talonic": {
      "command": "npx",
      "args": ["-y", "@talonic/mcp@latest"],
      "env": { "TALONIC_API_KEY": "tlnc_your_key_here" }
    }
  }
}

{
  "mcpServers": {
    "talonic": {
      "command": "npx",
      "args": ["-y", "@talonic/mcp@latest"],
      "env": { "TALONIC_API_KEY": "tlnc_your_key_here" }
    }
  }
}

{
  "name": "talonic",
  "command": "npx",
  "args": ["-y", "@talonic/mcp@latest"],
  "env": { "TALONIC_API_KEY": "tlnc_your_key_here" }
}

Claude.ai 的“Add custom connector”流程使用远程 MCP URL，而不是本地进程。我们在 mcp.talonic.com 上托管了一个。推荐使用 OAuth——配置中无需 API 密钥。

推荐方式——OAuth（无需 API 密钥）：

1. 打开 claude.ai/settings/connectors → Add custom connector。
2. URL：https://mcp.talonic.com/mcp（不带查询字符串和请求头）。
3. 点击 Connect → 系统会将你重定向至 Talonic → 登录（Google、Microsoft 或 SSO）。
4. 批准授权页面（权限范围：extract:write、documents:read、schemas:read，以及决策任务工具所需的 apps:decide）。在 apps:decide 推出前添加的连接器仍可正常使用；七个决策工具会显示为不可调用，除非你移除并重新添加连接器。如果你有多个工作区，请选择一个。
5. 你会返回 Claude.ai。所有三十六个公开工具都会显示。

此流程使用 PKCE（RFC 7636）和动态客户端注册（RFC 7591）。Claude.ai 会存储有效期为 1 小时的访问令牌和有效期为 30 天的刷新令牌，并自动刷新。API 密钥不会出现在连接器配置或任何 URL 中。移除连接器或在 Talonic 控制面板中撤销 OAuth 客户端，即可撤销授权。

替代方式——在 URL 中使用 API 密钥（适用于防火墙环境、自动化或静态凭据）：

https://mcp.talonic.com/mcp?apiKey=tlnc_your_key_here

权衡：密钥会保存在 Claude.ai 的连接器存储中，也可能出现在 Anthropic 侧的日志中。如果你移除或共享连接器，请轮换密钥。

要在 Claude.ai 中上传文件？ 请使用 talonic_request_upload——详见下一节。通过托管连接器，直接将实际文件拖入聊天不起作用（这是平台限制，详见下文）。

文件上传：浏览器交接流程

这是在托管连接器（Claude.ai 网页版、ChatGPT）中运行 Talonic 时最重要的一点。

限制

托管 AI 平台会限制单次工具调用参数的大小。在 Claude.ai 上，实际有效上限约为 32 KB 的解码后载荷（约 43 KB 的 base64）——这是直接在生产环境中测得的。实际 PDF 通常有数百 KB 到数 MB，因此以 base64 file_data 传递会被静默截断：服务器会收到格式正常但不完整的文件前缀，API 会登记一个占位文档，提取结果则返回 null 字段。Agent 不会察觉到截断。此外，Agent 的沙箱也无法通过带外方式上传字节——出口流量采用允许列表控制，因此直接向存储发送 PUT 请求会被拦截。

这些是托管式／沙箱化 Agent 平台有意设置的结构性限制，不是 Talonic 的漏洞，也无法通过配置消除。ChatGPT 连接器和类似界面也有相同限制。

解决方案：talonic_request_upload

将文件传输交给用户自己的浏览器，它既不受工具调用大小限制，也不受出口流量允许列表限制：

1. Agent calls  talonic_request_upload(filename)
       → { document_id, upload_url: "https://app.talonic.com/u/<token>", expires_at }
2. Agent shows the upload_url to the user.
3. User opens it in a browser tab and drops the file.
4. Agent polls  talonic_get_document(document_id)  until status === "completed".
5. Agent calls  talonic_extract(document_id, schema)  — structured data comes back.

用户只需点击一次。这与 Slack／Stripe 的“在浏览器中打开”链接采用相同模式，并且适用于所有托管 Agent。已在生产环境中的 Claude.ai 完成端到端验证。

供 Agent 参考： 用户说“完成了”或“已上传”，只表示浏览器端上传已完成——服务端 OCR 和处理还需要约 10～30 秒。请轮询 talonic_get_document，直到 status 为 "completed" 后再调用 talonic_extract。过早调用会返回看似文件缺失的错误。（工具说明中已明确要求这样做，通常无需额外提示。）

以下情况无需使用

• 本地 stdio 安装（Claude Desktop、Cursor、Cline、Continue、Cowork）不受工具调用大小限制。上传文件后，Agent 会直接传递 file_data——无需使用 talonic_request_upload。
• 文件已有公开 URL → 将 file_url 传给 talonic_extract。
• 文件已上传至 app.talonic.com → 传入其 document_id。

Agent 决策指南

调用前先选对工具——选错会返回错误数据、消耗额度，还会拖慢对话。

用户有一个文件

• 本地客户端（Desktop、Cursor、……），中小型文件 → 使用 talonic_extract，并提供 file_data 和 filename。
• 托管式连接器（Claude.ai）→ 使用 talonic_request_upload，然后轮询，接着通过 document_id 调用 talonic_extract。（参见 browser-handoff。）
• 文件位于公开 URL → 使用 talonic_extract，并提供 file_url。
• 用户需要特定字段 → 传入 schema 或 schema_id。用户需要全文 → 使用 talonic_to_markdown。两者都需要 → 调用 talonic_extract 并设置 include_markdown: true。

用户在询问现有文档

• 概念性、范围宽泛的问题（“有没有关于赔偿的文档”）→ 使用 talonic_search。
• 按值查询（“金额超过 1000 EUR 的发票”）→ 使用 talonic_filter。
• 用户提到了 document_id → 使用 talonic_get_document（元数据）、talonic_to_markdown（文本），或 talonic_extract（使用新架构重新提取）。重复使用 document_id 比重新上传更省钱。

使用架构

• 一次性使用 → 直接传入架构。要在多个文档间重复使用 → 先调用一次 talonic_save_schema，然后使用 schema_id 调用 talonic_extract。查找现有架构 → 使用 talonic_list_schemas。

置信度与人工审核

• confidence.overall < 约 0.7 → 告知用户提取结果可能不可靠；指出低置信度字段；执行后续操作前先确认。
• 单个字段的置信度 < 约 0.7 → 标记为“需要审核”；不要在计算或外部调用中默默使用。
• 关键字段（金额、法律条款、名称、日期）→ 即使置信度很高，也要与用户确认。
• 需要引用来源？传入 include_provenance: true，获取各字段对应的页码、章节和来源文本。

不应调用 Talonic 的情况

• 一般知识或聊天问题——不要主动提取。
• 数据已在之前的调用中出现在对话里——重复使用即可。
• 关于费用或余额的问题 → 使用 talonic_get_balance。每次调用的费用都会显示在每个 talonic_extract / talonic_to_markdown 响应的 cost 中。

工作原理

Agent (Claude Desktop / Cursor / Claude.ai / …)
  │  MCP protocol — stdio (local) or Streamable HTTP (hosted)
  ▼
Talonic MCP server (this package)
  │  HTTPS, Bearer auth (API key or OAuth token)
  ▼
api.talonic.com

每次工具调用都会向 Talonic API 发送一个 HTTP 请求。服务端负责身份验证、针对瞬时故障（429、5xx）重试、MIME 类型检测、多部分序列化以及结构化错误格式化。它是一个轻量、无状态的客户端——参见隐私。

配置

在 MCP 客户端配置中的 env 块里设置：

故障排除

Error: TALONIC_API_KEY environment variable is required. 缺少或无法读取 env 区块。检查 JSON 结构，然后彻底重启客户端（而不只是重启对话）。

已连接服务列表中没有显示 Talonic。 确认 command 为 npx，且 args 确切为 ["-y", "@talonic/mcp@latest"]。在终端中进行简单验证：npx -y @talonic/mcp@latest --version 应打印版本号。

talonic_extract 返回验证错误，且未提供架构。 这是有意设计的——调用需要知道要提取哪些字段。错误会返回一个可直接粘贴的最简架构（根据你的 instructions 定制），以便重试立即成功。有三种处理方式：提供内联 schema（建议使用完整 JSON Schema），传入来自 talonic_list_schemas 的 schema_id，或设置 auto_schema: true 以进行开放式捕获——Talonic 会发现字段并返回建议的架构供你完善。

将文件拖入 Claude.ai 后，字段为空或为 null。 托管连接器的工具调用上限（约 32 KB）截断了 file_data。请使用 talonic_request_upload——浏览器交接流程是受支持的方式。本地 stdio 安装不受影响。

talonic_request_upload 已成功，但紧接着 talonic_extract 报错。 你在处理完成前就进行了提取。轮询 talonic_get_document，直到 status === "completed"，然后再提取。用户说“完成”仅表示浏览器上传已完成，并不表示 OCR 已完成。

预期有数据时，talonic_filter 却没有返回结果。 有两种原因：（1）该字段尚未提取或不可筛选——调用 talonic_search 并检查 filterable: true；（2）架构类型问题——数值运算符（gt、gte、lt、lte、between）要求字段类型为 number。存储数值内容的 string 字段会静默返回零条结果。在构造数值筛选条件前，先检查 field.dataType === "number"（来自 talonic_search）。

更新后，工具描述看起来仍是旧的。 某些客户端会缓存工具列表。对于 Claude.ai，请移除并重新添加连接器。对于本地客户端，请重启。

已知限制（v0.1）

• **talonic_extract 需要指定字段。**传入 schema（建议使用完整 JSON Schema）或 schema_id，也可以设置 auto_schema: true 以进行开放式捕获，系统会发现字段并返回建议的架构。三者均未提供时，调用会返回验证错误，并附带一个可直接粘贴的最简架构。如果扁平键类型映射（{ vendor_name: "string" }）导致“no fields”错误，请使用完整 JSON Schema：

  {
    "type": "object",
    "properties": {
      "vendor_name": { "type": "string", "title": "Vendor Name" },
      "total_amount": { "type": "number", "title": "Total Amount" }
    },
    "required": ["vendor_name", "total_amount"]
  }
  

• **托管连接器的工具调用上限（约 32 KB）。**实际文件无法通过 Claude.ai/ChatGPT 中的 file_data 传递——请使用 talonic_request_upload。本地安装不受影响。
• **筛选要求字段具有 filterable: true。**请先调用 talonic_search；只有 filterable: true 的条目才能用于 talonic_filter。
• **数值筛选运算符要求字段类型为 number。**以字符串形式存储的数字（货币符号、本地化格式）会静默返回零条结果。设计时应为架构字段设置恰当的类型；查询时应检查 dataType。
• 每次调用的费用仅适用于提取。talonic_extract 和 talonic_to_markdown（文件输入路径）会从 API 的 X-Talonic-Cost-* 标头中返回 cost 区块（costCredits、costEur、balanceCredits、cellsResolvedRegistry、cellsResolvedAi）。读取工具不消耗点数，也不包含 cost；talonic_to_markdown 使用 document_id 路径时会返回 cost: null。随时查询余额 → talonic_get_balance。

开发

git clone https://github.com/talonicdev/talonic-mcp.git
cd talonic-mcp
npm install
npm run build
npm test
node dist/server.js --version

要为文档做贡献或添加工具？请先阅读 AGENTS.md 和 docs/architecture/docs-pipeline.md——文档有两个并行维护的部分，很容易改错地方。

隐私

此 MCP 服务是一个轻量客户端。它不会自行收集、存储、记录或传输任何数据。每次工具调用都会使用你的凭据直接转发到 api.talonic.com，并原样返回响应。此服务不会在单次工具调用之外持久化 API 密钥、输入、输出或文档内容；不会发送分析数据或遥测数据；并且只会在该次调用期间读写你明确传入的 file_path 所指向的文件。

Talonic 对上传数据的处理方式受 talonic.com/privacy 约束：文档会经过 OCR 和信息提取处理，结果存储在你位于 app.talonic.com 的隔离工作区中，工作区数据不会与第三方共享。要删除状态，请在控制面板中移除文档/架构，或撤销 API 密钥。有关此集成的隐私问题，请联系：[email protected]。

许可证

MIT © Talonic GmbH