Prometeo MCP Server

Prometeo MCP サーバー

Prometeo API に接続するための MCP（Model Context Protocol）サーバー実装です。銀行情報へのアクセス、口座の検証、CURP の照会を行う関数を含みます。

---

🚀 機能

• ✅ Python 3.11+
• ✅ Pydantic v2.x
• ✅ FastMCP との統合
• ✅ Prometeo API SDK

---

📦 要件

• Python 3.11+
• グローバルにインストールされた uv
• API キー（Prometeo に登録して取得してください！）

---

📥 インストール

リポジトリをクローンし、uv で依存関係をインストールします。

git clone https://github.com/prometeoapi/prometeo-mcp.git
cd prometeo-mcp
uv venv
source .venv/bin/activate

依存関係をインストールします（Claude Desktop のような MCP 対応 LLM 環境内で uv run を直接実行する場合は、この手順を省略できます）。

uv pip install -e .

🧠 MCP 対応 LLM でのアプリケーションの実行

このプロジェクトは MCP（Model Context Protocol）との統合をサポートしており、外部サーバーの起動に対応する LLM ツールやエージェント内で実行するように設定できます。

以下に、各種 LLM の設定例を示します。

🤖 Claude Desktop（Anthropic）

Claude Desktop の JSON 設定内で、次のように mcpServers セクションを追加または拡張します。

