ListSmith

list-smith-mcp

独立仓库： 此服务从 QuincyGB/token-verdict-tools 拆分出来，让每个 MCP 服务都有自己的 GitHub 仓库，以便收录到目录并进行维护。PyPI 包名（list-smith-mcp）、版本和安装命令均未更改。

这是一个通过 stdio 传输的 MCP 服务，可将 ListSmith 作为原生工具提供给任何 MCP 宿主——Claude Desktop、Cursor，或你自己的 Agent 运行时。

ListSmith 可为 x402 服务的 Bazaar 发现元数据评分并修复。/v1/grade（$0.10）会逐项列出路由发现元数据中的问题——空洞的架构、SDK 验证失败、超过 500 个字符的描述、错误的资产地址。/v1/fix （$0.50）会根据一个真实样本输出，返回修复后且通过验证的发现信息包。两者均通过 x402 协议在 Base 上以 USDC 付费——无需账户或 API 密钥；付款即为身份验证。

工具

list_grade — 仅诊断，不提供修复内容：

输入	类型	说明
resource_url	string（必填）	要评分的 x402 资源完整 URL
sample_output	any（可选）	端点返回的一个真实响应正文；提供后，还会根据端点发布的输出架构对其进行检查

输出：resource_url、graded_at、reachable、http_status、 x402_valid、terms、extension_present、sdk_validation、 schema_quality、defects（含严重程度）、score（0–100）和 fix_available。

list_fix — 修复：

输入	类型	说明
resource_url	string（必填）	要修复的 x402 资源完整 URL
sample_output	any（必填）	端点返回的一个真实响应正文。修复后的输出架构仅根据此样本推断——不会凭空编造
name	string（可选）	生成的描述中使用的显示名称；若省略，则根据 URL 推导
category	string（可选）	类别（例如 token-risk、search、data、media、monitoring），用于组织描述中的适用场景句子

输出：resource_url、graded_at、ok、failure、score_before、 defects、package（描述、修复后的 Bazaar 扩展、OpenAPI 和 well-known 片段、说明、验证结果——仅当通过 x402 SDK 的两项验证器检查后才会提供）以及 notes。

安装

pip install list-smith-mcp

# Or from a checkout of this repository:
pip install .

需要 Python ≥ 3.10。此服务固定使用 MCP v1 SDK API （mcp>=1.2,<2）。

配置

所有配置都来自操作者自己的环境——运行此服务的人需提供自己的钱包。本包不包含任何密钥材料，包作者也永远不会看到你的密钥。

环境变量	必填	用途
AGENT_PRIVATE_KEY	用于付费调用	持有 Base 上 USDC 的钱包 EVM 私钥（0x...）。用于在本地签署 x402 EIP-3009 授权。
AGENT_KEY_FILE	替代项	包含该密钥的文件路径。
LIST_SMITH_URL	否	服务基础 URL 覆盖项（默认：生产环境）。
LIST_SMITH_GRADE_MAX_AMOUNT_UNITS	否	/v1/grade 的 USDC 微单位消费上限（默认 100000 = $0.10，即已知价格）。
LIST_SMITH_FIX_MAX_AMOUNT_UNITS	否	/v1/fix 的 USDC 微单位消费上限（默认 500000 = $0.50，即已知价格）。

每个路由的消费上限均为其自身价格——客户端拒绝签署超过该路由上限的金额。未配置签名器时，工具绝不会付款。 遇到 402 时，工具会将解析后的挑战作为结构化错误返回——error: "payment_required"，并附带完整的 accepts 数组（scheme、network、asset、amount、payTo）——以便调用它的 Agent 查看价格并决定如何处理，或使用自己的 x402 客户端完成挑战。

MCP 主机配置

Claude Desktop（claude_desktop_config.json）——其他 stdio MCP 主机的配置结构相同：

{
  "mcpServers": {
    "list-smith": {
      "command": "list-smith-mcp",
      "env": {
        "AGENT_PRIVATE_KEY": "0xYOUR_OWN_WALLET_KEY"
      }
    }
  }
}

从代码仓库检出版本运行，而非使用已安装版本：

{
  "mcpServers": {
    "list-smith": {
      "command": "python",
      "args": ["-m", "list_smith_mcp"],
      "env": {
        "PYTHONPATH": "/path/to/list-smith-mcp/src",
        "AGENT_KEY_FILE": "/path/to/your/agent.key"
      }
    }
  }
}

如果主机配置允许，请优先使用 AGENT_KEY_FILE，而不要将密钥直接写入配置文件。

支付方式

客户端采用标准的 x402 v2 流程（与该服务自有的实时目录付款采用相同流程）：

1. 未付款时向 POST /v1/grade 或 POST /v1/fix 发起请求 → HTTP 402，挑战内容以 Base64 编码后放在 payment-required 标头中。
2. 从 accepts 中选择 exact / eip155:8453 条目。
3. 构造 EIP-3009 TransferWithAuthorization（validAfter: 0、validBefore: now + maxTimeoutSeconds、随机生成的 32 字节 nonce），并根据挑战中声明的 USDC 域（extra.name / extra.version），将其作为 EIP-712 类型化数据签名。
4. 在 PAYMENT-SIGNATURE 标头中附上该负载，重新发送内容相同的 POST 请求。服务会在服务器端通过其结算方（PayAI）验证并完成结算；结算收据会通过 payment-response 标头返回。

测试

pip install -e ".[dev]"
pytest

所有付款均为模拟（使用 httpx MockTransport，在测试时生成一次性签名者）。402 测试样例是从生产环境捕获的真实挑战；付费流程测试会验证 EIP-712 签名确实能恢复出签名者地址，并覆盖两个路由。

安全说明

• 运行时会从环境中读取私钥，并且仅在本地用于签署付款授权。私钥绝不会被传输——x402 负载包含的是签名，而非密钥。
• 每个路由的支出限制会将单次调用的费用控制在配置的金额以内（默认值：评分恰好为 $0.10，修复恰好为 $0.50）。
• 请使用专用的 Agent 钱包运行，只存入工作所需资金，和为任何 Agent 充值的方式相同。