Alien Probe who

alienprobe-who-mcp

一个 MCP 服务，为任何 Agent 提供一条法律实体信息——LEI、法定名称、司法管辖区、实体状态和注册状态——每次调用支付 $0.05 USDC（Base 网络），通过 x402 付款。无需注册、API 密钥或账户。钱包就是账户。

两个工具：

工具	费用	功能
who_terms	免费	返回标示的价格、网络、收款方和覆盖范围。不会付款。无需钱包即可使用。
who	$0.05，真实资金	返回实体记录。未找到或存在歧义时不收费。

客户端配置

三行配置。适用于 Claude Desktop（claude_desktop_config.json）或 Cursor（.cursor/mcp.json）：

{ "mcpServers": { "who": { "command": "npx", "args": ["-y", "@alienprobe/who-mcp"],
  "env": { "PRIVATE_KEY": "0x...", "MAX_USD_PER_SESSION": "1.00" } } } }

完全移除 env 块后，服务仍会启动——who_terms 可以使用，who 则会以 wallet_not_configured 拒绝调用。这是安全的试用方式。

环境变量

变量	默认值	含义
PRIVATE_KEY	(无)	一个持有少量 USDC 的 一次性 Base 主网钱包。可选。绝不会记录、回显或在工具结果中返回。
MAX_USD_PER_CALL	0.10	单次查询的硬性上限。标示的查询价格为 $0.05。
MAX_USD_PER_SESSION	1.00	此服务进程在重启前所有支出的硬性上限。

请参阅 .env.example。切勿提交真实密钥。请使用不持有其他资产的钱包——约 $1 的 USDC 可支付 20 次查询。本仓库不会说明如何将 USDC 转入 Base；请参阅 https://docs.base.org/base-chain/tools/bridges/。

支出上限

服务会使用普通、未经封装的 fetch 对每次 who 调用进行预检——该路径上不存在签名器——读取 402 响应中标示的价格，然后才作出决定。如果价格超过 MAX_USD_PER_CALL，或会使累计金额超过 MAX_USD_PER_SESSION，服务会拒绝调用，并返回模型可以读取并采取行动的结果：

{
  "error": "spend_cap_exceeded",
  "scope": "per_session",
  "price_usd": 0.05,
  "cap_usd": 1.0,
  "spent_usd_this_session": 1.0,
  "remaining_usd": 0.0,
  "hint": "the session budget is spent; raise MAX_USD_PER_SESSION and restart the MCP server to buy more"
}

一个会话对应一个服务进程。重启客户端会重置计数器，因此单次会话上限只是刹车，而非账本——真正的上限是钱包余额。请将余额控制在较低水平。

返回内容

成功付费的查询会原样返回 API 响应正文，并附上 paid_usd：

{
  "schema_version": "who-lookup.v1",
  "subject": { "type": "who", "value": "apple.com" },
  "answer": {
    "lei": "HWUPKR0MPOU8FGXBT394",
    "legal_name": "Apple Inc.",
    "jurisdiction": "US-CA",
    "entity_status": "ACTIVE",
    "registration_status": "ISSUED",
    "match": { "by": "domain", "rule": "domain_exact" },
    "official_website": "https://apple.com/"
  },
  "source": { "name": "...", "vintage": "...", "coverage": "..." },
  "paid_usd": 0.05
}

q 可以是公司名称、可注册域名或 20 个字符的 LEI。若要消除名称歧义，可在同一字符串中附加司法管辖区："Acme Corp;US-DE"。

paid_usd 表示授权价格，而非收据金额

paid_usd 是服务授权的金额——即 API 在 402 响应中标示、支出上限据此判断的价格。它不是从链上读取的实际金额。

一种会导致该值偏高的情况是：钱包在此定价档位下首次成功查询时，结算金额为 $0（首单免费；这是服务自身的特性，与此客户端无关）。该调用仍会报告 "paid_usd": 0.05。此后的每次调用都会实际转出 $0.05。

服务的会话计数器也会出现同样的偏高情况，这种偏差更安全——它只会让你提前停止，不会让你停得太晚。如果需要准确金额，唯一的收据是链上从你钱包转出的 USDC Transfer 记录。请勿将 paid_usd 用于记账。

免费拒绝结果

以下情况均不会收费，并会以普通工具结果返回，供模型推理——而不是作为异常抛出：

上游状态	结果
400	{"error":"invalid_subject","reason":"empty"}
404	{"error":"not_found","coverage":"..."}
409	{"error":"ambiguous","candidates":[...],"hint":"re-ask with the exact legal_name, then a ;jurisdiction suffix if it still collides"}
503	{"error":"source_unavailable"}

API 只有在能够确定唯一实体后才会收费，因此只要结果仍有歧义，重新询问也不会收费。

本项目不提供的功能

• 不提供街道地址、管理人员或董事信息，也不提供所有权关系图。
• 不会猜测。未命中时返回 404，而不是尽力提供答案。
• 规范化后拉丁字母数字少于 2 个字符的法定名称（中日韩文字、西里尔字母、希腊字母、阿拉伯字母、希伯来字母、泰语）完全不存在于此版本的数据中——所有入口都不提供，不只是名称入口。
• 仅当来源将 LEI 与官方网站关联，且注册域名完全一致时，才匹配域名。子域名不会命中。

开发

npm install
npm test     # 28 contract rows over a mocked fetch: no network, no wallet, no payment
npm run smoke  # spawns the server, drives initialize/tools/list/who_terms over real stdio

npm run smoke 会访问线上端点以获取 402。运行时 PRIVATE_KEY 为空，并断言公布的 amount 为 "50000"（$0.05）。此命令无法付款。

src/core.mjs 包含与传输无关的逻辑，并接收注入的 fetch，因此测试无需钱包。src/index.mjs 仅负责 MCP 接线；@x402/* 和 viem 采用延迟导入，只有在调用已获准付款后才会导入。

基于 @modelcontextprotocol/sdk 1.30.0 构建。完整契约和分发计划请参阅 SPEC.md。

许可证

MIT © Brent Bryson。请参阅 LICENSE。