Stellar Agent Search

stellar-agent-search

stellar-8004 レジストリの上に構築された、読み取り専用のディスカバリーレイヤーです。Stellar メインネット上の ERC-8004 形式の Identity／Reputation／Validation コントラクトを対象とします。 コントラクトの追加もフォークも行わず、既存のオンチェーンレジストリを MCP クライアントに公開します。インデックス化されたレピュテーションは「申告済み」と「検証済み」を明確に区別し、記録されたメインネットトランザクションで、エージェントが別のエージェントを見つける一連の流れを実証します。

npm · GitHub · ドキュメント · エビデンスパッケージ

npm	MCP Registry	リモートエンドポイント	メインネットでの実証
✅ 0.1.0	✅ 公開・検証済み	⏳ 未デプロイ	✅ x402 payment · フィードバック

公式インターフェースは2つありますが、スタックが2つあるわけではありません。TypeScript アプリケーション、登録、署名付き書き込みには、trionlabs/stellar-8004 の正規の @trionlabs/stellar8004 SDK を使用します。MCP クライアントとターミナルでのディスカバリーには、このパッケージを使用します。このパッケージは SDK のバージョンを内部で厳密に固定しています。上流リポジトリにある制限付きの Supabase Studio /mcp は、SSH/IP 制御下で使うデータベース運用ツールであり、エージェントレジストリ用の MCP ではありません。また、このランタイムとして公開してはなりません。統合の境界を参照してください。

AI エージェント、またはユーザー自身が、Stellar メインネット上のオンチェーンの stellar-8004 エージェントを検索、ランキング、審査し、その後 x402（呼び出しごとに USDC を支払う）決済を準備できる、読み取り専用でキー不要の MCP サーバー（および人間向け CLI）です。1つのバイナリで、Model Context Protocol を stdio 経由で Claude Code／Cursor／Windsurf／Cline／VS Code に接続すると同時に、通常のターミナルツールとしても利用できます。別途用意された Cloudflare Worker 実装では、同じ機能をステートレスな Streamable HTTP 経由で公開します。ただし、このリモートエンドポイントはまだ稼働していません。デプロイのカナリアテストに合格するまでは、ローカルの stdio トランスポートを使用してください。

npx -y [email protected] find "a paid web scraper with a good reputation"

---

これが存在する理由：宣言されたデータと、チェーンの読み取りで証明できること

オフチェーンのエージェントディレクトリ（A2A カード、MCP Registry、OASF、NANDA）には、自己申告のエージェントが登録されています。まさにここに信頼の隔たりがあります。ERC-8004 エコシステムに関する2026年の調査（arXiv 2606.26028）では、登録のうち稼働中のエンドポイントを持つものはわずか3～15％であり、「レビュー担当者」の59～91％はシビルであることが明らかになりました。

stellar-8004 は、私たちが把握している限り、メインネットで稼働する唯一の非 EVM ERC-8004 実装です（2026年7月時点で、Stellar メインネットにエージェントが66件あります。get_registry_stats を呼び出すと現在の件数を取得できます）。非 EVM へのデプロイを網羅した公開調査はありません。上記の調査は、Ethereum、BSC、Base のみを対象としています。これらは「登録数とフィードバック量が最も多い3つのチェーン」です。そのため、これは否定されていない主張として捉え、証明済みとは見なさないでください。このサーバーが提供するのは、ディレクトリの一覧では得られない範囲を限定した Reputation コントラクトへの到達性プローブです。現在の処理では、6枠の観測ウィンドウを使って get_clients_paginated を1回呼び出します。コントラクトは、信頼できるクライアント数やカーソルを公開しておらず、期限切れのクライアントインデックスエントリーによって欠落が生じるため、ページが空または短くても、その後に稼働中のクライアントが存在しないことは証明できません。その集合に対して get_summary を呼び出すと、誤った一致または不一致を生み出してしまいます。そのため、このリリースでは get_summary を呼び出さず、評判フィールドも検証しません。プローブを試行して到達できた場合は、理由 client-set-exhaustion-unprovable とともに unavailable を返します。verifiedFields は空で、平均値、フィードバック件数、ユニーククライアント数はいずれも未検証のままです。verified／partial／mismatch は、将来、信頼できる集計値を取得できるようになった場合にのみ使われます。ステータスの全種類は引き続き verified | partial | mismatch | unavailable | skipped です。自己申告の宣伝文（名前、説明、サービスラベル、フィードバックタグ）は引き続き信頼できないデータであり、指示として扱うことはありません（セキュリティを参照）。

