manifestlens

manifestlens

APIs that want to be usable by agents publish an Agent Manifest: a small JSON document that says what the API is, which endpoints an agent may call, and what constraints apply. manifestlens is a client for that Agent Manifest Protocol. It finds a manifest at an origin's well-known locations, checks a manifest's shape, files an origin with the public AMP registry and follows the submission, and — the part worth doing before every call — answers whether an intended operation is actually permitted by the manifest you are holding.

No API key is involved anywhere. The manifest probes and the registry are both public; the two local tools never leave the machine.

Configuration

• AMP_REGISTRY_BASE_URL (optional) — base URL for the registry tools. Defaults to https://api.agent-manifest.com.
• AMP_FETCH_TIMEOUT_MS (optional) — timeout applied to manifest fetches. Defaults to 15000.

Tools

• fetch_manifest_by_domain — given a domain (a bare host, or a URL whose scheme and path are stripped), it requests /.well-known/agent-manifest.json, /.well-known/amp.json, and /agent-manifest.json under https://<host>, in that order, and returns the first manifest that answers, together with the winning manifest_url, the origin, and the tried_urls list. When nothing answers, it fails with no AMP manifest found for <host> (tried 3 URLs).
• validate_manifest_syntax — checks a manifest given as an object or as a JSON string. It applies the structural subset of the AMP schema described below and either returns valid: true with a success token of the form amp-schema-valid:<spec_version>:<name>, or valid: false with a list of path/message errors. A string that does not parse as JSON is a validation failure, not a tool error.
• submit_api_to_amp_registry — posts a domain's origin to the registry's submission endpoint (POST /listings/submit) and returns the registry's JSON reply unchanged.
• check_amp_submission_status — polls GET /listings/submit/<submission_id>/status and returns the registry's JSON reply unchanged.
• check_agent_permissions — takes an action such as POST /baking/validate-mix, a manifest, and the optional booleans intends_unauthenticated and payment_onboarded (both default false). It replies with a verdict — compliant, violation, warning, or unknown — plus structured findings, and the matched_endpoint when a declared route matched. Finding codes include endpoint_not_declared (no declared route matches the action), auth_required (the route needs authentication but the action intends to run unauthenticated), payment_onboarding (the route or manifest declares payment terms and onboarding is not complete), and agent_notes_usage_restriction (the manifest's agent_notes contain restriction language such as "do not" or "only for"). Declared routes may use {id}-style template segments, which match any single path segment.

Registry failures share two shapes: a non-2xx reply fails with amp registry error: HTTP <status>, and an unreachable registry with amp registry unreachable. Argument validation fails before any request with 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, or manifest must be an object, as applicable.

What is a subset, and what is a reconstruction

Three parts of this build are deliberately labelled, here and in the code:

• Validation subset. The full official AMP JSON Schema is not in the readable record, so validation implements its documented structural subset: the value must be a JSON object, spec_version must be agentmanifest-0.2 or agentmanifest-0.3, name must be a non-empty string, and a present endpoints must be an array of objects each carrying a string path, url, or route.
• Submit input and body. The original tool's submit input is not shown in its README; manifestlens takes {domain} and posts {"origin": "https://<host>"}, a reconstruction.
• Permission-rule mechanics. The verdicts and finding codes above are documented; the exact matching and precedence mechanics that produce them are a reconstruction. Two finding codes are local extensions: unparseable_action (the action does not start with an HTTP method) and no_endpoints_declared (the manifest carries no readable endpoints at all) — both come with verdict unknown.

CLI

Each tool is a subcommand taking one JSON argument string:

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

Output is the tool's result text. Exit codes: 0 on success, 1 on a runtime error (including a validation or upstream failure), 2 on a usage error.

MCP server

npx -y @reneturcios/manifestlens mcp

MCP client config:

{
  "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"}'

Development

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

License

MIT — Copyright (c) 2026 Rene Turcios