ar-agents

@ar-agents/mcp

@ar-agents/* ツールキット全体をまとめた 1 つの MCP サーバーです。CUIT 検証、AFIP/ARCA のパドロン照会、身元証明、MercadoPago の決済・サブスクリプション・Cuotas、WhatsApp Business を、あらゆる MCP ホスト（Claude Desktop、Cursor、Codeium、Continue、Cline など）で利用できます。

これは何ですか

このパッケージは、@ar-agents/* パッケージを包むMCP サーバーラッパーです。Vercel AI SDK 6 でエージェントを直接構築する場合、これは不要です。個別のパッケージをインストールしてください。Claude Desktop、Cursor、Codeium、またはあらゆる MCP ホストから AR ツールキットを使いたい場合は、これ 1 つをインストールするだけです。

ガバナンス：art. 102 に基づくゲートはデフォルトで有効です

このサーバーは実際のお金（Mercado Pago）を動かし、実際の税務申告（AFIP/ARCA）を行い、実際の会社を設立できます（IGJ）。アルゼンチンの Sociedad Automatizada 制度（art. 102）では、これらの行為に対する責任を人間の管理者が負い、その監督を委任することはできません。そのため、このサーバーではデフォルトでガバナンスゲートが適用されます。

• READ レベルのツール（例：validate_cuit、lookup_cuit_afip、search_payments）は、ゲートなしで常に実行されます。
• 金銭・税務・法務・取り消し不能なツール（または分類できないツール）は、人間による承認フックを設定しない限り、拒否されます。拒否時には、何をすべきかを示す明確な MCP エラーが返されます。金銭・税務・法務に関するツールが、気付かれないまま実行されることはありません。

分類には、ローカルエージェントが使用するものと同じ @ar-agents/core のリスクマニフェスト（classifyTool / levelRequiresApproval）を再利用し、各ツールの name、description、sideEffects を渡します。ゲートはツールの実行前に動作するため、拒否された呼び出しがネットワークにアクセスすることはありません。

影響範囲：ゲートはフェイルクローズのため、一部の READ ツールもゲートされます

分類は名前（および説明／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

合計： 1 つの MCP インストールで、AR エージェント向けに最大 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 エージェントを構築する
IDE でツールキットを利用したい	エージェントに登録するツールを細かく制御したい
コードを書きたくない	すでに Agent({ tools }) のセットアップがある

npm パッケージと MCP サーバーが公開する機能は同一です。ツール名、スキーマ、動作はすべて同じです。MCP サーバーはトランスポートが異なるだけです。

トラブルシューティング

「validate_cuit のみ」と表示され、ほかのツールが表示されない → 環境変数が設定されていません。MCP 設定の環境変数セクションを確認してください。

MercadoPago のツール呼び出しが 401 で失敗する → MP_ACCESS_TOKEN が間違っているか、有効期限が切れています。サンドボックスのテストユーザーにはそれぞれ専用のトークンがあります。本番用とテスト用を混在させないでください。

AFIP の lookup_cuit_afip が「not configured」を返す → MP_ACCESS_TOKEN は設定されていますが、AFIP_CUIT_REPRESENTADO と証明書関連の環境変数が設定されていません。各インテグレーションは独立しています。

Magic-link アダプターが登録されない（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 が連続する 2 回以上のマイナーリリースを通じて安定した時点で、1.0.0 を公開します。