heu-mcp

HEU Legal MCP 服务

MCP 服务（Model Context Protocol），用于将 HEU Legal API 接入 Claude 和任何 MCP 客户端。可在对话中直接管理电子签名文档的整个生命周期（在 180 多个国家/地区有效）：从创建和发送签名，到发送提醒，再到下载完整的法律档案。

---

可以做什么

我想……	服务可以通过……实现
📄 查看我的文档和模板	list_heu_documents, list_pdf_documents
✍️ 从模板发送合同进行签署	create_heu_document, create_pdf_document
🚀 发送电脑上的 PDF 进行签署，无需经过平台	create_pdf_document_from_upload
🤖 让 AI 映射签名字段（分析 PDF、放置字段并发送）	locate_pdf_text + create_pdf_document_from_upload
🔔 提醒尚未签署的人	prompt_heu_document_signature, prompt_pdf_document_signature
👀 让 AI 阅读合同（摘要、条款、比较），而无需下载	read_heu_document, read_pdf_document
🪪 提取各方信息（增值税号、税号、SDI、PEC、地址）	extract_heu_document_parties, extract_pdf_document_parties
💾 下载已签署的 PDF	download_heu_document_pdf, download_pdf_document
⚖️ 下载完整法律档案（文档 + 审计跟踪 + FES 产物）	download_pdf_bundle, download_pdf_audit_trail
🧩 通过 API 创建／修改可重复使用的 PDF 模板	create_pdf_template, update_pdf_template, preview_pdf_template, delete_pdf_template
❌ 取消误发的签名请求	cancel_pdf_document
🩺 检查 API 是否可访问	get_heu_health

两类对象：

• HEU 原生文档 — 使用平台内置编辑器创建（UUID 格式的 ID，例如 5135e7b2-196b-...）。
• 已上传的 PDF — 带有签署人和已放置签名字段的 PDF 文件（数字 ID，例如 68）。

---

要求

• Python ≥ 3.10
• HEU Legal API 密钥 — 在 UI 中：Profile → API Keys → Generate API Key（需要 Enterprise 订阅；最多可启用 2 个密钥）
• 对于基于模板的工作流：平台上至少有一个已创建的模板（也可以通过 create_pdf_template API 创建）

安装

通过 PyPI 安装：

pip install heu-mcp

从源代码安装：

git clone https://github.com/heulegal/heu-mcp.git
cd heu-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "heu": {
      "command": "heu-mcp",
      "args": [],
      "env": {
        "HEU_API_KEY": "la_tua_api_key_qui"
      }
    }
  }
}

如果从源代码安装并使用 venv：

{
  "mcpServers": {
    "heu": {
      "command": "/path/assoluto/heu-mcp/venv/bin/python",
      "args": ["/path/assoluto/heu-mcp/server.py"],
      "env": {
        "HEU_API_KEY": "la_tua_api_key_qui"
      }
    }
  }
}

修改后重启 Claude Desktop。

Claude Code（CLI）

claude mcp add heu heu-mcp -e HEU_API_KEY=la_tua_api_key_qui

---

远程服务（多用户）

除了上文介绍的本地模式（stdio），本项目还包含一个远程服务，可通过 HTTPS 提供相同的 28 个工具，用户无需安装任何内容即可连接：只需在 OAuth 流程中输入一次自己的 HEU API 密钥。

特性：

• 使用 Streamable HTTP 传输，通过 OAuth 2.1 和 PKCE S256 进行身份验证，并支持动态客户端注册和客户端 ID 元数据文档
• 多用户：每个连接均使用对应用户的 API 密钥；密钥经过加密（Fernet）存储，绝不会以明文形式保存在数据库中
• 刷新令牌支持轮换，如检测到可疑的重复使用，会自动撤销会话
• 网络 I/O 异步执行，PDF 解析在 threadpool 上运行：一个缓慢的请求不会阻塞其他用户

本地启动

