Henrri (unofficial)

重要

这不是 Henrri 的官方产品。 这是一个独立的开源项目， 并非由 Henrri 制作、认可或支持。它逐项覆盖已发布的 Henrri v1 规范， 在 API 所允许的范围内忠实实现，并说明 API 与文档描述不一致之处。请参阅免责声明。

向助手提出 “为 Atelier Martin 开具发票，内容是 3 天开发工作，未税金额 600 欧元”、“还有谁欠我钱？”、“把已签署的报价单 D-26-11-3 转成发票”—— 就能直接在你的 Henrri 中完成操作，你的会计师也能看到结果。

> who still owes me money?

  list_payment_milestones   is_overdue = true · 7 milestones
                            ATELIER MARTIN    I-26-10-12   1 440,00 €   23 days late
                            LOVELACE          I-26-10-17     864,00 €    9 days late
                            …
                            overdue total     4 812,40 €

> invoice Atelier Martin for 3 days of development at 600 € excl. tax

  create_document           draft invoice 9632 for ATELIER MARTIN
  add_document_line         3 × Journée de développement · 600,00 € · VAT 20 %
  get_document_with_all     1 800,00 € excl. tax · 360,00 € VAT · 2 160,00 € incl. tax
                            finalize it? It locks the invoice for good and costs 8 credits.

为什么

Henrri 的 API 是简洁的 REST 接口，但直接交给大模型使用时，会以一些可预见的方式出错：PUT 会抹掉未随请求发送的所有字段；文档在调用一个不可撤销的操作之前都只是草稿；定稿会消耗额度；月度配额和速率限制器都会返回 429；模型也无法分辨文档的 ID 和编号。

• **完整 API，毫无隐藏。**涵盖 v1 规范的全部 87 项操作：85 个路由，每个路由对应一个工具，另外两项认证路由由客户端本身处理。测试会将工具表与 spec/operations.tsv 比对，CI 每天都会将该文件与线上生产环境和沙盒规范进行核对。
• **更新，就该真正更新。**每个 update_* 工具只接收要修改的内容，读取资源、合并并写回 Henrri 接受的内容——不会再因为客户的网站变更，就丢失他们的备注。
• 对于不可撤销的操作，默认拒绝执行。finalize_document、validate_quotation、付款工具、cancel_deposit 以及所有删除操作，都必须提供 confirm: true 才会执行；拒绝执行时会说明可能造成的后果：文档、总额、客户和额度。设置 HENRRI_READ_ONLY=1 会禁用所有写入工具。
• **让模型可以据此采取行动的错误信息。**失败会以工具结果的形式返回，并设置 isError: true，同时包含 Henrri 的 RFC 9457 问题文档：稳定的 errorCode（ALREADY_FINALIZED、LINES_MISSING、QUOTA_EXCEEDED 等）、detail、无效字段、供 Henrri 支持团队查询的 traceId，以及在解决方法不明显时提供的提示。
• **一次处理好 API 的种种规则。**提前续期 10 分钟有效的令牌；遇到速率限制、503 和繁忙的定稿操作时进行重试；遇到额度限制时绝不重试；POST 请求可能已经执行后绝不再次发送；列表筛选条件以重复键的形式发送；将 last month 等时间段转换为 Henrri 使用的含首尾日期。
• **经过验证的 Webhook。**通过 HTTP 时，服务会在 /webhooks 接收 Henrri 的推送，以恒定时间校验其 HMAC-SHA256 签名，拒绝重放请求，并让模型读取发生的事件。
• **为模型阅读而编写。**89 个工具均提供带模式的结构化输出，每个工具都有注解；提供 4 个会在执行不可撤销操作前停下并询问的提示词；服务器说明会预先指出：使用 ID 而非编号、金额单位为欧元，以及草稿和定稿的区别。

安装

# macOS on Apple silicon; swap the target for x86_64-apple-darwin,
# x86_64-unknown-linux-gnu or aarch64-unknown-linux-gnu
V=v0.1.0 T=aarch64-apple-darwin
curl -LO https://github.com/edouard-claude/henrri-mcp/releases/download/$V/mcp-henrri-$V-$T.tar.gz
tar xzf mcp-henrri-$V-$T.tar.gz
sudo mv mcp-henrri-$V-$T/mcp-henrri /usr/local/bin/

git clone https://github.com/edouard-claude/henrri-mcp
cd henrri-mcp
cargo build --release
# the binary is at target/release/mcp-henrri

