list-smith-mcp
[M8ven Score]
Standalone home: This server was split out of QuincyGB/token-verdict-tools so each MCP server has its own GitHub repository for directory ingestion and maintenance. The PyPI package name (list-smith-mcp), version, and install command are unchanged.
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
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:
From a checkout instead of an install:
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):
POST /v1/grade or /v1/fix unpaid → HTTP 402, challenge
base64-encoded in the payment-required header.- Pick the
exact / eip155:8453 entry from accepts.
- 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).
- 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
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.
