ListSmith

list-smith-mcp

独立リポジトリ： このサーバーは QuincyGB/token-verdict-tools から分離されました。各 MCP サーバーに、ディレクトリへの取り込みと保守のための独自の GitHub リポジトリを持たせるためです。PyPI パッケージ名（list-smith-mcp）、バージョン、インストールコマンドに変更はありません。

MCP サーバー（stdio トランスポート）で、Claude Desktop、Cursor、独自のエージェントランタイムなど、あらゆる MCP ホスト向けに ListSmith をネイティブツールとして公開します。

ListSmith は、x402 サービスの Bazaar 検索メタデータを評価し、修正します。/v1/grade（$0.10）は、ルートの検索メタデータで問題となっている箇所（不完全なスキーマ、SDK 検証の失敗、500 文字を超える説明、誤ったアセットアドレス）を項目ごとに示します。/v1/fix（$0.50）は、実際のサンプル出力 1 件から推定した、修正済みでバリデーターに合格する検索パッケージを返します。どちらも x402 プロトコルを介して Base 上の USDC で支払います。アカウントも API キーも不要で、支払いが認証となります。

ツール

list_grade — 診断のみを行い、修正済みのコンテンツは返しません。

入力	型	説明
resource_url	string（必須）	評価する x402 リソースの完全な URL
sample_output	any（任意）	エンドポイントからの実際のレスポンスボディ 1 件。指定した場合、エンドポイントが公開している出力スキーマとの照合も行います

出力：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（必須）	エンドポイントからの実際のレスポンスボディ 1 件。修正後の出力スキーマはこのサンプルのみから推定され、何も作り出しません
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）を含みます。これにより、呼び出し元のエージェントは価格を確認して対応を決めるか、独自の 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。チャレンジが payment-required ヘッダーに Base64 エンコードされて返されます。
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 ペイロードに含まれるのは署名であり、鍵では ありません。
• ルートごとの支出ガードにより、1 回の呼び出しで使用できる金額は設定値に制限されます （デフォルトは、grade が正確に $0.10、fix が $0.50 の価格です）。
• 他のエージェントに資金を入れる場合と同じように、運用資金のみを保有する専用の エージェントウォレットを用意して実行してください。