heu-mcp

HEU Legal MCP Server

HEU Legal API を Claude およびあらゆる MCP クライアントに接続する MCP サーバー（Model Context Protocol）です。電子署名（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
🪪 当事者のデータ（VAT 番号、納税者番号、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

オブジェクトは 2 種類あります。

• HEU ネイティブドキュメント — プラットフォームのアプリ内エディターで作成したもの（UUID 形式の ID、例：5135e7b2-196b-...）。
• アップロード済み PDF — 署名者と署名フィールドを配置した PDF ファイル（数値 ID、例：68）。

---

必要条件

• Python ≥ 3.10
• HEU Legal API キー — UI で Profile → API Keys → Generate API Key（Enterprise サブスクリプションが必要。アクティブなキーは最大 2 個）
• テンプレートを使う場合：プラットフォーム上でテンプレートを少なくとも 1 つ作成済みであること（または 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）に加えて、プロジェクトには同じ 28 個のツールを HTTPS 経由で公開するリモートサーバーが含まれており、ユーザーは何もインストールせずに接続できます。OAuth フローで自分の HEU API キーを一度入力するだけです。

特徴：

• Streamable HTTP トランスポート、PKCE S256 による OAuth 2.1 認証、Dynamic Client Registration、Client ID Metadata Document
• マルチユーザー：各接続でユーザー自身の API キーを使用します。API キーは暗号化（Fernet）して保存され、データベース内に平文で保存されることはありません
• リフレッシュトークンのローテーションと、不審な再利用が発生した場合のセッションの自動失効
• ネットワーク I/O は非同期、PDF の解析はスレッドプールで実行するため、時間のかかるリクエストがほかのユーザーをブロックしません

ローカルでの起動

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 キーを暗号化する 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 エンドポイント（ベアラートークンが必要）
/.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 キー（必須）	—
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 — すべて任意	ステータス、メンバー、署名を含む文書／テンプレートの一覧を取得します。⚠️ 2 つの日付は必ずセットで指定してください。そうしないと 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 回まで（上限を超えると Retry-After を含む 429 を返します）
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	当事者のデータ：登録済みの署名者情報と、テキストから抽出した納税者番号、VAT 番号、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	ステータス（to_sign/in_progress/signed）、署名方式（FES/FEA）、署名者を含む PDF の一覧を表示します
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を使って関連付けます。
• 回転したPDF（/Rotate 90/180/270）はAPIで拒否されます。

---

典型的なワークフロー

0. 「スマート」な署名依頼：AIがフィールドを自動でマッピング

「/Users/me/Desktop/Contratto.pdfを開いて、各当事者が署名する場所を見つけて、[email protected]と[email protected]に送ってください。」

内部では次の処理が行われます。

1. **locate_pdf_text**がPDFを分析し、アンカーを見つけます。「Firma del Cliente」／「Firma del Fornitore」の行（または当事者の名前）と、その正確なパーセンテージ座標です。
2. Claudeがマッピングを提案します。「4ページ目の『Firma del Cliente』ラベルの上（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 da firmare』にしてください。」

Claudeがcreate_pdf_document_from_uploadを使い、文書を作成すると、Marioにすぐメールが届きます。その後は次のように操作できます。

「Marioは署名しましたか？」 → get_pdf_document 「リマインダーを送って」 → prompt_pdf_document_signature 「署名済みです。書類一式をダウンロードしてください」 → download_pdf_bundle

2. テンプレートを使った定期的な契約

「Contratto-tipo.pdfから、署名者を顧客と供給元の2名にしたテンプレートを作成してください。顧客の署名欄は3ページ目の下部です。」 → create_pdf_template 「位置を確認するため、プレビューを表示してください」 → preview_pdf_template 「では、これを使ってACME srlに契約書を送ってください」 → create_pdf_document

3. 文書分析（AIが契約書を読み取る）

「契約書abc-123を要約して、期間と解約条件を教えてください」 → read_heu_document 「XとYの契約書の責任条項を比較してください」 → read_heu_documentを2回 「当事者の情報を抽出してください。会社名、P.IVA、SDI、PECです」 → extract_heu_document_parties

当事者情報の抽出は、イタリアの電子請求書ワークフローとの連携を想定しています。契約書から抽出した一意のSDIコードとP.IVAを、管理システムの取引先情報に直接反映できます。

4. モニタリングと管理

「7月の文書のうち、まだ全員が署名していないものはどれですか？」 → 日付とhave_editors_signed=falseを指定してlist_heu_documents 「PDF 42の署名依頼を取り消してください。誤った相手に送ってしまいました」 → cancel_pdf_document

---

把握しておくべき動作と制限事項

内容	制限／動作
API レート制限	300 リクエスト／5 分（レスポンスのヘッダー X-RateLimit-*。上限を超えると、Retry-After を含む 429 が返されます）
署名リマインダー	文書ごとに 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 キーは環境変数からのみ読み取られます。コード内、レスポンス、ログに含まれることはありません。
• 外部に影響を及ぼすツール（✋）は、ユーザーに必ず明示的な確認を求めるよう設定されています。
• ダウンロードしたファイルはローカルのファイルシステムに保存されます。

開発

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 パッケージ