claimseed

@claimseed/mcp

一个 MCP 服务，可让 Agent 列出、生成和渲染 claimseed 的合成医疗账单样本文档。渲染后的文档会以页面图像的形式返回，聊天客户端会在对话中显示这些图像；如果指定文件夹，文档还会以 PDF 和真实标注文件的形式保存在该文件夹中。该服务通过 stdio 运行，只会写入指定的那个文件夹，不会读取客户端指定的任何文件，也不需要网络访问或 API 密钥。

运行

需要 Node.js 22.13 或更高版本。渲染需要 Chrome 或 Chromium（设置 CLAIMSEED_CHROME=/path/to/chrome，或在常见位置安装）；列出文档和运行 generate_data 则不需要。

若要在聊天中查看文档且不保存文件：

{ "mcpServers": { "claimseed": { "command": "npx", "args": ["-y", "@claimseed/mcp"] } } }

若还要将每个 PDF 及其真实标注保存为文件，请指定一个文件夹：

{
  "mcpServers": {
    "claimseed": {
      "command": "npx",
      "args": ["-y", "@claimseed/mcp", "--workspace", "/absolute/path/to/claimseed-out"]
    }
  }
}

也可以在检出代码后运行：node packages/mcp/src/cli.js（添加 --workspace ./out 以保存文件）。使用 Docker 时，可使用已发布的镜像 ghcr.io/claimseed/claimseed-mcp（其中包含 Chromium；可使用 :latest 或 :0.1.0 这样的版本标签），也可以使用从仓库根目录下的 Dockerfile 构建的镜像（运行 docker build -t claimseed-mcp .，然后在下方将 claimseed-mcp 用作镜像名称）：

docker run -i --rm --network none --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
  --user "$(id -u):$(id -g)" -v "$PWD/claimseed-out:/work" ghcr.io/claimseed/claimseed-mcp

（镜像会写入 /work；若不保存文件，请省略 -v 挂载并添加 -e CLAIMSEED_WORKSPACE=。）

{ "mcpServers": { "claimseed": { "command": "docker",
  "args": ["run", "-i", "--rm", "--network", "none", "--read-only", "--tmpfs", "/tmp", "--cap-drop", "ALL",
           "--security-opt", "no-new-privileges", "--user", "1000:1000",
           "-v", "/absolute/path/to/claimseed-out:/work", "ghcr.io/claimseed/claimseed-mcp"] } } }

该服务在 MCP 注册表中的名称为 io.github.claimseed/claimseed。

将 1000:1000 替换为你的用户和组 ID（id -u、id -g），这样文件夹中的文件就归你所有。Chromium 自带的沙盒需要容器不具备的权限，因此它在镜像内会以禁用沙盒的方式运行；容器就是安全边界，所以以上标志会禁用它的网络访问和功能权限，并限制其可写文件系统。

工具

工具	功能
list_document_types	文档类型（msn、itemized-bill、ppo-eob、hmo-eob），每种类型均附有描述和适用场景。
describe_document_type	某种类型的所有场景：描述、期间、理赔数量、注入的错误（类型、严重程度、规则）及其公开来源。
generate_data	生成一份文档的数据和真实值，不进行渲染；不会写入任何内容。
render_document	渲染一份文档并返回其页面图像、真实值、PDF 的 SHA-256 和页数；指定工作区时，还会将 PDF 和真实值 JSON 写入该工作区，并返回两者的路径。
verify_document	根据答案键，对提取器或账单审核工具针对一份文档报告的内容进行评分：字段准确率（包括读取错误或遗漏的路径）、错误召回率和精确率、误报以及被标记的干扰项。不会进行渲染或写入。

参数包括类型、场景标识和种子（可使用字母、数字、.、_、-；最多 64 个字符）。相同的类型、场景和种子总会生成相同的数据；在 Linux 上使用相同的 Chrome 构建版本时，也会生成相同的 PDF 字节。 render_document 还接受：

• preview：none、first 或 all — 指定哪些页面以图像形式返回（未指定工作区时默认为 all，指定工作区时默认为 first）。页面长边为 1200 像素，格式为 PNG（仅 JPEG 图片能放入时则使用 JPEG），每个结果最多包含 CLAIMSEED_MCP_PREVIEW_KB 的图像数据（默认为 800 KB，低于部分客户端允许的 1 MB 工具结果上限）；结果会说明包含哪些页面以及如何继续获取后续页面。始终会包含请求的第一页；为适应限制，图像会缩小或转为 JPEG；即使限制非常低，也会以最小尺寸包含该页。
• from_page：作为图像返回的起始页（默认为 1），用于查看先前结果因空间不足而未能包含的页面。
• include_pdf：同时在结果中嵌入并返回 PDF。它也计入同一限制：PDF 能放入时，页面图像使用剩余空间（不会强制包含任何图像）；如果 PDF 单独就超过限制，则不会包含 PDF，结果会说明这一点（pdfEmbedded: false）。

verify_document 接受文档的类型、场景和种子，以及 output；该报告符合 schema://extractor-output 的格式：fields 将答案键字段路径（即 documents[0].fields 的键）映射到读取的值，errors 则列出 { kind, fieldRef or lineRef }。它会使用此版本的 claimseed，根据种子重新生成答案键。匹配方式与 @claimseed/core 的 verify 命令一致：金额精确到分，日期使用 ISO、M/D/YYYY 或 "April 11, 2026" 格式，文本不区分大小写；当错误类型和行匹配时，即视为发现错误；对于重复收费，任一行都计为匹配；对干扰项（看起来有误但符合规则的行）进行标记则属于误报。要对整套已渲染文档评分，请使用 claimseed-core batch 和 claimseed-core verify --manifest。

