使用说明

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/<your-user-or-org>/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`):

```bash
# 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 /health`
- `GET /metrics`
- `GET /tools/node_status`
- `GET /tools/node_info`
- `GET /tools/account_overview/{address}`
- `GET /tools/balance/{address}?assetId=0`
- `GET /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)

1. **Milestone 1**
   - Project skeleton
   - `qortal_api.client`
   - `get_node_status`, `get_account_overview`
2. **Milestone 2**
   - Remaining v1 tools (`get_node_info`, `get_name_info`, etc.)
   - More robust error handling, logging, and tests
3. **Milestone 3**
   - Example agent / MCP integration configs
   - Optional extended tools (DEX views, QDN convenience tools)

See **`DESIGN.md`** for the current authoritative plan.

使用说明

Qortal MCP服务器（Python）

概述

状态

安全模型（简称）

公共节点回退（选择加入，实验性）

高层体系结构

需求

快速启动（一旦实施）

MCP集成（初始化+工具）

关于速率限制和日志记录的说明

测试

部署说明

相关 MCP

MCP文本编辑器服务

MCP服务器框架

LLM-MCP桥接器

Avanza 市场数据MCP服务器

印度经纪商投资组合统一视图服务

Cloudflare MCP API 服务器（企业版）