Hacienda Costa Rica

🇨🇷 mcp-hacienda-cr

MCP 服务可将 Claude、Cursor 和其他 AI 助手连接到哥斯达黎加财政部的公开数据：汇率、纳税人税务状况、含 IVA 税率和免税信息的 CABYS 代码。专为电子开票设计。

英文摘要 · 工具 · 安装 · 工作原理

_{使用 MCP Inspector 录制，连接到财政部的真实 API：今日汇率、“烘焙咖啡”的 CABYS 代码及其 IVA 税率，以及 CNFL 的税务状况。}

---

💬 可以向助手询问什么

“销售烘焙咖啡应该使用哪个 CABYS 代码？税率是多少？”

烘焙咖啡有 71 个代码。例如，2391102010100（未脱咖啡因的烘焙咖啡豆）适用 1% IVA，而 2391102020000（脱咖啡因的烘焙咖啡）适用 13% IVA。

“给公司开票前，3-101-000046 这家公司是否已结清对财政部的欠款？”

COMPAÑIA NACIONAL DE FUERZA Y LUZ S.A. · 法人身份证件 · 已登记在一般税制下 · 状态正常（无欠税，也未漏报） · 主要经营活动：3510.0，电力的生产、输送和分配。

“今天美元汇率是多少？” · “AL-00020402-24 这项免税还有效吗？”

这些都是 MCP 服务通过财政部 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），使用财政部公开 API：无需注册、令牌或 API key。

---

📦 安装

需要 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 验证输入。
• **双重响应：**提供便于阅读的对话文本，以及供模型使用精确数据的 structuredContent。
• **面向用户的错误处理：**身份证件格式无效、代码不存在或财政部 API 宕机时，会返回清晰的提示，而不是抛出异常。
• **内存缓存：**汇率缓存 10 分钟，其他数据缓存 1 小时，避免给财政部 API 造成过大负载。
• 调用 API 前进行本地验证：个人身份证件号（9 位）、法人身份证件号或 NITE（10 位）、DIMEX（11–12 位）；CABYS 代码为 13 位。

质量

25 个单元测试	API 客户端和完整 MCP 服务（使用内存中的真实 MCP 客户端），并采用从 Hacienda 录制的真实响应
实时契约测试	针对 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 是一个 Model Context Protocol 服务，可让 AI 助手（Claude、Cursor 等）查询哥斯达黎加财政部的公共 API：官方汇率、纳税人状态（已注册、欠税或未申报、经济活动）、CABYS 产品／服务代码及其增值税税率，以及税务豁免。它面向电子发票场景；每张发票的每一行都需要 CABYS 代码和正确的增值税税率。

无需 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 许可证