cargo install --git https://github.com/edouard-claude/henrri-mcp

docker run --rm -i \
  -e HENRRI_USERNAME -e HENRRI_PASSWORD \
  ghcr.io/edouard-claude/henrri-mcp:latest

获取 API 访问权限

Henrri 的开发者方案提供 API 访问权限。API 有两个环境，账户彼此独立：

认证方式有以下三种，按优先级从高到低排列：

1. 开发者客户端——使用 HENRRI_CLIENT_ID 和 HENRRI_CLIENT_SECRET，通过 POST /v1/users/authenticate 交换令牌，并通过 POST /v1/users/refresh-token 续期。
2. API 用户——使用 HENRRI_USERNAME 和 HENRRI_PASSWORD，通过 POST /v1/users/token 使用 OAuth2 password 授权（沙盒会提供这种账户，例如 [email protected]）。
3. 现成令牌——使用 HENRRI_ACCESS_TOKEN，原样使用且不会续期（有效期为 10 分钟）。

然后检查一切是否正常：

HENRRI_ENVIRONMENT=sandbox HENRRI_USERNAME=… HENRRI_PASSWORD=… mcp-henrri --check

environment  sandbox
base url     https://api-sandbox.henrri.io
credentials  API user (OAuth2 password grant)
toolsets     account, customers, documents, catalog, payments, revenues, webhooks
tools        89
token        ok
hello world  "Hello World"
user         [email protected] (16079), role admin
company      My company (947), plan discovery
credits      used 100 of unlimited, unlimited left

ready.

配置

所有内容均从环境变量读取，并在启动时读取一次。变量缺失或格式错误都会导致进程停止，并显示变量名称。

本地使用时，将 .env.example 复制为 .env；该文件已加入 git 忽略列表。

连接客户端

{
  "mcpServers": {
    "henrri": {
      "command": "/usr/local/bin/mcp-henrri",
      "env": {
        "HENRRI_USERNAME": "[email protected]",
        "HENRRI_PASSWORD": "…",
        "HENRRI_ENVIRONMENT": "production"
      }
    }
  }
}

claude mcp add henrri \
  -e [email protected] -e HENRRI_PASSWORD=… \
  -- /usr/local/bin/mcp-henrri

{
  "servers": {
    "henrri": {
      "type": "stdio",
      "command": "/usr/local/bin/mcp-henrri",
      "env": { "HENRRI_USERNAME": "[email protected]", "HENRRI_PASSWORD": "…" }
    }
  }
}

提示：只需读取信息的记账员可以使用 HENRRI_READ_ONLY=1 运行；只需跟进付款的助手可以使用 HENRRI_TOOLSETS=customers,payments 运行。

工具

七个工具集中共有 89 个工具。mcp-henrri --list-tools 会列出当前配置开放的工具。R 表示读取，W 表示写入，D 表示具有破坏性或不可逆的操作，需要设置 confirm: true（两个付款工具和 validate_quotation 也需要）。

documents — 报价单、发票、贷项通知单、明细、PDF

payments — 付款节点、定金、付款

客户 — 客户与联系人

目录 — 商品、类别、文本项、单位

账户、收入与 Webhook

POST /v1/users/authenticate 和 POST /v1/users/refresh-token 不是工具：客户端会自行调用它们，OAuth2 令牌端点 POST /v1/users/token 也是如此。

资源和提示词

Henrri 的实际行为

在构建此服务时通过沙盒发现了这些情况，并已妥善处理，模型不会遇到它们。tests/api_contract.rs 中的测试会验证每一项。

