manifestlens

manifestlens

希望供 Agent 使用的 API 会发布 Agent Manifest：一个小型 JSON 文档，用于说明 API 的内容、 Agent 可以调用哪些端点，以及适用哪些限制。manifestlens 是 Agent Manifest Protocol 的客户端。它会在源站的知名位置查找 manifest，检查 manifest 的结构，将源站提交到公开的 AMP 注册表并跟踪提交状态；此外， 它还会在每次调用前执行一项值得做的检查——根据你持有的 manifest，判断预期操作是否确实获准。

整个过程中无需 API 密钥。manifest 探测和 注册表都是公开的；两个本地工具绝不会离开本机。

配置

• AMP_REGISTRY_BASE_URL（可选）——注册表工具的 基础 URL。默认为 https://api.agent-manifest.com。
• AMP_FETCH_TIMEOUT_MS（可选）——应用于 manifest 获取的超时时间。默认为 15000。

工具

• fetch_manifest_by_domain——给定一个 domain（裸 主机名，或会剥除协议和路径的 URL），它会依次请求 https://<host> 下的 /.well-known/agent-manifest.json、 /.well-known/amp.json 和 /agent-manifest.json，并返回 第一个有响应的 manifest，以及获胜的 manifest_url、 origin 和 tried_urls 列表。 如果都没有响应，则会失败并返回 no AMP manifest found for <host> (tried 3 URLs)。
• validate_manifest_syntax——检查以 对象或 JSON 字符串形式提供的 manifest。它会应用下文所述 AMP schema 的结构子集，并返回带有以下成功令牌的 valid: true：amp-schema-valid:<spec_version>:<name>；或者返回 valid: false，并附上路径/消息错误列表。无法解析为 JSON 的 字符串属于验证失败，而非工具错误。
• submit_api_to_amp_registry——将某个 domain 的 origin 发送到注册表的提交端点 （POST /listings/submit），并原样返回注册表的 JSON 回复。
• check_amp_submission_status——轮询 GET /listings/submit/<submission_id>/status，并 原样返回注册表的 JSON 回复。
• check_agent_permissions——接受一个 action，例如 POST /baking/validate-mix，一个 manifest，以及 可选的布尔值 intends_unauthenticated 和 payment_onboarded（两者默认为 false）。它会返回 一个 verdict——compliant、violation、warning 或 unknown——以及结构化的 findings；如果有声明的路由匹配， 还会返回 matched_endpoint。 Finding 代码包括 endpoint_not_declared（没有 声明的路由与操作匹配）、 auth_required（路由需要身份验证，但操作意图在未验证身份的情况下运行）、 payment_onboarding（路由或 manifest 声明了付款条款，但尚未完成入驻），以及 agent_notes_usage_restriction（manifest 的 agent_notes 中包含限制性措辞，例如 “do not” 或 “only for”）。声明的路由可以使用 {id} 这类模板片段，它们可匹配任意单个路径片段。

注册表故障有两种形式：非 2xx 回复会以 amp registry error: HTTP <status> 失败；无法访问注册表则会返回 amp registry unreachable。 参数验证会在发出任何请求前失败，并返回以下适用错误： domain must be a non-empty string、 manifest must be an object or a JSON string、 submission_id must be a non-empty string、 action must be a non-empty string 或 manifest must be an object。

什么是子集，什么是重建

本次构建中的三个部分在此处和代码中都明确标注：

• 验证子集。 可读记录中没有完整的官方 AMP JSON Schema，因此验证实现了文档所述的结构子集：值 必须是 JSON 对象，spec_version 必须是 agentmanifest-0.2 或 agentmanifest-0.3，name 必须 是非空字符串；如果存在 endpoints，则必须是一个数组， 其中每个对象都带有字符串 path、url 或 route。
• 提交输入和请求体。 原始工具的提交输入未在其 README 中展示；manifestlens 接收 {domain} 并发送 {"origin": "https://<host>"}， 这是一次重建。
• 权限规则机制。 上文记录了判定结果和发现代码；产生这些结果的确切匹配 和优先级机制属于重建。两个发现代码是本地扩展： unparseable_action（操作不以 HTTP 方法开头）和 no_endpoints_declared（清单中完全没有可读取的端点）—— 两者的判定结果都是 unknown。

CLI

每个工具都是一个子命令，接受一个 JSON 参数字符串：

npx @reneturcios/manifestlens fetch_manifest_by_domain '{"domain":"api.example.com"}'
npx @reneturcios/manifestlens validate_manifest_syntax '{"manifest":{"spec_version":"agentmanifest-0.3","name":"My API"}}'
npx @reneturcios/manifestlens submit_api_to_amp_registry '{"domain":"api.example.com"}'
npx @reneturcios/manifestlens check_amp_submission_status '{"submission_id":"sub_123"}'
npx @reneturcios/manifestlens check_agent_permissions '{"action":"POST /baking/validate-mix","manifest":{"endpoints":[{"method":"POST","path":"/baking/validate-mix"}]}}'
npx @reneturcios/manifestlens --version

输出是工具的结果文本。退出码：成功时为 0，运行时错误时为 1（包括验证或上游错误），用法错误时为 2。

MCP 服务

npx -y @reneturcios/manifestlens mcp

MCP 客户端配置：

{
  "mcpServers": {
    "manifestlens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/manifestlens", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/manifestlens
docker run --rm ghcr.io/cloudcorprecords/manifestlens fetch_manifest_by_domain '{"domain":"api.example.com"}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

许可证

MIT — Copyright (c) 2026 Rene Turcios