Qortal MCP服务器（Python）
概述
此存储库包含 只读Qortal MCP服务器 用Python实现。\ 它公开了精心策划的Qortal核心HTTP API子集（端口 12391)as LLM友好的工具，使代理（Codex、ChatGPT代理等）可以在链上查询 QDN数据没有任何签名或广播交易的能力。
服务器与Qortal Core节点一起运行，并充当安全、结构化的代理 获取以下信息：
- 节点状态和版本
- 账户/余额/姓名信息
- 跨链贸易门户提供
- QDN（Qortal数据网络）搜索元数据
- 组元数据（组列表、成员资格、邀请/请求/禁止）
- 聊天历史元数据（消息、计数、活动聊天）
所有写入/状态更改操作都永久超出范围。
状态
该项目尚处于早期开发阶段。
- v1目标：最小但有用的工具集+稳定的Python服务器：
- 节点： get_node_status, get_node_info, get_node_summary, get_node_uptime - 账户/姓名： get_account_overview, get_balance, validate_address, get_name_info, get_names_by_address, get_primary_name, search_names, list_names, list_names_for_sale （默认情况下仅QORT；通过 include_assets +可选 asset_ids) - 交易： list_trade_offers （AT地址返回为 tradeAddress) - 隐藏交易： list_hidden_trade_offers （贸易门户网站报价失败，数量有限） - QDN： search_qdn （仅元数据；存在时包括名称/标识符） - 聊天： get_chat_messages, count_chat_messages, get_chat_message_by_signature, get_active_chats （可选 decode_text=true 安全时解码明文） - 组： list_groups, get_groups_by_owner, get_groups_by_member, get_group, get_group_members, get_group_invites_by_address, get_group_invites_by_group, get_group_join_requests, get_group_bans - 阻碍： get_block_at_timestamp, get_block_height, get_block_by_height, get_block_by_signature, get_block_height_by_signature, get_first_block, get_last_block, list_block_summaries, list_block_range - 交易： search_transactions, get_transaction_by_signature, get_transaction_by_reference, list_transactions_by_block, list_transactions_by_address, list_transactions_by_creator
get_account_overview 当前返回QORT余额和姓名；这 assetBalances v1中的字段故意留空，以避免大的有效载荷。其他省略或 可选端点（例如，块签名者、铸币信息）列在 DESIGN.md.
计划：可选公共节点回退/NodePool（选择加入；默认为仅本地）。看 DESIGN.md 获取策略和配置说明。
第一个实施里程碑仅关注 get_node_status 和 get_account_overview，然后从那里扩展。
有关完整详细信息，请参阅 DESIGN.md.
安全模型（简称）
- 只读 –无签名、无广播、无POST/PUT/DELETE调用。
- 只有a 列入白名单的GET端点集 在...之下
/admin,/addresses,
/names, /crosschain/tradeoffers, /arbitrary/search，以及一小部分 的 /assets 将永远被使用。
- 工具输入经过验证（地址、名称、服务代码、限制等）。
- 对LLM的输出进行修剪和归一化（没有巨大的二进制blob，没有日志，
没有敏感节点细节）。
- Qortal Core API密钥（如果需要）保存在服务器端，并且从不返回
对于来电者。
- 进程启动时读取配置；集
QORTAL_*在启动服务器之前执行env变量（重新启动以应用更改）。
完整的安全模型记录在 DESIGN.md 并通过 规则在 AGENTS.md.
公共节点回退（选择加入，实验性）
- 默认行为仍然是单节点/本地。必须明确启用回退到公共节点。
- 通过env启用：
QORTAL_ALLOW_PUBLIC_FALLBACK=true加上逗号分隔QORTAL_PUBLIC_NODES列表（例如。，https://api.qortal.org).可选调整：QORTAL_FALLBACK_COOLDOWN_SECONDS（默认值约为30），QORTAL_FALLBACK_HEALTH_CHECK_PATH（默认值/blocks/height),QORTAL_FALLBACK_HEALTH_CHECK_TIMEOUT（默认值~2s）。 - 政策：初级优先；仅在网络错误（连接/超时）时重试另一个节点。任何真正的HTTP响应（包括401/4xxx/5xx）都会停止重试。最近发生故障的节点会被跳过进行短暂的冷却（默认约30秒）。
- API密钥：只发送给受信任的本地节点；从未转发到公共节点。由于缺少身份验证，管理端点在回退时仍可能失败。
- 信任说明：公共节点更改只读数据的信任模型；只有当你接受这种权衡时，才能启用。看
DESIGN.md了解详情。
高层体系结构
- Python 3.11+
- HTTP服务器：FastAPI+Uvicorn（或等效的ASGI服务器）
- Qortal的HTTP客户端：
httpx
- 内部布局（有待完善）：
qortal_mcp/
__init__.py
config.py # base URL, API key path, timeouts, limits
qortal_api/
__init__.py
client.py # thin wrappers around whitelisted Qortal HTTP endpoints
tools/
__init__.py
node.py # node status / info tools
account.py # account + balance + names tools
names.py # name system helpers
trade.py # Trade Portal tools
qdn.py # QDN / arbitrary search tools
server.py # FastAPI app wiring tools to HTTP routes or MCP interface每个工具功能负责：
- 验证输入
- 呼叫一个或多个
qortal_api.client助手 - 将原始Qortal响应映射为LLM的紧凑JSON结果
- 处理和规范错误
看 DESIGN.md 了解每个工具及其底层Qortal的详细信息 端点。
需求
- python 3.11+
- 跑步 核心 启用了HTTP API的节点（默认值
http://localhost:12391)
- 如果您的Core需要API密钥
/admin/*端点，确保MCP
服务器可以读取它（例如从 apikey.txt或环境）。
快速启动（一旦实施）
# 1. Clone the repo
git clone https://github.com//qortal-mcp-python.git
cd qortal-mcp-python
# 2. Create a virtualenv and install dependencies
python -m venv .venv
source .venv/bin/activate # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt
# 3. Configure Qortal Core connection (defaults usually OK)
# e.g. edit config file or set environment variables as described in DESIGN.md
# 4. Run the server (example – adjust module/path once implemented)
uvicorn qortal_mcp.server:app --reload
# (Optional) Quick sanity check against your local Core node
# Override QORTAL_SAMPLE_ADDRESS to another on-chain address if desired.
python scripts/sanity_check.py
# (Optional) Run unit tests
pip install -r requirements-dev.txt
pytest
# (Optional) Live integration tests (require a running Core node)
# Set LIVE_QORTAL=1 and optionally QORTAL_SAMPLE_ADDRESS / QORTAL_SAMPLE_NAME
LIVE_QORTAL=1 pytest tests/test_live_integration.py
## HTTP usage examples
With the server running (default `http://localhost:8000`):
Health
curl http://localhost:8000/health
Metrics snapshot
curl http://localhost:8000/metrics
Node status
curl http://localhost:8000/tools/node_status
Account overview
curl http://localhost:8000/tools/account_overview/QgB7zMfujQMLkisp1Lc8PBkVYs75sYB3vV
Validate address (no Core call)
curl http://localhost:8000/tools/validate_address/QgB7zMfujQMLkisp1Lc8PBkVYs75sYB3vV
Name info
curl http://localhost:8000/tools/name_info/AGAPE
Trade offers (limit=3)
curl "http://localhost:8000/tools/trade_offers?limit=3"
Groups (list first 5)
curl "http://localhost:8000/tools/groups?limit=5"
Group detail + members
curl "http://localhost:8000/tools/group/1" curl "http://localhost:8000/tools/group/1/members?limit=10"
Chat (messages between two addresses)
curl "http://localhost:8000/tools/chat/messages?involving=Qaddress1&involving=Qaddress2&limit=5"
Chat with decoded plaintext (when not encrypted)
curl "http://localhost:8000/tools/chat/messages?involving=Qaddress1&involving=Qaddress2&limit=5&decode_text=true"
Hidden trade offers (limit=3)
curl "http://localhost:8000/tools/hidden_trade_offers?limit=3"
Account overview with bounded assets
curl "http://localhost:8000/tools/account_overview/QgB7zMfujQMLkisp1Lc8PBkVYs75sYB3vV?include_assets=true&asset_ids=1&asset_ids=2"
## MCP集成（初始化+工具）
MCP网关位于 `POST /mcp` 并支持MCP初始化握手
加上标准工具方法。
- **协议版本**: `2025-03-26` （回应客户）
- **支持的方法**:
- `initialize` → 回报 `protocolVersion`, `serverInfo`, `capabilities.tools`
- `tools/list` 或 `list_tools` → 返回工具目录
- `tools/call` 或 `call_tool` → 按名称调用工具
示例 `initialize` 调用调试：
curl -sS -X POST http://127.0.0.1:8000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": { "name": "debug-client", "version": "0.0.1" } } }'
工具调用（初始化后）：
{"jsonrpc": "2.0", "id": 2, "method": "tools/list"} {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "validate_address", "arguments": {"address": "Q..."}}}
工具响应包括 `content` 带a的数组 `text` 项目加a
`structuredContent` JSON结果的副本。工具执行错误集
`isError: true` 并将消息作为文本内容返回。协议级故障
使用JSON-RPC `error` 现场。
显示： `mcp-manifest.json` 点在 `http://localhost:8000/mcp` 带名字
`qortal-mcp-server` 和版本 `0.1.0`。更新终结点以供远程使用。
## 关于速率限制和日志记录的说明
- 一个简单的每工具速率限制器（令牌桶）默认为~5个请求/秒
每个工具都可以保护底层Qortal节点。通过以下方式进行调整 `QortalConfig.rate_limit_qps`.
- 日志记录最少，避免了秘密。通过以下方式调整日志级别 `QORTAL_MCP_LOG_LEVEL`.
- 回复包括 `X-Request-ID` 用于跟踪的标头。
- 日志格式可以通过以下方式切换为JSON `QORTAL_MCP_LOG_FORMAT=json`.每个工具
速率限制可以通过以下代码设置 `per_tool_rate_limits` 如果需要的话。
- `/metrics` 返回进程中计数器（请求、速率限制计数、每个工具的成功/错误）；对于多工设置，请从外部聚合。
## 测试
- 单元测试： `pytest` （或 `pytest --cov=qortal_mcp --cov=tests --cov-report=term-missing` 安装后 `requirements-dev.txt` 其中包括 `pytest-cov`).
- 实时集成（需要正在运行的Qortal节点）： `LIVE_QORTAL=1 pytest tests/test_live_integration.py` （可选设置 `QORTAL_SAMPLE_ADDRESS` / `QORTAL_SAMPLE_NAME`).
## 部署说明
- 与uvicorn或gunicorn+uvicorn工人一起跑步，例如：
- `uvicorn qortal_mcp.server:app --host 0.0.0.0 --port 8000`
- `gunicorn -k uvicorn.workers.UvicornWorker -w 2 qortal_mcp.server:app`
- 每个流程都有速率限制和度量；如果您运行多个worker或在反向代理后面运行，请考虑外部聚合和/或调整 `per_tool_rate_limits`.
- 在反向代理（nginx/caddy/traefik）处终止TLS，如果暴露在本地主机之外，则限制对受信任客户端的访问。
- `/metrics` 返回进程内计数器（请求、速率限制计数、每个工具的成功/错误）。
Once running, the server can be wired into your LLM tooling as an MCP server or as an HTTP tool host, depending on your integration.
Available tool routes (v1)
GET /healthGET /metricsGET /tools/node_statusGET /tools/node_infoGET /tools/account_overview/{address}GET /tools/balance/{address}?assetId=0GET /tools/validate_address/{address}GET /tools/name_info/{name}GET /tools/names_by_address/{address}?limit=...GET /tools/trade_offers?limit=...GET /tools/qdn_search?address=...&service=...&limit=...
Roadmap (short)
- Milestone 1
- Project skeleton - qortal_api.client - get_node_status, get_account_overview
- Milestone 2
- Remaining v1 tools (get_node_info, get_name_info, etc.) - More robust error handling, logging, and tests
- Milestone 3
- Example agent / MCP integration configs - Optional extended tools (DEX views, QDN convenience tools)
See DESIGN.md for the current authoritative plan.