pip install -e ".[remote]"
export HEU_MCP_SECRET_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
export PUBLIC_URL="http://localhost:8080"
export HEU_MCP_DB="./heu-mcp.db"
heu-mcp-remote

部署到 Fly.io

fly launch --no-deploy
fly volumes create heu_data --size 1
fly secrets set HEU_MCP_SECRET_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
fly secrets set PUBLIC_URL="https://<nome-app>.fly.dev"
fly deploy

远程服务环境变量

变量	描述	默认值
HEU_MCP_SECRET_KEY	用于加密用户 API key 的 Fernet 密钥（必需）	—
PUBLIC_URL	服务的公开 URL，不带末尾斜杠（生产环境必需）	http://localhost:8080
MCP_PATH	MCP 端点路径	/mcp
HEU_MCP_DB	SQLite 数据库路径	/data/heu-mcp.db
ACCESS_TOKEN_TTL / REFRESH_TOKEN_TTL	令牌有效期（秒）	1 小时 / 60 天

公开端点

端点	用途
/mcp	MCP 端点（需要 bearer 令牌）
/.well-known/oauth-protected-resource	受保护资源元数据（RFC 9728）
/.well-known/oauth-authorization-server	授权服务器元数据（RFC 8414）
/register · /authorize · /token	OAuth 2.1 流程
/healthz	存活探针

环境变量

变量	描述	默认值
HEU_API_KEY	HEU Legal API key（必需）	—
HEU_BASE_URL	API 基础 URL	https://api.heulegal.com/v1
HEU_DOWNLOAD_DIR	保存下载文件的文件夹	/tmp

---

工具完整参考（28 个）

🩺 健康状况

工具	参数	返回内容
get_heu_health	—	API 正常运行时返回 { message: "ok", status: 200 }

📄 HEU 原生文档

工具	参数	功能
list_heu_documents	type（document/template）、sort（asc/desc）、created_from + created_to（ISO 8601）、have_editors_signed — 均为可选项	列出文档/模板及其状态、成员和签名。⚠️ 两个日期必须始终一起传入，否则 API 可能返回不完整的结果
get_heu_document	document_id	完整详情：名称、状态（to_sign/in_progress/in_review/completed/signed）、所有者、编辑者、含 has_signed 和 signed_at 的成员、标签
list_heu_document_placeholders	document_id	列出模板文本中可替换的占位符键
create_heu_document ✋	source_document_id、email_subject、email_text、email_to（列表）、document_name、document_type、placeholders（键→值映射）	根据模板创建文档、替换占位符，并通过电子邮件分享给收件人
prompt_heu_document_signature ✋	document_id	发送签名提醒。限制：每份文档每 24 小时 1 次（超出时返回 429 和 Retry-After）
read_heu_document	document_id、pages（例如 "1-3"、"5"、"1,3,5-7"）、layout、has_index、has_footer	提取文档文本并返回到对话中，不会保存到磁盘。省略 pages 时最多读取 100 页
extract_heu_document_parties	document_id、pages、include_text	当事方数据：合并已登记的签署人信息与从文本中提取的税号、增值税号、SDI 唯一代码、电子邮件、PEC、出生地点和日期、地址、邮政编码。匹配模式针对意大利合同优化
download_heu_document_pdf	document_id、layout（UI 代码：100、200-204、210-214、220-224、230-234）、has_index、has_footer、output_path	生成 PDF 并保存到磁盘；返回文件路径

📎 已上传的 PDF