{
  "mcpServers": {
    "PrometeoAPI": {
      "command": "uv",
      "args": [
        "--directory",
        "/your/path/to/host",
        "run",
        "prometeo_mcp/server.py"
      ],
      "env": {
        "PROMETEO_API_KEY": "your_api_key",
        "PROMETEO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

/your/path/to/host は、お使いのシステム上の完全な絶対パスに置き換えてください。

your_api_key は、Prometeo のサンドボックスキーまたは本番キーに置き換えてください。

🧠 OpenAI GPTs（プラグインまたはツールの使用）

プロセスの起動を通じたツール呼び出し（または LangChain、AutoGen などのエージェントツールチェーン経由）に対応する GPTs では、次のシェルコマンドを使用します。

uv run prometeo_mcp/server.py

これをツール定義または ToolExecutor でラップできます。

🕹️ OpenInterpreter / OpenDevin

{
  "tools": {
    "PrometeoServer": {
      "type": "command",
      "exec": "uv",
      "args": [
        "run",
        "prometeo_mcp/server.py"
      ],
      "cwd": "/your/path/to/host",
      "env": {
        "PROMETEO_API_KEY": "your_api_key",
        "PROMETEO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

/your/path/to/host は、お使いのシステム上の完全な絶対パスに置き換えてください。

your_api_key は、Prometeo のサンドボックスキーまたは本番キーに置き換えてください。

🧪 LangChain（Runnable または Tool 経由）

LangChain のカスタムツールの場合：

from langchain.tools import Tool

prometeo_server_tool = Tool.from_function(
    name="PrometeoServer",
    func=lambda x: os.system("uv run prometeo_mcp/server.py"),
    description="Runs Prometeo API server"
)

---

🛠 ツール

CURP 照会ツール

curp_query

CURP コードを直接指定して、既存の CURP（Clave Única de Registro de Población）を検証し、関連情報を取得できます。この関数は、メキシコの身分証明書を確認し、関連する個人データを取得するために不可欠です。

curp_reverse_query

CURP 自体ではなく、個人の人口統計情報を指定して CURP を取得できます。対応する CURP を特定するには、氏名、姓、性別、生年月日、登録州が必要です。

---

口座検証ツール

validate_account

アルゼンチン、ブラジル、コロンビア、チリ、エクアドル、メキシコ、ペルー、ウルグアイ、および米国の銀行口座情報を検証します。この関数は、口座が存在するかを確認し、口座名義人の詳細を返します。CLABE（メキシコ）、CBU/CVU（アルゼンチン）、CCI（ペルー）、PIX キー（ブラジル）など、さまざまな口座番号形式に対応しています。

get_validation_result

以前に開始した口座検証リクエストのステータスまたは結果を取得します。銀行システムでの処理に時間がかかる場合がある非同期検証に特に便利です。

get_tasks

システムタスクとそのステータスに関する情報を取得します。この関数は、バックグラウンドプロセスの監視やシステム全体の状態の把握に役立ちます。

---

銀行接続ツール

banking_login

ユーザーの認証情報を認証して、銀行プロバイダーへの接続を確立します。多要素認証が必要な場合は、後続の操作に使用できるセッションキーを返します。二要素認証が必要な場合、この関数は OTP（ワンタイムパスワード）が必要であることを通知します。

banking_get_accounts

認証済みの銀行セッションに関連付けられたすべての口座の一覧を取得します。ユーザーのログインに成功すると、口座番号、口座種別、残高、その他の関連情報を確認できます。

banking_get_movements

指定した期間内の特定の口座の取引履歴（入出金）を取得します。この関数には、有効なセッションキー、口座番号、通貨コード、および取引の対象期間が必要です。

banking_logout

有効な銀行セッションを安全に終了し、認証トークンとセッションデータを適切にクリーンアップします。

---

クロスボーダーツール

crossborder_create_intent

destination_id、concept、currency、amount、customer、external_idを使用して、クロスボーダーの入金インテントを作成します。入金方法には、バーチャル口座（MX）またはQRコード（BR、PE）を利用できます。

crossborder_create_payout

現地の決済ネットワークを利用するクロスボーダーの出金振込を作成します。MXではSPEI、BRではPIX、PEではCCEを使用します。

crossborder_get_intent

intent_idを指定してクロスボーダーの入金インテントを取得します。インテントのステータスを確認できます。

crossborder_get_payout

payout_idを指定してクロスボーダーの出金振込を取得します。出金のステータスを確認できます。

crossborder_list_intents

すべてのクロスボーダー入金インテントを一覧表示します。

crossborder_list_payouts

すべてのクロスボーダー出金振込を一覧表示します。

crossborder_refund_intent

クロスボーダーの入金インテントを返金します。インテントのステータスがSettledの場合にのみ返金できます。

crossborder_create_customer

クロスボーダーの顧客を作成します。顧客は入金と出金に使用します。入金に使用する場合、create_intent関数の呼び出し時にQRコードまたはバーチャル口座が作成されます。出金に使用する場合は、出金を実行するための出金口座が必要です。

crossborder_get_customer

customer_idを指定してクロスボーダーの顧客を取得します。

crossborder_list_customers

すべてのクロスボーダー顧客を一覧表示します。

crossborder_update_customer

クロスボーダー顧客のデータを一部またはすべて更新します。

crossborder_add_withdrawal_account

クロスボーダー顧客に出金口座を追加します。顧客が複数の出金口座を持つ場合、この出金口座がデフォルトで選択されます。

crossborder_select_withdrawal_account

クロスボーダー顧客の出金口座を選択します。顧客が複数の出金口座を持つ場合に便利です。

crossborder_get_accounts

現在の加盟店（割り当てられたAPIキー）のすべての口座を取得します。

crossborder_get_account

account_idを指定して加盟店口座を取得します。

crossborder_get_account_transactions

account_idを指定して、加盟店口座のすべての取引を取得します。

---

OpenAPI リソース

openapi://all

利用可能なすべてのOpenAPIリソースを一覧表示します。この一覧から読み込むリソースを選択できます。

openapi://{document_id}

IDを指定して特定のOpenAPIリソースを読み込みます。このリソースから、Prometeo APIと連携するクライアントコードを生成できます。

---

💡 プロンプトの例

サポート対象のLLMを介してこのMCP サーバーを操作する方法については、次をご覧ください。

📁 examples/prompts.md

このファイルには、Claude、ChatGPT（MCP対応）、またはその他の互換性のあるLLMにコピーして貼り付け、実際のサーバー呼び出しを実行して動作をテストできるプロンプトの例が記載されています。

---

🧪 テストの実行

このプロジェクトではpytestとpytest-asyncioを使用します。

pytest

非同期テストには必ず@pytest.mark.asyncioを付けてください。

---

🛠 開発

仮想環境を有効にします。

source .venv/bin/activate
uv pip install -e .[dev]

アプリケーションを実行します。

uv run prometeo_mcp/server.py

📄 ライセンス

MIT Licenseです。詳細はLICENSEをご覧ください。

👥 コントリビューション

コントリビューションを歓迎します。課題を登録するか、プルリクエストを送信してください。