Stellar Agent Search

stellar-agent-search

基于 stellar-8004 注册表的只读发现层——Stellar 主网上采用 ERC-8004 风格的 Identity/Reputation/Validation 合约。 它不添加任何合约，也不分叉任何项目：它将现有的链上注册表开放给 MCP 客户端，将已索引的信誉明确区分为已声明和已验证，并通过记录在案的主网交易证明完整的 Agent 寻找 Agent 流程。

npm · GitHub · 文档 · 证据包

npm	MCP 注册表	远程端点	主网证明
✅ 0.1.0	✅ 已发布并验证	⏳ 尚未部署	✅ x402 付款 · 反馈

这里有两个官方接口，而不是两份重复的技术栈。TypeScript 应用、注册和签名写入使用来自 trionlabs/stellar-8004 的规范 @trionlabs/stellar8004 SDK；MCP 客户端和终端发现则使用此软件包，该软件包在内部精确锁定了该 SDK。上游仓库受限的 Supabase Studio /mcp 是受 SSH/IP 控制的数据库运维工具，并非 Agent 注册表 MCP，绝不能将其暴露为此运行时。请参阅集成边界。

这是一个只读、无需密钥的 MCP 服务（以及面向用户的 CLI），可让 AI Agent——或你——在 Stellar 主网上发现、排名和审查链上的 stellar-8004 Agent，然后准备一笔 x402（按次调用支付 USDC）付款。一个二进制程序通过 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"

---

为什么存在：声明的数据与链上读取所能证明的内容

链下 Agent 目录（A2A cards、MCP Registry、OASF、NANDA）列出的是自行声明的 Agent。信任鸿沟恰恰就在这里。2026 年一项针对 ERC-8004 生态的研究（arXiv 2606.26028）发现，只有 3–15% 的注册项拥有可访问的在线端点，而 59–91% 的“评审者”都是 Sybil。

据我们所知，stellar-8004 是唯一一个在主网上运行的非 EVM ERC-8004 实现（截至 2026 年 7 月，Stellar 主网上有 66 个 Agent；get_registry_stats 返回当前数量）。目前没有已发表的调查统计非 EVM 部署情况——上述研究仅考察 Ethereum、BSC 和 Base，即“注册量和反馈量最高的三条链”——因此应将其视为尚未被反驳，而非已获证明。这个服务提供了目录列表无法提供的内容：有界的 Reputation 合约可达性探测。当前流程会调用一次 get_clients_paginated，使用六个槽位的观测窗口。合约没有提供权威的客户端数量或游标，且已过期的客户端索引条目会造成空缺，因此即便返回的页面为空或条目很少，也无法证明后面不存在仍有效的客户端。对这组数据调用 get_summary 会制造虚假的匹配或不匹配；因此本次发布不会调用该方法，也不会验证任何声誉字段。探测尝试可达时，会返回 unavailable，原因是 client-set-exhaustion-unprovable；verifiedFields 为空，平均值、反馈数量和唯一客户端数都仍未验证。verified/partial/mismatch 将保留给未来的权威聚合结果。完整状态集仍为 verified | partial | mismatch | unavailable | skipped。自行声明的营销文本（名称、描述、服务标签、反馈标签）仍是不可信数据，绝不是指令（参见安全性）。

这种失败即关闭的边界，加上版本化的声明证据启发式，构成了本产品。归一化后的 Explorer 质量会乘以固定的证据强度（0.4 × 封顶后的数量 + 0.6 × 有效广度）。有效唯一客户端数不会超过反馈行数，并且每个声明客户端对应的重复行数设有上限。这些是操纵成本的代理指标，不代表链上验证、真人身份验证或 Sybil 抵抗能力。

---

提供的功能

全部三种 MCP 原语，均为只读：

工具

层级	工具	功能
0 · SOW	find_agent	自然语言发现 → 排名后的候选项
	rank_agent	对明确指定的 ID 集合或查询结果进行排名，提供完整的 3 轴声明声誉细分及有界链上可达性探测
	get_agent_profile	深度资料：身份、能力、声明声誉及合约探测限制、近期反馈、未经验证的 A2A 投影
	list_services	自行声明的 x402/MPP 端点候选项；在线状态、所有权、合规性和支付情况仍未经验证
1 · complete-core	list_agents	支持分页和筛选的列表，按排名排序
	leaderboard	有界扫描中的顶级 Agent（客户端侧 3 轴排名及覆盖率）
	resolve_agent	任意句柄（id / stellar:…#id / 所有者 G-address）→ 规范标识符
	get_agents_by_owner	所有者当前 API 页面（最多 20 个 Agent），并明确标示后续分页的覆盖情况
	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 初始化和 tools/list 握手。此操作是幂等的：使用 --check --handshake 重新运行即可验证而不更改配置，或使用 --dry-run 预览注册信息。Cursor 和 Codex 示例、配置路径及适用范围限制见**docs/getting-started.md。其他客户端的手动配置见docs/integration.md**。

