list-smith-mcp

An MCP server (stdio transport) that exposes ListSmith as native tools for any MCP host — Claude Desktop, Cursor, or your own agent runtime.

ListSmith grades and repairs the Bazaar discovery metadata of x402 services. /v1/grade ($0.10) itemizes what is broken in a route's discovery metadata — hollow schemas, failed SDK validation, over-500-char descriptions, wrong asset addresses. /v1/fix ($0.50) returns a repaired, validator-passed discovery package inferred from one real sample output. Both are paid in USDC on Base via the x402 protocol — no accounts, no API keys; the payment is the authentication.

The tools

list_grade — diagnosis only, no repaired content:

Output: resource_url, graded_at, reachable, http_status, x402_valid, terms, extension_present, sdk_validation, schema_quality, defects (with severities), score (0–100), and fix_available.

list_fix — the repair:

Output: resource_url, graded_at, ok, failure, score_before, defects, package (description, repaired Bazaar extension, OpenAPI and well-known snippets, instructions, validation results — shipped only if it passes both x402 SDK validators), and notes.

Install

pip install list-smith-mcp     # once published; or from a checkout:
pip install ./mcp-list-smith   # (this directory, inside token-verdict-tools)

Requires Python ≥ 3.10. The server pins the MCP v1 SDK API (mcp>=1.2,<2).

Configuration

All configuration is the operator's own environment — whoever runs this server supplies their own wallet. No key material ships in this package, and the package author never sees your key.

Each route is capped at its own price — the client refuses to sign anything above the route's guard. Without a signer configured the tools never pay. On a 402 they return the parsed challenge as a structured error — error: "payment_required" with the full accepts array (scheme, network, asset, amount, payTo) — so the calling agent can see the price and decide what to do, or settle the challenge with its own x402 client.

MCP host configuration

Claude Desktop (claude_desktop_config.json) — same shape for other stdio MCP hosts:

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

From a checkout instead of an install:

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

Prefer AGENT_KEY_FILE over inlining a key in a config file when your host setup allows it.

How payment works

The client mirrors the standard x402 v2 flow (the same flow used for the fleet's own live cataloging payments):

1. POST /v1/grade or /v1/fix unpaid → HTTP 402, challenge base64-encoded in the payment-required header.
2. Pick the exact / eip155:8453 entry from accepts.
3. Build an EIP-3009 TransferWithAuthorization (validAfter: 0, validBefore: now + maxTimeoutSeconds, random 32-byte nonce) and sign it as EIP-712 typed data against the USDC domain the challenge advertises (extra.name / extra.version).
4. Retry the identical POST with the payload in the PAYMENT-SIGNATURE header. The service verifies and settles through its facilitator (PayAI) server-side; the settlement receipt comes back in the payment-response header.

Tests

pip install -e ".[dev]"
pytest

All payments mocked (httpx MockTransport, throwaway signer generated at test time). The 402 fixtures are the real challenges captured from production; the paid-flow tests verify the EIP-712 signatures actually recover to the signer address, for both routes.

Security notes

• Your private key is read from your environment at runtime and used only to sign payment authorizations locally. It is never transmitted — the x402 payload contains a signature, not a key.
• The per-route spend guards cap any single call at the configured amounts (defaults: exactly the $0.10 grade and $0.50 fix prices).
• Run this with a dedicated agent wallet holding only working funds, the same way you would fund any agent.