使用说明

项目简介

Ranger Agent Kit 是一个用于构建去中心化永续合约交易高级模块化 Agent 的工具包和框架。其核心组件 Ranger Perps MCP 服务器 实现了 Model Context Protocol (MCP)，旨在为 LLM 客户端提供标准化的接口，以便 Agent 可以安全、可扩展地访问交易功能和市场数据。

主要功能点

交易工具 (SOR Tools): 提供获取交易报价、增加/减少/关闭仓位等交易操作工具，允许 Agent 执行自动化交易策略。
数据工具 (Data Tools): 提供丰富的市场数据查询工具，包括持仓信息、交易历史、 ликвидации 数据、资金费率等，帮助 Agent 分析市场和制定决策。
基于 MCP 协议: 遵循 Model Context Protocol 标准，易于与任何 MCP 客户端集成，构建可组合、生产就绪的 Agent 应用。
可扩展性: 模块化设计，方便添加新的数据源、策略或协议适配器。

安装步骤

安装依赖: 确保你的 Python 环境中安装了必要的依赖包 'mcp-agent' 和 'numpy'。
```
pip install mcp-agent numpy
```
配置环境变量: 复制仓库根目录下的 '.env.example' 文件为 '.env'，并根据你的 Ranger Finance API 密钥和 API 服务地址进行配置。你需要设置以下环境变量：
- 'RANGER_API_KEY': 你的 Ranger Finance API 密钥。
- 'RANGER_SOR_BASE_URL': Ranger SOR API 的基础 URL。
- 'RANGER_DATA_BASE_URL': Ranger Data API 的基础 URL。

服务器配置

MCP 客户端需要以下 JSON 格式的配置信息来连接 Ranger Perps MCP 服务器。请注意，你需要将服务器启动起来后，客户端才能连接。

{
  "serverName": "ranger_mcp",
  "command": "python",
  "args": ["-m", "ranger_mcp"]
}

配置参数说明:

'serverName': 服务器名称，这里设置为 "ranger_mcp"。
'command': 启动服务器的命令，这里使用 'python'。
'args': 传递给启动命令的参数，'["-m", "ranger_mcp"]' 表示以模块方式运行 'ranger_mcp' 包，即执行 'perps-mcp/src/ranger_mcp/main.py' 文件。

MCP客户端如何使用此配置: MCP 客户端 (例如基于 'mcp-agent' 库开发的 Agent) 会读取以上 JSON 配置，并使用 'command' 和 'args' 在本地启动 Ranger Perps MCP 服务器进程，并通过标准输入/输出 (stdio) 或其他 MCP 支持的协议与服务器进行通信。

基本使用方法

启动服务器: 在 'perps-mcp/src/ranger_mcp/' 目录下，或者在项目根目录下，运行以下命令启动 Ranger Perps MCP 服务器。
```
python -m ranger_mcp
```
服务器默认通过标准输入/输出 (stdio) 与客户端通信。
使用 MCP 客户端 (Agent): 你可以使用 'mcp-agent' 库构建 MCP 客户端 (Agent) 来连接并使用 Ranger Perps MCP 服务器提供的工具。
- 参考 'ranger-agent-examples/examples/' 目录下的示例 Agent 代码，例如 'single_tool_call_agent.py', 'orchestrator_agent.py' 等。
- 使用 'mcp_agent.mcp.gen_client' 连接到 "ranger_mcp" 服务器。
- 通过 'client.call_tool()' 方法调用服务器提供的各种工具，例如 'sor_get_trade_quote' (获取交易报价), 'data_get_positions' (获取持仓信息) 等。
- 交易工具返回的交易信息 (base64 编码的交易消息) 需要由客户端进一步处理 (例如签名和提交到链上)。

示例代码 (Agent 客户端): 以下代码片段展示了如何使用 'mcp-agent' 连接到 Ranger Perps MCP 服务器并调用 'sor_get_trade_quote' 工具。

import asyncio
from mcp_agent.mcp.gen_client import gen_client

async def main():
    async with gen_client("ranger_mcp") as client: # 默认连接 stdio 上的 "ranger_mcp" 服务器
        print("Connected to Ranger MCP server.")
        tools = await client.list_tools()
        print("Available tools:", [tool["name"] for tool in tools])

        params = {
            "fee_payer": "YourSolanaAccountAddressHere", # 替换为你的 Solana 账户地址
            "symbol": "SOL",
            "side": "Long",
            "size": 1.0,
            "collateral": 100.0,
            "size_denomination": "SOL",
            "collateral_denomination": "USDC",
            "adjustment_type": "Increase"
        }

        try:
            result = await client.call_tool("sor_get_trade_quote", params)
            print("Trade quote result:", result)
        except Exception as e:
            print("Error calling tool:", e)

if __name__ == "__main__":
    asyncio.run(main())

关键词