このフェイルクローズの境界と、バージョン管理された申告情報に基づくエビデンスのヒューリスティックが、この製品の中核です。正規化された Explorer の品質に、固定のエビデンス強度（0.4 × 上限付きボリューム + 0.6 × 実効的な幅広さ）を乗じます。実効ユニーククライアント数がフィードバック行数を超えることはなく、申告されたクライアントごとの重複行には上限が設けられています。これらは操作コストの代理指標であり、チェーン上の検証、個人証明、シビル耐性を示すものではありません。

---

提供する機能

MCP の3つのプリミティブすべてに対応し、すべて読み取り専用です。

ツール

Tier	Tool	What it does
0 · SOW	find_agent	自然言語での検索 → 順位付けされた候補
	rank_agent	明示的な ID の集合またはクエリを順位付け。申告された評判を3軸で詳細に内訳表示し、範囲を限定したチェーン到達性も確認
	get_agent_profile	詳細なプロフィール：アイデンティティ、機能、申告された評判とコントラクトプローブの制限、最近のフィードバック、未検証の A2A 投影
	list_services	自己申告の x402／MPP エンドポイント候補。稼働状況、所有権、準拠性、支払いはいずれも未検証
1 · complete-core	list_agents	ページネーションとフィルタリングに対応した、順位付け済みの一覧
	leaderboard	範囲を限定したスキャンにおける上位エージェント（クライアント側での3軸順位付けとカバレッジ）
	resolve_agent	任意のハンドル（id / stellar:…#id / owner G-address）→ 正規識別子
	get_agents_by_owner	現在の所有者 API ページ（最大20件のエージェント）。継続時のカバレッジを明示
	get_agent_feedback	最近のオンチェーンレビュー（サニタイズ済み、ラベル付き）
	verify_reputation	フェイルクローズの Reputation コントラクト到達性プローブ。現在、検証済みのフィールドはありません
	get_agent_card	派生した未検証の A2A 形式の投影と x402 のヒント。プロトコル準拠の証明ではありません
	get_registry_stats	件数の正確なクエリと、上限付きのサンプル指標。定義とカバレッジを提示
	get_registry_health	レジストリごとのインデクサーの古さ

ツールごとの完全なリファレンス（入力、出力、デフォルト値）：docs/tools.md。

リソース — stellar8004://（ピン留め可能なコンテキスト）

registry · leaderboard · health · agent/{id} · agent/{id}/card · agent/{id}/feedback · agent/{id}/reputation · owner/{address}。それぞれ、JSON + レンダリング済み Markdown のペイロードを返します。

プロンプト — スラッシュワークフロー

/find-and-vet-agent（主要機能） · /vet-agent · /compare-agents · /prepare-x402-call · /explore-registry。prepare-x402-call は x402 の正確なフローを示し、署名の直前で停止します — この サーバーは鍵を保持しません。

---

クイックスタート

ワンコマンド MCP セットアップ（Claude Code）：

npx -y [email protected] setup --client claude --scope user --handshake

これはパッケージをダウンロードし、Claude Code 独自の CLI を通じてバージョン固定された npx -y [email protected] mcp の stdio 起動を登録した後、実際の MCP initialize + tools/list ハンドシェイクを実行します。冪等性があり、--check --handshake を指定して再実行すると、設定を変更せずに検証できます。また、--dry-run を使うと登録をプレビューできます。Cursor と Codex の例、設定パス、スコープの制限については docs/getting-started.md をご覧ください。他のクライアント向けの手動設定は docs/integration.md にあります。

必要に応じて、まず スキル をインストールしてください — エージェントがツールを呼び出す前に読む使用ガイドです。

npx skills add berkingurcan/stellar-agent-search --skill mcp

ターミナル（人間向け CLI）：

npx -y [email protected] find "web scraper" --x402       # discover
npx -y [email protected] profile 10                       # full profile for agent 10
npx -y [email protected] rank "scraping agents" --json    # rank + fail-closed contract-probe status, machine-readable
npx -y [email protected] services --x402                  # declared paid-endpoint candidates
npx -y [email protected] doctor                           # self-check: env, explorer, RPC, bounded read path
npx -y [email protected] setup --client cursor --scope project --dry-run  # preview client config

初めての方は、docs/getting-started.md から始めてください。

リモートエンドポイントのステータス

ホスト先として想定している URL は https://mcp.stellar8004.com/mcp です。Worker、トランスポートテスト、ルーティング、堅牢化は実装済みですが、ルートはまだデプロイされていません。現在、/mcp はランディングサイトにフォールスルーして 404 を返します。Cloudflare のレート制限ネームスペースをセンチネル値から置き換え、Service Binding を通じて元の呼び出し元の ID が保持されることをライブカナリアで確認するまで、デプロイは意図的に保留されています。まだこの URL をリモート MCP クライアントに設定しないでください。

