Hacienda Costa Rica

🇨🇷 mcp-hacienda-cr

**Claude、Cursor などの AI アシスタントを、コスタリカ財務省の公開データ（為替レート、納税者の納税状況、IVA や免税情報を含む CABYS コード）に接続する MCP サーバーです。**電子請求書の発行を想定しています。

英語の概要 · ツール · インストール · 仕組み

_{MCP Inspector で、Hacienda の実際の API に対して記録：今日の為替レート、「焙煎コーヒー」の IVA 付き CABYS コード、CNFL の納税状況。}

---

💬 アシスタントに質問できること

「焙煎コーヒーを販売する場合、どの CABYS コードを使い、IVA はいくらですか？」

焙煎コーヒーには 71 個のコードがあります。たとえば、2391102010100（カフェイン抜きではない焙煎豆）は IVA 1% ですが、2391102020000（カフェイン抜きの焙煎コーヒー）は IVA 13% です。

「請求書を発行する前に、企業 3-101-000046 は Hacienda への納税を済ませていますか？」

COMPAÑIA NACIONAL DE FUERZA Y LUZ S.A. · 法人識別番号 · 一般制度に登録済み · 納税済み（滞納も未申告もなし） · 主な事業活動：3510.0、電力の発電、送電、配電。

「今日のドル相場はいくらですか？」 · 「免税 AL-00020402-24 はまだ有効ですか？」

これらは、Hacienda の API に接続したサーバーからの実際の回答です。

---

🧰 ツール

ツール	機能	入力例
tipo_de_cambio	今日の基準為替レート：ドル（買値／売値）とユーロ	—
consultar_contribuyente	名称、識別番号の種類、税制、納税状況、滞納または未申告かどうか、経済活動	3-101-000046
buscar_cabys	説明から CABYS コードを検索し、IVA 税率を表示	café tostado
obtener_cabys	CABYS コードの詳細：IVA とカテゴリ階層	0161001010000
consultar_exoneracion	免税の受益者、割合、有効期間、対象 CABYS	AL-00020402-24

すべて読み取り専用（readOnlyHint）で、Hacienda の公開 API を使用します。登録、トークン、API キーは不要です。

---

📦 インストール

Node.js 18 以降が必要です。

Claude Desktop

claude_desktop_config.json（設定 → 開発者 → 設定を編集）で指定します。

{
  "mcpServers": {
    "hacienda-cr": {
      "command": "npx",
      "args": ["-y", "mcp-hacienda-cr"]
    }
  }
}

Claude Code

claude mcp add hacienda-cr -- npx -y mcp-hacienda-cr

Cursor、VS Code、その他の MCP クライアント

stdio トランスポートで npx -y mcp-hacienda-cr コマンドを使用します。

---

⚙️ 仕組み

flowchart LR
    U["Tú"] --> A["Asistente de IA<br/>(Claude, Cursor…)"]
    A -- "MCP (stdio)" --> S["mcp-hacienda-cr"]
    S -- "HTTPS" --> H["api.hacienda.go.cr"]

• TypeScript と MCP 公式 SDKを使用し、各ツールの入力を Zod で検証します。
• 2 種類の応答： 会話で読みやすいテキストと、モデルが正確なデータを扱うための structuredContent。
• ユーザーに配慮したエラー処理： 形式が無効な識別番号、存在しないコード、Hacienda の API の停止には、例外ではなくわかりやすいメッセージを返します。
• メモリ内キャッシュ： Hacienda の API に過度な負荷をかけないよう、為替レートは 10 分間、それ以外は 1 時間キャッシュします。
• API 呼び出し前にローカルで検証：個人識別番号（9 桁）、法人識別番号または NITE（10 桁）、DIMEX（11～12 桁）、13 桁の CABYS コード。

品質

25 件のユニットテスト	実際に記録した Hacienda の応答を使用した、API クライアントと MCP サーバー全体のテスト（メモリ内の実際の MCP クライアントを使用）
ライブコントラクトテスト	api.hacienda.go.cr に対して実行し、Hacienda が応答形式を変更した場合に検出します
stdio スモークテスト	Claude が実行する場合と同じようにコンパイル済みサーバーを起動し、5 つのツールを呼び出します
CI	プッシュごとに Node 18、20、22 で実行します。ライブコントラクトテストは毎週月曜日にも実行し、API が変更された場合、ユーザーより先に把握できます

npm install
npm test            # unitarios (sin red)
npm run test:live   # contrato con la API real de Hacienda
npm run smoke       # servidor compilado por stdio, de punta a punta

---

⚠️ 注意

データは財務省の公開 API から取得したもので、参考情報です。このプロジェクトは財務省と提携していません。税務上の判断については、会計士または財務省に直接確認してください。

---

🇺🇸 英語の概要

mcp-hacienda-cr は、AI アシスタント（Claude、Cursor など）がコスタリカ財務省の公開 API にクエリできる Model Context Protocol サーバーです。対象となるのは、公式為替レート、納税者の状態（登録済み、滞納中、未申告者、経済活動）、VAT 税率が付いた CABYS の商品・サービスコード、および税控除です。請求書の各明細に CABYS コードと適切な VAT 税率が必要となる電子請求書を対象としています。

API キーは不要です。TypeScript と公式 MCP SDK、Zod による入力検証、テキストと構造化出力、分かりやすいエラー、メモリ内キャッシュ、25 件のユニットテスト、ライブコントラクトテスト、stdio スモークテスト、そして Node 18／20／22 での CI と週次のライブ実行を備えています。

claude mcp add hacienda-cr -- npx -y mcp-hacienda-cr

---

Ney Fred Jiménez Campos · LinkedIn · GitHub · MIT ライセンス