ar-agents

@ar-agents/mcp

一个 MCP 服务，整合了整个 @ar-agents/* 工具包：CUIT 验证、AFIP/ARCA 纳税人名册查询、身份证明、MercadoPago Payments + Subscriptions + Cuotas、WhatsApp Business，可接入任何 MCP 宿主（Claude Desktop、Cursor、Codeium、Continue、Cline 等）。

这是什么

此软件包是围绕 @ar-agents/* 软件包封装的 MCP 服务。如果你直接使用 Vercel AI SDK 6 构建 Agent，则不需要此服务：安装各个软件包即可。如果你想在 Claude Desktop、Cursor、Codeium 或任何 MCP 宿主中使用 AR 工具包，这就是一站式安装方案。

治理：默认启用 art. 102 审批门槛

此服务会动用真实资金（Mercado Pago）、申报真实税务（AFIP/ARCA），并且可以设立真实公司（IGJ）。阿根廷《自动化公司制度》（art. 102）要求由人类管理员对这些行为负责，并禁止将此类监督职责委托给他人。因此，默认情况下，此服务会强制执行治理审批门槛：

• READ 级工具（例如 validate_cuit、lookup_cuit_afip、search_payments）始终运行：无需审批。
• 涉及资金、税务、法律、不可逆操作（或无法分类）的工具，若未接入人工审批钩子，则会被拒绝。拒绝时会返回清晰的 MCP 错误，告知你该如何处理——任何资金、税务或法律工具都不会在无提示的情况下执行。

分类时会使用本地 Agent 采用的同一份 @ar-agents/core 风险清单（classifyTool / levelRequiresApproval），并传入每个工具的 name、description 和 sideEffects。审批门槛在工具执行之前生效，因此被拒绝的调用不会访问网络。

影响范围：该门禁采用默认拒绝策略，因此部分读取工具也会受门禁控制

分类依据是名称（以及描述 / sideEffects）。unknown 类采用默认拒绝策略——任何名称不属于已识别读取动词的工具，都会被视为 unknown，并默认启用门禁。 接入所有注册表后，约 145 个已暴露工具中有 65 个会受门禁控制，目前其中包括一些名称不符合读取动词启发式规则的真正读取工具：

类别	当前默认启用门禁的读取工具
IGJ 注册表读取	igj_get_entity、igj_search_entities、igj_get_autoridades、igj_get_domicilios、igj_get_asambleas
Boletín Oficial 读取	bo_search、bo_today、bo_get_norma、bo_list_subscriptions
签名验证读取	firma_inspect_cert、firma_verify_chain、firma_verify_cms_signature、firma_is_onti_issued
AFIP 目录读取	obtener_alicuotas_iva、obtener_tipos_comprobante、obtener_tipos_documento、obtener_tipos_concepto、obtener_tipos_moneda
配送读取	trackear_envio、listar_sucursales
其他	lookup_credit_situation、mp_health_check

这是有意设置的故障安全行为（宁可对读取操作设门禁，也不让未知工具悄悄转移资金），而不是针对“这些工具有危险”的逐工具允许列表。 若要查看你的配置中每个工具的确切解析风险级别，请运行：

ar-agents-mcp doctor

其中的 GOVERNANCE 部分会列出每个已暴露工具、其解析后的风险级别，以及根据你当前环境变量该工具是否受门禁控制——升级前后都能看到确切的影响范围。若要运行受门禁控制的读取工具（以及任何需要审批级别的工具），可以接入审批钩子（见下文），或设置 AR_AGENTS_MCP_ENFORCE=off（不启用门禁——不建议用于自主执行资金、税务或法律相关操作）。将这些名称重新分类为 read，以便它们通过门禁，同时继续拦截实际操作，是对跨包风险清单的另一项独立且有意的更改；该更改在本次发布范围之外跟踪。

接入人工审批（HITL）

在自己的 Node 应用中嵌入服务时：

import { createServer } from "@ar-agents/mcp";

const { server } = await createServer({
  governance: {
    // Called before any money/fiscal/legal/irreversible/unknown tool.
    // Return true to proceed, false (or throw) to refuse.
    approve: async (toolName, args) => askHumanAdministrator(toolName, args),
    // Optional kill-switch: when it returns true, EVERY tool refuses.
    isHalted: async () => isSocietySuspended(),
  },
});

选择退出（不设门禁的直通模式）

若要恢复旧行为，让每个工具都不经门禁直接运行，请设置：

"env": { "AR_AGENTS_MCP_ENFORCE": "off" }

解析优先级：显式的 createServer({ governance: { enforce } }) 选项 > AR_AGENTS_MCP_ENFORCE 环境变量 > 默认启用。启动摘要（输出到 stderr）会显示当前模式，例如 governance → enforce=ON (art. 102 gate · NO approve hook → fail-closed DENY)。

紧急停止开关

设置 AR_AGENTS_MCP_HALT=1（或接入 governance.isHalted）即可暂停整个社会：所有工具，无论是否为读取工具，都会拒绝执行并返回 society_suspended 错误。默认不暂停——除非你接入该功能，否则行为不会改变。

环境变量	默认值	效果
AR_AGENTS_MCP_ENFORCE	on	off 会禁用 art. 102 门禁（不设门禁的直通模式）。
AR_AGENTS_MCP_HALT	未设置	1 会暂停所有工具（society_suspended）。

快速开始（Claude Desktop）

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

{
  "mcpServers": {
    "ar-agents": {
      "command": "npx",
      "args": ["-y", "@ar-agents/mcp"],
      "env": {
        // All env vars are optional: set the ones for the integrations you need.
        // Without any: only `validate_cuit` (algorithm-only) is available.

        // MercadoPago: enables 21 payment / subscription tools
        "MP_ACCESS_TOKEN": "TEST-...-or-APP_USR-...",
        "MP_BACK_URL": "https://yourapp.com/done",

        // AFIP/ARCA: enables `lookup_cuit_afip` (real padron data)
        "AFIP_CUIT_REPRESENTADO": "20XXXXXXXXY",
        "AFIP_CERT_PEM": "-----BEGIN CERTIFICATE-----\n...",
        "AFIP_KEY_PEM": "-----BEGIN PRIVATE KEY-----\n...",
        "AFIP_ENV": "prod", // or "homo"

        // WhatsApp Business: enables 6 messaging tools
        "WA_ACCESS_TOKEN": "EAA...",
        "WA_PHONE_NUMBER_ID": "...",

        // Identity Attestation: enables 5 verification tools
        "ATTEST_SIGNING_SECRET": "openssl rand -hex 32 result here",
        "BUSINESS_NAME": "Your Company",
        "RESEND_API_KEY": "re_...",                // optional, enables email_magic_link adapter
        "ATTEST_CALLBACK_URL": "https://yourapp.com/api/identity-attest/callback",
        "ATTEST_FROM_EMAIL": "[email protected]"
      }
    }
  }
}

重启 Claude Desktop。找到扳手图标 → ar-agents 工具应会显示。

快速开始（Cursor）

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "ar-agents": {
      "command": "npx",
      "args": ["-y", "@ar-agents/mcp"],
      "env": {
        "MP_ACCESS_TOKEN": "TEST-...",
        // ... same env vars as above
      }
    }
  }
}

重启 Cursor。工具会显示在聊天面板的工具选择器中。

快速开始（其他 MCP 主机）

方法相同。任何支持 MCP stdio 服务的主机都可以：

• Codeium：在 Settings → MCP servers 中设置
• Continue：~/.continue/config.json → experimental.modelContextProtocolServers
• Cline：cline_mcp_settings.json

可用工具

工具集取决于设置了哪些环境变量。如果没有设置任何环境变量，则只会注册 validate_cuit（仅算法）。设置所有环境变量后：

来源	工具
@ar-agents/identity（始终启用）	validate_cuit、lookup_cuit_afip（设置 AFIP 变量时）
@ar-agents/identity-attest（设置 ATTEST_SIGNING_SECRET 时）	list_verification_methods、request_identity_verification、submit_otp_code、check_verification_status、get_attestation
@ar-agents/mercadopago（设置 MP_ACCESS_TOKEN 时）	21 个工具：create_payment_preference、create_payment、search_payments、refund_payment、calculate_installments、create_subscription、create_customer、list_customer_cards、list_payment_methods、get_account_info、cancel_payment、capture_payment、list_refunds、get_payment、get_payment_preference、find_customer_by_email、delete_customer_card、pause_subscription、resume_subscription、cancel_subscription、get_subscription_status
@ar-agents/whatsapp（设置 WA 变量时）	6 个工具：send_whatsapp_text、send_whatsapp_template、send_whatsapp_media、send_whatsapp_buttons、send_whatsapp_list、mark_whatsapp_read

单次 MCP 安装最多可为 AR Agent 提供 34 个工具。

验证是否正常运行

直接运行二进制文件，查看已注册工具摘要：

npx @ar-agents/mcp
# Outputs to stderr (stdout is reserved for MCP protocol):
#   [email protected] starting with N tools registered:
#     identity      → validate_cuit + lookup_cuit_afip (AFIP cert configured)
#     mercadopago   → PROD mode · back_url=...
#     whatsapp      → phone_number_id=...
#     identity-attest → whatsapp_otp, email_magic_link

如果看到“not configured”，请检查环境变量是否与各个包的要求相符。

何时使用此包，何时使用单独的包

使用此包（@ar-agents/mcp）	使用单独的包
Claude Desktop / Cursor / Codeium 用户	在自己的 Node 应用中构建 Vercel AI SDK 6 Agent
希望在 IDE 中使用工具包	希望精细控制 Agent 注册哪些工具
不想编写任何代码	已经有 Agent({ tools }) 配置

npm 包和 MCP 服务提供完全相同的功能：工具名称、架构和行为都相同。MCP 服务只是使用了不同的传输方式。

故障排除

“validate_cuit only”：没有显示其他工具 → 你尚未设置任何环境变量。请检查 MCP 配置中的环境变量部分。

MercadoPago 工具调用因 401 失败 → MP_ACCESS_TOKEN 错误或已过期。沙盒中的测试用户有各自的令牌；请勿混用生产环境和测试环境的令牌。

AFIP 的 lookup_cuit_afip 返回“not configured” → 你设置了 MP_ACCESS_TOKEN，但漏掉了 AFIP_CUIT_REPRESENTADO 和证书变量。各项集成彼此独立。

未注册魔法链接适配器（identity-attest） → 你设置了 ATTEST_SIGNING_SECRET，但没有设置 RESEND_API_KEY 和 ATTEST_CALLBACK_URL。适配器需要这两项。

工具名称冲突 → 请在 github.com/ar-agents/ar-agents 提交 issue：如果冲突变得常见，我们会在 v0.2 中为工具名称添加前缀。

许可证

MIT：© Nazareno Clemente

稳定性

此包处于 1.0 之前。根据 npm 约定，0.x 的次版本可能包含破坏性变更。我们会在 CHANGELOG.md 对应的次版本更新条目中记录每项破坏性变更，并明确标注。为避免意外：

# Pin to exact version (recommended for production):
pnpm add @ar-agents/<package>@<exact-version>

我们承诺同一修订版本内不会有破坏性变更；在公共 API 至少连续两个次版本保持稳定后，我们会发布 1.0.0。