ランディングページと MCP ランタイムは別々の Worker です。アセット専用のランディング Worker が mcp.stellar8004.com のカスタムドメインを所有し、完全一致する /mcp と /healthz のゾーンルートは、それら2つのパスのみをランタイム Worker に送信します。ランタイムは Cloudflare Service Binding を通じて既存の stellar8004-web API を読み込みます。Supabase への接続、service-role キーの保持、2つ目のインデクサーの作成は行いません。 docs/architecture.md と docs/stellar8004-integration.md をご覧ください。

設定

すべての設定は環境変数で行います（MCP モードでの標準設定）。CLI フラグは環境変数より優先されます （優先順位：フラグ → 環境変数 → デフォルト値）。

環境変数	デフォルト値	用途
STELLAR_NETWORK	mainnet	mainnet または testnet。testnet の場合は、以下のとおり EXPLORER_BASE_URL または REGISTRY_AGENT_IDS も必要です
EXPLORER_BASE_URL	https://stellar8004.com	Explorer HTTP API のベース URL。インデックス対象は mainnet のみです
REGISTRY_AGENT_IDS	—	レジストリモード：エージェント ID を最大 50 個、カンマ区切りで指定します。Explorer を介さず、Identity コントラクトから直接読み取ります。EXPLORER_BASE_URL とは併用できません
STELLAR_RPC_URL	https://mainnet.sorobanrpc.com	Reputation コントラクトへの到達性を範囲限定で確認するプローブ用の Soroban RPC
VERIFY_ONCHAIN	true	プローブを省略するには false を設定します。いずれの場合も、レピュテーションは宣言された情報のみを使用します
RANK_SCORE_MAX	100	v1 互換性の固定アサーションです。100 以外の値は拒否されます

ランキングには、固定されたバージョン管理対象の stellar-agent-search-declared-evidence-v1 ポリシーが使用されます。インデックス済み平均をちょうど 100 で正規化し、0.4 × 上限付きボリューム + 0.6 × 有効な幅 を乗算します。RANK_SCORE_MAX の変更および従来の RANK_W_* 変数はいずれも拒否されるため、デプロイによって公開済みスコアの意味が暗黙に変更されることはありません。

STELLAR_PRIVATE_KEY が設定されていても意図的に無視され、その旨が標準エラーに警告として出力されます。このサーバーは設計上、キーを必要としません。

testnet ではテストネットのデータソースが必要であり、設定されていない場合は起動を拒否します。 デフォルトの Explorer がインデックスするのはmainnet のみですが、STELLAR_NETWORK は Soroban のコントラクトと RPC も選択します。この組み合わせでは、レジストリの行は mainnet、オンチェーン読み取りは testnet となり、2 つのチェーンが 1 つとして扱われます。そのため、次のいずれかを設定しない限り、STELLAR_NETWORK=testnet は起動時に失敗します。

• EXPLORER_BASE_URL。自分で運用する testnet インデクサーを指定します。または
• REGISTRY_AGENT_IDS。レジストリモード（以下を参照）を有効にします。

x402 デモのドライランゲートは、mainnet で DRY_RUN=1 を設定することです。これにより支出は発生しません。

レジストリモード（インデクサーなし）

公開されている testnet インデクサーが存在しないため、サーバーは代わりに、指定したエージェントのリストを Identity コントラクトから直接読み取ることができます。レジストリモードは未リリース（0.1.0 には含まれていません）のため、現時点ではチェックアウトしたリポジトリから実行してください。

npm ci && npm run build
STELLAR_NETWORK=testnet REGISTRY_AGENT_IDS=12,40 node dist/index.js find "inference"

各エージェントについて、Identity コントラクトから URI、ウォレット、オーナーを読み取り（キー不要のシミュレーション）、その後 URI が指す登録ファイル（data: または https:）をデコードして、Explorer 経由の場合と同じプロファイルを作成します。読み取るのは指定したエージェントのみで、登録ファイルを取得するのもそのエージェントに限られます。

許可リストの範囲で動作します（フィルターはローカルで適用）	インデクサーが必要です — INDEXER_REQUIRED を返します
find_agent、list_services、list_agents、rank_agent、get_agent_profile、get_agent_card、verify_reputation	leaderboard、get_registry_stats、get_registry_health、get_agents_by_owner、get_agent_feedback、オーナーアドレスに対する resolve_agent、minExplorerScore フィルター（引数、または「score above 70」のように指定された数値）

