HODLXXI Read-Only

HODLXXI 只读 MCP

公共远程 MCP 服务和独立 FastMCP 包，封装了 26 个列入允许列表的 HODLXXI 机器可读信任接口。

公共远程服务

在支持远程服务的任何 MCP 宿主中使用此 Streamable HTTP 端点：

https://hodlxxi.com/agent/mcp

无需 API 密钥或 OAuth 流程。该服务是公共只读服务。

机器可读发现信息：

https://hodlxxi.com/.well-known/mcp.json
https://hodlxxi.com/.well-known/agent.json
https://hodlxxi.com/agent/capabilities

兼容的客户端可以初始化会话、列出恰好 26 个工具，并调用以下工具：

• hodlxxi_get_agent_discovery
• hodlxxi_get_capabilities
• hodlxxi_get_chain_health
• hodlxxi_get_reputation
• hodlxxi_get_attestations
• hodlxxi_get_operator_continuity
• hodlxxi_get_receipt
• hodlxxi_verify_receipt

规范的 MCP Registry 元数据存储在仓库根目录的 server.json 中，名称为 io.github.hodlxxi/hodlxxi-readonly。

安全边界

• 固定的上游源：https://hodlxxi.com
• 固定的端点枚举；不提供通用 URL 工具
• 仅允许通过 GET 访问列入允许列表的上游运行时接口
• 禁用重定向
• 上游请求超时为 10 秒
• 响应上限为 2 MiB
• 仅允许 JSON 和 application/linkset+json
• 严格验证标识符和分页参数
• 不导入 Flask、不访问数据库、钱包或 LND，不涉及密钥、机密、环境读取、发起支付、创建收据或写入调用
• 使用专用的 systemd sidecar；Flask 单体应用不会执行 MCP 工具
• 公共 nginx 路由仅代理到回环 sidecar

有意排除 GET /agent/jobs/<job_id> 和 GET /agent/readiness/self-scan，因为它们可能会修改服务器状态。

独立验证

远程生产路径已通过外部 macOS 客户端和 Claude 自定义连接器完成验证：

external client -> HTTPS -> nginx -> loopback MCP sidecar -> public HODLXXI runtime surfaces

验证完成了 MCP 初始化、tools/list，以及对 capabilities、chain health 和 reputation 的实时调用。请参阅 docs/MCP_CLIENT_VALIDATION.md。

开发

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"
pytest -q

通过 stdio 运行

hodlxxi-mcp

等效命令：

python -m hodlxxi_mcp

配置本地客户端时，将 MCP 宿主指向虚拟环境中的可执行文件，并使用 stdio 传输。

通过 localhost Streamable HTTP 运行 sidecar

hodlxxi-mcp-http

sidecar 端点固定为：

http://127.0.0.1:8765/mcp

sidecar 传输经过有意限制，仅使用回环地址、无状态 JSON 响应、Host/Origin 保护以及相同的 26 个只读工具。公共访问由单独加固的生产反向代理处理。