资源：schema://ground-truth（真实值 JSON Schema）、schema://extractor-output（verify_document 用于评分的报告）、catalog://scenarios、catalog://mutations（错误和干扰项操作）、docs://error-taxonomy、policy://synthetic-data 以及 ui://claimseed/preview（下方的 MCP Apps 视图）。提示词：build_test_case（指定目标，可选指定类型），用于规划并渲染小型测试集及其预期结果。

在聊天中查看文档

render_document 结果包含作为标准 MCP 图像内容的页面图像、作为结构化内容的真实数据，并指定一个 MCP Apps 视图 （_meta.ui.resourceUri = "ui://claimseed/preview"），用于显示页面和错误注入表格。你看到的内容取决于客户端：

客户端	显示内容
支持 MCP Apps 的客户端（ChatGPT、Claude、VS Code 等）	在对话中显示该视图：所有返回的页面和注入的错误。
显示图像内容的客户端（Claude Desktop、claude.ai、MCP Inspector）	工具结果中的页面图像。
仅将图像传递给模型的客户端（若干命令行 Agent）	文本摘要；模型可以看到页面并对其进行描述。

每个客户端都会获得文本摘要和结构化的真实数据。该视图是一个完全独立的页面：它不会加载任何内容（其 Content-Security-Policy 仅允许 data: 图像），除了向宿主发送 MCP Apps 消息外，不会发送任何内容；所有值均以文本形式显示，且只从宿主的样式变量中读取颜色和字体值。

ChatGPT 通过 HTTPS 连接 MCP 服务，因此 stdio 服务需要桥接程序和公开地址。一种方式是使用第三方工具（请固定为已检查过的版本）：运行 npx -y [email protected] --stdio "npx -y @claimseed/mcp" --outputTransport streamableHttp --stateful --port 8000，使用隧道公开端口 8000（例如 cloudflared tunnel --url http://localhost:8000），然后在 ChatGPT 的开发者模式中添加 https://<tunnel address>/mcp 作为连接器。隧道运行期间，任何拥有隧道地址的人都能调用该服务；没有工作区时不会写入任何内容，但完成后请关闭隧道。

限制与安全

• 一个文件夹，或不保存任何文件。 没有工作区时，服务不会保存任何文件。与任何 Chrome 一样，其浏览器会在运行期间于系统临时文件夹中保留一个临时配置文件（在容器中为内存中的 /tmp）；浏览器关闭后、连续一分钟没有渲染任务后或服务停止时，配置文件会被删除，只有进程被强制终止时才会残留。有工作区时，服务只会写入工作区文件夹（--workspace 或 CLAIMSEED_WORKSPACE），该文件夹必须存在，且不能是 / 或你的主文件夹。服务会自行选择所有文件名（<type>_<scenario>_<seed>_<random>.pdf 和 .ground-truth.json），以独占方式创建文件，绝不通过符号链接创建；如果文件夹在运行期间被移动或替换为链接，服务就会停止。
• 配额。 CLAIMSEED_MCP_QUOTA_MB（默认值为 500）限制输出文件的总大小。大小会跨运行计入账本（.claimseed-mcp.json），其中记录每个文件的大小和 SHA-256。超出配额时，服务会删除本次运行中自己生成的最旧输出文件，且只会删除内容与写入时完全一致的文件。删除权限保存在内存中，而非账本里，因此修改账本无法让服务删除任何文件。服务绝不会删除其他文件，包括之前运行时生成的输出文件：如果仅这些文件就已占满配额，在你移除部分文件前，渲染任务会被拒绝。每个文件夹只运行一个服务。
• 时间与负载。 每个服务进程共用一个浏览器；CLAIMSEED_MCP_CONCURRENCY 控制同时进行的渲染任务数（默认值为 2，最多为 4），另有最多 4 个任务等待，超过后会以繁忙为由拒绝渲染任务。如果渲染耗时超过 CLAIMSEED_MCP_TIMEOUT_MS（默认值为 30000），任务会失败，浏览器也会重启；此时并行运行的其他渲染任务也会失败，但可以重试。连续一分钟没有渲染任务后，浏览器会关闭。超过 4 MB 的协议消息会关闭服务。
• 渲染已按 @claimseed/core 的方式锁定： HTML 从内存打印，JavaScript 关闭，并启用严格的 CSP、请求拦截和无效代理（参见 SECURITY.md）。运行 Docker 镜像时请使用上述标志。
• 页面图像由 PDF.js 在同一浏览器的页面中从加盖标记的 PDF 绘制（https://mozilla.github.io/pdf.js/）；该页面在独立的浏览器上下文中运行，每次渲染后都会关闭。该页面会运行脚本（PDF.js），但只会打开服务刚刚渲染的 PDF，只会从此软件包加载 PDF.js 及其字体（从内存提供），PDF 中的脚本已关闭，且不会联网。图像会像 PDF 一样显示样本标识带和水印；每个图像文件的元数据中都包含样本文本（PNG tEXt，或 JPEG 中的 Exif 和注释）。
• 报告有上限，且绝不会回显。 verify_document 会拒绝字段超过 5,000 个、错误超过 1,000 个、路径超过 200 个字符、值超过 1,000 个字符或其他格式不符的报告，并仅通过消息给出位置。其结果包含计数、比率、答案键路径、类别和干扰项 ID；调用者发送的内容不会返回，报告中的任何内容也不会用作文件路径。
• 输出带有标记。 每页都带有样本标识带和水印，PDF 元数据也会注明这是一个合成样本；没有任何工具参数可以关闭这些标记。可接受的用途请参见 policy://synthetic-data。

开发

npm test -w @claimseed/mcp          # end to end through the MCP client over stdio; rendering tests need Chrome
npm run sync-resources -w @claimseed/mcp   # after changing schemas/ or the two documents in docs/ it serves