Prometeo MCP Server

Prometeo MCP 服务

用于连接 Prometeo API 的 MCP（模型上下文协议）服务实现。包含访问银行信息、验证账户和查询 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 的大模型环境中运行 uv run，可以跳过此步骤）：

uv pip install -e .

🧠 在兼容 MCP 的大模型中运行应用

此项目支持 MCP（模型上下文协议）集成，可配置为在支持启动外部服务的大模型工具或 Agent 中运行。

以下是不同大模型的配置示例：

🤖 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（通过插件或工具调用）

对于支持通过启动进程调用工具的 GPT（或通过 LangChain、AutoGen 等 Agent 工具链调用工具），请使用此 shell 命令：

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 或工具）

对于 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 关联的信息。此功能对于核验墨西哥身份证件并获取相关个人数据至关重要。

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）或二维码（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 函数时会创建二维码或虚拟账户。如果用于出金，则需要提款账户才能执行出金。

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 交互。

---

💡 提示词示例

如需了解如何通过受支持的大模型与此 MCP 服务交互，请查看：

📁 examples/prompts.md

其中包含示例提示词，你可以复制并粘贴到 Claude、ChatGPT（通过 MCP）或任何其他兼容的大模型中，以触发实际的服务调用并测试行为。

---

🧪 运行测试

此项目使用 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。

👥 贡献

欢迎贡献！请提交 issue 或 pull request。