工具	参数	功能
list_pdf_documents	type（必填：document/template）、sort	列出 PDF 及其状态（to_sign/in_progress/signed）、签名类型（FES/FEA）和签署人
get_pdf_document	document_id	详情：名称、状态、signature_type、日期，以及包含 has_read/has_signed 的签署人信息
list_pdf_document_signers	document_id	PDF 的签署人：ID、姓名、邮箱、是否已阅读、是否已签署
list_pdf_document_signer_placeholders	document_id、signer_id	分配给特定签署人的字段（签名/文本/复选框），包含位置和填写状态
list_pdf_document_placeholders	document_id	PDF 的所有字段
create_pdf_document ✋	source_document_id、email_subject、email_body、signers（包含 source_id、full_name、email）、document_name、signature_type（fes/fea）、可预填的 placeholders	根据现有模板创建可签署的 PDF 并发送邀请。使用 fea 需要有足够的额度（否则返回 422）
prompt_pdf_document_signature ✋	document_id	提醒对方签署 PDF
read_pdf_document	document_id、pages	提取 PDF 文本（包括已签署的文本）并在对话中返回
extract_pdf_document_parties	document_id、pages、include_text	获取已上传 PDF 中各方的信息（同上）
download_pdf_document	document_id、output_path	下载 PDF — 如有已签署版本则下载该版本 — 并返回路径
download_pdf_audit_trail	document_id、output_path	下载审计记录：记录谁在何时阅读/签署的 PDF
download_pdf_bundle	document_id、output_path	下载法律文件包 ZIP：已签署的 PDF + 审计记录 + FES 相关文件。非常适合用于证据留存归档
cancel_pdf_document ✋	document_id	取消已发出的签署请求：文档会从列表中消失，签署链接也会失效。如果有人已签署，则会返回 409

🧩 PDF 模板（通过 API 管理）

工具	参数	功能
create_pdf_template ✋	file_path（本地 PDF ≤ 5 MB）、document_name、signers（source_id、full_name）、placeholders（类型、位置 %、页码）	上传电脑中的 PDF，创建可重复使用的模板。返回的 ID 可作为 create_pdf_document 中的 source_document_id 使用
create_pdf_document_from_upload ✋	file_path、document_name、email_subject、email_body、signers（包含邮箱）、placeholders、signature_type	一站式快捷操作：上传 PDF 并立即发送签署，无需先创建模板。文档创建后状态为 to_sign，签署人会立即收到邮件
locate_pdf_text	file_path 或 document_id、search_terms（默认：签名关键词）、pages、include_all_lines	查找 PDF 中文本的坐标（以 % 为单位，原点在左下角——与占位符使用相同的坐标系统）。此工具可让 AI 自动放置字段：搜索“签名”、各方姓名或任意锚点，并获取每个匹配项的页码和位置
preview_pdf_template	document_id、output_path	下载带标注的预览：每个字段都会显示为带有类型和签署人标签的方框。可在发送前核对位置
update_pdf_template ✋	document_id、signers（完整替换集合）、placeholders（同上；[] 会删除所有字段）、document_name	完整替换模板的签署人和字段（ID 保持不变）。仅限所有者
delete_pdf_template ✋	document_id	从所有列表中删除（隐藏）模板

✋ = 此工具会产生外部影响（创建、发送邮件、删除）：Claude 执行前总会请求确认。

占位符的定位方式

• position_x / position_y：页面的百分比（不含 0–100），原点位于左下角（与应用编辑器相同）。
• page_number：从 1 开始。
• 类型：signature、initials、text（需要 text_label）、checkbox_optional、checkbox_required。
• 签署人通过 source_id → signer_source_id 与字段关联。
• API 会拒绝旋转过的 PDF（/Rotate 90/180/270）。

---

典型工作流

0. “智能”发起签署：AI 自动映射字段

“获取 /Users/me/Desktop/Contratto.pdf，找出各方需要签署的位置，然后发送给 [email protected] 和 [email protected]。”

幕后流程：

1. locate_pdf_text 分析 PDF 并找到锚点：带有“客户签名”/“供应商签名”字样（或各方名称）的行及其精确的百分比坐标。
2. Claude 提出映射方案：“我会把客户签名字段放在第 4 页‘客户签名’标签上方（x 17%，y 14%），并将供应商签名字段放在旁边（x 50%，y 14%）。确认吗？”
3. 确认后，create_pdf_document_from_upload 上传已放置占位符的 PDF，并发送签署邮件。
4. （可选）如果使用了模板，可通过 preview_pdf_template 进行目视检查。