也可以先安装 skill — 这是 Agent 在调用任何内容前会先阅读的使用指南：

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 保留。暂时不要将远程 MCP 客户端配置为使用该 URL。

落地页和 MCP 运行时由不同的 Worker 提供。仅提供静态资源的落地页 Worker 持有 mcp.stellar8004.com 自定义域名；精确匹配 /mcp 和 /healthz 的区域路由只会将这两个路径发送到运行时 Worker。运行时通过 Cloudflare Service Binding 读取现有的 stellar8004-web API。它不会连接到 Supabase、持有服务角色密钥，也不会创建第二个索引器。请参阅**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	—	Registry 模式：以逗号分隔的 Agent ID（最多 50 个），直接从 Identity 合约读取，不使用 explorer。不能与 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，它会被有意忽略（并在 stderr 上发出警告）——该服务从设计上 就是无密钥的。

testnet 需要 testnet 数据源，缺少数据源时会拒绝启动。 默认的 explorer 仅索引 mainnet，而 STELLAR_NETWORK 也会选择 Soroban 合约和 RPC。若将两者配在一起，就会同时得到 mainnet 注册表行和 testnet 链上读取结果——仿佛两条链是一条链——因此，除非设置以下任一项，否则 STELLAR_NETWORK=testnet 会在启动时失败：

• EXPLORER_BASE_URL，指向你运行的 testnet 索引器；或
• REGISTRY_AGENT_IDS，用于启用注册表模式（见下文）。

x402 演示在 mainnet 上的试运行开关为 DRY_RUN=1，不会产生任何支出。

注册表模式（无索引器）

目前没有公开的 testnet 索引器，因此服务可以改为直接从 Identity 合约读取你指定的 Agent 列表。注册表模式尚未发布（不包含在 0.1.0 中），目前请从代码检出目录运行：

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

对于每个 Agent，服务会从 Identity 合约读取 URI、钱包和所有者（进行无密钥模拟），然后解码 URI 指向的注册文件（data: 或 https:），构建与 explorer 路径相同的配置文件。它只会读取你列出的 Agent，也只会为这些 Agent 获取注册文件。

可在允许列表上使用（在本地应用筛选器）	需要索引器——返回 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 筛选条件（参数，或诸如“评分高于 70”的明确数字）

对于注册表模式无法获知的信息，服务会如实说明。合约无法枚举，因此覆盖信息会带有 registry-allowlist-only，并在 unreadableAgentIds 中列出无法读取的 Agent。由于没有索引后的 声誉数据，结果会包含 source: { kind: "registry", reputationIndexed: false }：评分、反馈数量和 unrated 反映的是数据缺失，而不是 Agent 没有反馈。在此模式下，像“最佳”或“可信”这类在 mainnet 上 隐含最低评分的查询词不会作为筛选条件应用；覆盖信息会带有 implied-score-filter-not-applied，摘要也会说明这一点。通过 provider-kit register 注册的 Agent，会在 list_services 中将其清单 URL 显示为未验证的 stellar-agent-services 服务条目。

---

安全性

• 只读且无需密钥。 src/ 下没有签名器、写入客户端或私钥。仓库中唯一使用密钥的主体是独立的 examples/x402-demo.ts，需在人为明确控制下运行。
• 标准输出仅包含 JSON-RPC。 所有日志和诊断信息都写入标准错误，因此协议流不会遭到破坏。
• 信任边界。 由服务端编写的摘要文本（content[].text）仅插入类型化、枚举或数值。所有由 Agent 编写的自由文本（名称、描述、服务标签、反馈标签）仅存放在结构化输出中带标签的 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 协议，同时保留无状态的旧版兼容路径。在记录远程 canary 之前，这只是实现目标，并不代表已通过实时一致性验证。

---

参与贡献

要根据资助协议或工作说明书（SOW）审查本项目？请从 docs/evidence.md 开始——其中提供了交付成果与证据的对应关系，并附有验证步骤，便于没有技术背景的人员核查。

计划中的后续阶段是 Stellar Agent Search Phase 2。第一阶段帮助用户查找 Agent。第二阶段将为独立开发者提供一种标准方式来提供付费服务，同时钱包和私钥仍置于此只读搜索服务之外。

已知待办事项和发布阻塞项记录在 issues/ 中，每个问题对应一个文件。

欢迎提交错误报告和 PR。请先阅读 CONTRIBUTING.md——其中介绍了项目布局以及 CI 强制执行的四项不变量（只读且无需密钥、标准输出仅包含 JSON-RPC、信任边界和以关闭方式降级验证）。发布历史见 CHANGELOG.md。

许可证

MIT——详见 LICENSE。