レジストリモードでわからないことは、その旨が示されます。コントラクトは列挙できないため、カバレッジには registry-allowlist-only が付き、読み取れなかったエージェントがあれば unreadableAgentIds に一覧表示されます。インデックス済みレピュテーションは存在しないため、結果には source: { kind: "registry", reputationIndexed: false } が含まれます。スコア、フィードバック数、unrated はデータが欠落していることを示すものであり、エージェントにフィードバックがないことを意味しません。mainnet では最小スコアを暗示する「best」や「trusted」などのクエリ語は、ここではフィルターとして適用されません。カバレッジには implied-score-filter-not-applied が付き、概要にもその旨が示されます。provider-kit register で登録されたエージェントは、list_services でマニフェスト URL が未検証の stellar-agent-services サービス項目として表示されます。

---

セキュリティ

• 読み取り専用で、鍵は不要です。 src/ 配下には署名者も書き込み用クライアントも秘密鍵もありません。リポジトリ内で鍵を持つ唯一の主体は、明示的に人間が制御して実行する単独の examples/x402-demo.ts です。
• 標準出力は JSON-RPC 専用です。 すべてのログと診断情報は標準エラー出力に送られるため、プロトコルストリームが破損することはありません。
• 信頼境界。 サーバーが作成する要約テキスト（content[].text）に補間されるのは、型付き、列挙型、数値の値のみです。エージェントが作成する自由記述テキスト（名前、説明、サービスラベル、フィードバックタグ）はすべて、構造化出力のラベル付き selfDeclared スロットにのみ格納され、サニタイズ（制御文字、ゼロ幅文字、双方向制御文字を除去）され、長さも制限されます。指示として扱われることはありません。

完全な脅威モデルと情報開示ポリシーについては、SECURITY.md および docs/architecture.md をご覧ください。

---

仕組み

flowchart LR
    A["MCP client<br/>Claude Code · Cursor · Windsurf …"] -- "stdio JSON-RPC" --> B["stellar-agent-search<br/>one Node binary · read-only · keyless"]
    T["Terminal (human CLI)"] --> B
    B -- "HTTP" --> C["ExplorerService<br/>stellar8004.com API · primary data"]
    B -- "Soroban RPC" --> D["ReputationVerifier<br/>bounded reachability probe"]
    C -.indexes.-> E[("stellar-8004 contracts<br/>Stellar mainnet")]
    D --> E

ローカル MCP クライアント（またはターミナル）→ 単一の Node バイナリ → ExplorerService（stellar8004 HTTP API、主要データ）と ReputationVerifier（Soroban RPC、範囲を限定した到達可能性プローブ）→ メインネット上の標準 stellar-8004 コントラクト。インデックス化された評判は、明示的に Explorer が宣言したもの のままです。コントラクトプローブは、範囲を限定した到達可能性の観測結果を報告するか、比較を捏造することなく、安全側に倒して利用を停止します。

まだ稼働していないホスト型の経路に追加されるのは、エッジアダプターのみです。リモートクライアント → ステートレスな Cloudflare Worker → 既存の stellar8004-web サービス → 標準の Supabase バックエンドインデックス。Worker が Supabase を直接読み取ることはなく、インデクサーの認証情報も保持しません。同じく範囲を限定した到達可能性プローブには、引き続き Soroban RPC を使用します。アーキテクチャ、ランキング計算式、キャッシュの境界、上流の検出コントラクトについては、docs/architecture.md に記載されています。

分割された MCP v2 パッケージ（@modelcontextprotocol/server および @modelcontextprotocol/client 2.0.0）、Zod 4、@trionlabs/stellar8004、TypeScript ESM、Node ≥ 22 を使用して構築されています。現在、ローカルの stdio ハンドシェイクではプロトコル 2025-11-25 をネゴシエートします。リモートハンドラーは、ステートレスなレガシー互換経路を維持しながら、最新のステートレスプロトコル 2026-07-28 を対象としています。これは実装上の目標であり、リモートカナリアが記録されるまでは、適合性が確認済みであることを示すものではありません。

---

コントリビュート

助成金や SOW に照らして内容を確認していますか？まず docs/evidence.md をご覧ください。技術的な知識がなくても確認できるよう、検証手順を含めて成果物と証拠を対応付けています。

継続案は Stellar Agent Search Phase 2 です。第 1 フェーズでは、ユーザーがエージェントを見つけられるようにします。第 2 フェーズでは、ウォレットと秘密鍵をこの読み取り専用検索サーバーの外に置いたまま、独立した開発者が有料サービスを提供するための標準的な方法を用意します。

既知の未完了作業とリリースの阻害要因は、issues/ で管理しています。課題ごとにファイルが 1 つあります。

バグ報告やプルリクエストを歓迎します。まず CONTRIBUTING.md をお読みください。プロジェクトの構成と、CI が適用する 4 つの不変条件（読み取り専用で鍵不要、標準出力は JSON-RPC 専用、信頼境界、安全側に倒す検証）が記載されています。リリース履歴は CHANGELOG.md をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。