locate_pdf_text 返回的坐标已采用 HEU 占位符坐标系（百分比，原点在左下角），无需转换。对于复杂布局，可以请求整页映射，设置 include_all_lines=true；也可以搜索特定词语（search_terms=["Il Committente", "Il Prestatore"]）。

⚠️ 限制：此功能适用于含文本的 PDF。未经 OCR 处理的扫描件没有可提取的文本，此时请手动指定位置。

1. 为电脑上的 PDF 发起签署（全程通过聊天完成）

“获取 /Users/me/Desktop/NDA.pdf，发给 Mario Rossi（[email protected]）签署。签名字段放在最后一页的右下角，邮件主题为‘待签署的 NDA’。”

Claude 使用 create_pdf_document_from_upload → 文档创建完成，Mario 随即会收到邮件。然后：

“Mario 签了吗？” → get_pdf_document “提醒他” → prompt_pdf_document_signature “签好了，把完整文件包下载给我” → download_pdf_bundle

2. 使用模板处理重复性合同

“根据 Contratto-tipo.pdf 创建一个模板，包含两个签署人：客户和供应商。客户的签名字段放在第 3 页底部。” → create_pdf_template “给我看看预览，检查一下位置” → preview_pdf_template “现在用它把合同发给 ACME srl” → create_pdf_document

3. 文档分析（AI 阅读合同）

“总结合同 abc-123，并告诉我合同期限和解约条件” → read_heu_document “比较合同 X 和 Y 中的责任条款” → 两次调用 read_heu_document “提取各方信息：公司名称、P.IVA、SDI、PEC” → extract_heu_document_parties

各方信息提取功能旨在与意大利电子发票工作流集成：从合同中提取的 SDI 唯一代码和 P.IVA 可直接用于管理系统中的客户资料。

4. 监控与管理

“哪些 7 月的文档还没有全部签署？” → 调用 list_heu_documents 并指定日期及 have_editors_signed=false “取消 PDF 42 的签署请求，我们发错人了” → cancel_pdf_document

---

需要了解的行为和限制

项目	限制 / 行为
API 速率限制	300 次请求 / 5 分钟（响应中包含 X-RateLimit-* 标头；超过阈值时返回 429，并附带 Retry-After）
签名提醒	每份文档每 24 小时 1 次
PDF 上传	最大 5 MB，application/pdf，不能旋转
文本读取	未指定 pages 时最多 100 页（载荷会标记 truncated: true）；未经 OCR 处理的扫描版 PDF 没有可提取的文本
FEA 签名	每位签署人都需要有可用的 FEA 积分（不足时返回 422）
带日期的 list_heu_documents	始终同时传入 created_from 和 created_to
取消 PDF	仅在没有签名活动时可执行（否则返回 409）
下载	二进制文件会保存到磁盘（HEU_DOWNLOAD_DIR），绝不会通过 MCP 通道传输

文档状态

状态	含义
to_sign	等待签名
in_progress	正在准备 / 修改
in_review	正在审核
completed	流程已完成（未签名）
signed	已完成签名

安全

• API key 仅从环境变量读取：绝不写入代码、响应或日志。
• 具有外部影响的工具（✋）均要求始终征得用户明确确认。
• 下载的文件保留在本地文件系统中。

开发

git clone https://github.com/heulegal/heu-mcp.git
cd heu-mcp
python3 -m venv venv
source venv/bin/activate
pip install -e .

# Avvio manuale per debug
HEU_API_KEY=... python server.py

参考 OpenAPI 规范发布于 https://api.heulegal.com/v1/specs/v1.yaml（交互式文档：https://api.heulegal.com/v1/docs）。

许可证

MIT — 参见 LICENSE。

链接

• HEU Legal
• HEU API 文档
• Model Context Protocol
• PyPI 软件包