Token Verdict

token-verdict-mcp

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

一个使用 stdio 传输的 MCP 服务，可将 Token Verdict 作为原生工具提供给任意 MCP 宿主，例如 Claude Desktop、Cursor 或你自己的 Agent 运行时。

Token Verdict 是一款面向 AI Agent、按次付费的代币风险筛查服务：发送代币合约地址，即可获取判定结果（SOLID / CAUTION / DANGER）、0–100 的风险评分、以通俗语言说明的六项加权市场结构信号，以及书面分析意见。在 Base 上每次调用费用为 $0.02 USDC，通过 x402 协议支付——无需账号或 API 密钥；付款即为身份验证。

工具

token_verdict——一个工具，也是服务实际提供的接口：

输入	类型	说明
address	字符串（必填）	代币合约地址（0x...）
chain	字符串，默认值为 "base"	base · ethereum · solana——要分析的代币市场。付款始终在 Base 上以 USDC 结算。

输出为服务的判定 JSON：token、verdict、score、signals（恰好六项）、take 和 market（判定所依据的原始数据，调用方可据此重新核验计算）。仅分析市场结构——不会检查蜜罐模拟和持有者集中度，产品也会在每条分析意见中明确说明这一点。

安装

pip install token-verdict-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	替代选项	包含该密钥的文件路径。
TOKEN_VERDICT_URL	否	覆盖服务基础 URL（默认使用生产环境）。
TOKEN_VERDICT_MAX_AMOUNT_UNITS	否	每次调用的 USDC 微单位支出上限（默认 20000 = $0.02，即已知价格）。客户端拒绝签署价格超过此上限的请求。

未配置签名者时，工具绝不会付款。 收到 402 响应时，工具会将解析后的质询作为结构化错误返回——error: "payment_required"，并附带完整的 accepts 数组（scheme、network、asset、amount、payTo）——这样调用 Agent 就能查看价格并决定如何处理，或使用自己的 x402 客户端结算质询。

MCP 宿主配置

Claude Desktop（claude_desktop_config.json）——其他 stdio MCP 宿主的配置格式相同：

{
  "mcpServers": {
    "token-verdict": {
      "command": "token-verdict-mcp",
      "env": {
        "AGENT_PRIVATE_KEY": "0xYOUR_OWN_WALLET_KEY"
      }
    }
  }
}

从代码检出目录运行，而非安装后运行：

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

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

付款流程

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

1. 不付款向 POST /v1/verdict 发送请求 → HTTP 402，质询以 base64 编码后放在 payment-required 标头中。
2. 从 accepts 中选择 exact / eip155:8453 条目。
3. 构造 EIP-3009 TransferWithAuthorization（validAfter: 0、validBefore: now + maxTimeoutSeconds、随机 32 字节 nonce），并将其作为 EIP-712 类型化数据进行签名；签名使用质询公布的 USDC 域（extra.name / extra.version）。
4. 在 PAYMENT-SIGNATURE 标头中携带该载荷，重试完全相同的 POST。服务会在服务端通过其支付中介（PayAI）验证并结算；结算回执会放在 payment-response 标头中返回。

测试

pip install -e ".[dev]"
pytest

共 14 项测试，所有支付均为模拟（httpx MockTransport，在测试时生成一次性签名者）。402 测试样例是从生产环境捕获的真实挑战；付费流程测试会验证 EIP-712 签名确实可恢复出签名者地址。

安全说明

• 运行时会从环境中读取你的私钥，且仅在本地用于签署支付授权。私钥绝不会被传输——x402 载荷包含的是签名，而非密钥。
• 支出保护机制会将单次调用限制在已配置金额内（默认值：恰好为 0.02 美元的价格）。
• 请使用仅持有工作资金的专用 Agent 钱包运行，就像为任何 Agent 提供资金一样。