• PUT 会删除未随请求发送的内容。 更新客户网站时，如果不附带评论，评论就会被删除。更新工具会先读取、合并，再写回。
• 某些字段读取时返回 ""，但提交 "" 会被拒绝。 vatNumber、siret 等字段都是如此。未变更的空字符串不会写入。
• 携带联系人信息的客户 PUT 会被拒绝（PUT_WITH_CUSTOMER）；携带嵌套项目、项目类型或计算总额的行 PUT 也会被拒绝。这些内容会被剔除。
• 没有请求体且未提供 Content-Length 的 POST 会收到 IIS 411。 transform-to-invoice、deposit-request、pdf/url 等请求都会附带一个显式的空请求体。
• 逗号分隔的列表筛选条件不会报错，而是返回空页（文档称会返回 400）。列表会以重复的键发送。
• 创建付款节点时会忽略到期日，但更新时会采用该日期： create_payment_milestone 会通过第二次调用来设置日期。
• 定稿请求体中的 confirmFirstOfMonth 会被拒绝，尽管 FIRST_ACCOUNTING_DOCUMENT_MONTH 错误要求提供该字段：它会作为查询参数发送。
• 新单位的响应会返回 id: 0：create_unit 会通过单位名称查找该单位。
• 公司级付款节点列表只显示已定稿的文档；已定稿文档指向客户的冻结副本（parentCustomerId）：草稿的付款计划通过文档读取，客户的付款计划则通过该副本读取。
• 城市会根据邮政编码变化。 Henrri 会重写城市名称（“Paris 01”）；与邮政编码不匹配的城市会被清空。请同时修改两者。
• refresh_token 在 /v1/users/token 上会被拒绝；API 用户会直接再次获得授权。
• 有两种不同的 429。 每分钟速率限制器会重试；QUOTA_EXCEEDED（每月额度）不会重试。
• PDF 渲染速度很慢，且在撰写本文时沙盒中的渲染存在问题（返回 500 或没有响应）；PDF 路由使用单独的较长超时。

安全性

• 不可逆调用采用失败关闭机制：没有 confirm: true 时，不会有任何内容离开进程，并且拒绝操作时会说明将会发生什么。服务说明和提示词会指示模型先向用户说明情况并取得肯定答复。
• 设置 HENRRI_READ_ONLY=1 后，完全不会注册写入工具：只读状态由每个工具的 readOnlyHint 决定，而不是由可能发生偏差的列表决定。
• 秘密信息绝不会进入日志或 Debug 输出；日志会写入 stderr。
• PDF 仅会写入 HENRRI_DOWNLOAD_DIR，并使用经过净化的文件名。
• 通过 HTTP 访问时，/mcp 需要 HENRRI_HTTP_TOKEN（使用恒定时间比较）；没有令牌时，服务会拒绝在回环地址以外监听；在回环地址上，会对 Host 进行验证，以防止 DNS 重绑定。
• 只有签名有效、时间戳在五分钟以内且每个投递 ID 仅首次出现的 Webhook 投递才会被接受。

通过 HTTP 运行

HENRRI_HTTP_TOKEN=$(openssl rand -hex 32) \
HENRRI_WEBHOOK_SECRET=… \
mcp-henrri --http 127.0.0.1:8080
# MCP at http://127.0.0.1:8080/mcp, webhooks at /webhooks, health at /healthz

Streamable HTTP 传输可服务多个会话，这些会话共用一个 Henrri 令牌和一个 Webhook 收件箱。在反向代理后，将绑定地址设为 0.0.0.0（此时必须提供令牌），并将 Henrri 的 Webhook 回调指向 https://<your-host>/webhooks。Henrri 对每次投递只发送一次，不会重试：接收方会立即响应 204，重复投递也不例外。

验证

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test                      # unit, contract (fake Henrri), stdio and HTTP protocol tests

使用真实沙盒进行验证，并在 .env 中填写沙盒凭据（此操作会创建一份报价草稿并将其删除；不会定稿）：

set -a; source .env; set +a
HENRRI_SANDBOX_TESTS=1 cargo test --test sandbox

API 有变动吗？此命令会按 spec/operations.tsv 的格式打印实时操作列表（CI 每天都会针对生产环境和沙盒运行此命令）：

scripts/spec-operations.sh | diff - spec/operations.tsv

发布

更新 Cargo.toml 和 server.json 中的 version，在 CHANGELOG.md 中添加一个章节，然后推送 vX.Y.Z 标签。发布工作流会检查三者是否一致，为五个目标平台构建二进制文件，将多架构镜像发布到 GHCR，并根据变更日志发布说明。

贡献

欢迎提交问题和拉取请求。请遵循代码所依循的规则：一条路由对应一个工具，并为真实 API 强制要求的每种行为编写测试。请参阅 CONTRIBUTING.md。

免责声明

Henrri 是其所有者的商标。本项目为非官方项目，与 Henrri 无关，也未获得 Henrri 的认可或支持。本项目基于 Henrri 的公开 v1 API 规范构建，并通过 Henrri 沙盒进行测试；API 变更时，行为也可能随之改变。在生产环境中定稿文档会产生税务后果并消耗 API 额度：您须对以自己名义签发的内容负责。本项目依据 MIT 许可证提供，不附带任何保证。

许可证

MIT © 2026 Edouard Claude