trustverdict

trustverdict

Before you connect an agent, a repo, a package or an MCP server, ask whether it deserves trust. trustverdict puts that question to a trust-verification service and brings back its signed answer: a decision you can act on, the one reason that drove it, a 0–100 trust score, and the findings underneath. Eight read-only tools cover the whole surface, and none of them needs an account or an API key — every call is anonymous.

Scan results come back exactly as the service issued them. Nothing is rescored, renamed or summarised locally, because the result is a signed attestation: its value is that it is the service's own output, recomputable offline.

Configuration

One environment variable controls the client:

• AGENTAVOW_URL (optional) — the service base URL. Defaults to https://agentavow.com.

There is no API key and no auth header.

Tools

• scan_repo — scan a public GitHub repo, addressed as owner/name. The answer leads with the decision, a signed 0–100 trust score, and the adoption score.
• scan_package — scan a package by name; an optional ecosystem says which registry it lives on (npm, PyPI, crates, Docker, or Hugging Face).
• scan_mcp_server — point it at a live MCP server url; its tool definitions are checked for poisoning and prompt-injection.
• verify_trust — resolve an agent identity and get its current trust score.
• check_interaction_safety — ask whether a specific interaction (for example delegating work or trading) with an agent is safe.
• lookup_identity — resolve a DID (did:web:… or did:key:…) or search agents by name with one query.
• get_trust_badge — a shields-style badge for an agent: the SVG URL plus ready-to-paste README markdown.
• about_agentavow — how the service reaches a verdict and how to read one. This tool is answered locally and makes no request.

Reading a verdict

Every scan leads with decision — safe, review, or do_not_connect — and the decision_reason that triggered it, followed by a summary, the signed trust_score from 0 to 100, the tier, whether the subject is certified, the adoption score, and the findings. A second, binary verdict (safe or needs_review) carries its own verdict_reason: clean, blocking_findings, thin_coverage, or low_signals. Scan attestations are Ed25519-signed (JWS) and can be recomputed offline.

Validation and errors

Validation runs before any request. An empty or missing argument fails with <arg> must be a non-empty string, and scan_repo additionally requires the owner/name shape, failing with repo must look like owner/name. An upstream non-2xx reply fails with agentavow error: HTTP <status>; an unreachable service fails with agentavow unreachable.

Endpoint provenance

Every request path below is a labelled reconstruction: the service's tool surface, base URL and verdict vocabulary are documented, but the per-tool wire paths are not pinned by the documentation, so these follow the documented base and REST conventions.

• POST /api/scan/repo — reconstruction (scan_repo)
• POST /api/scan/package — reconstruction (scan_package)
• POST /api/scan/mcp-server — reconstruction (scan_mcp_server)
• GET /api/agents/<agent>/trust — reconstruction (verify_trust)
• POST /api/interaction-safety — reconstruction (check_interaction_safety)
• GET /api/identity?q=<query> — reconstruction (lookup_identity)
• GET /api/agents/<agent>/badge — reconstruction (get_trust_badge)

The agent segment in the two GET paths and the q= value are URL-encoded. about_agentavow has no wire at all.

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/trustverdict scan_repo '{"repo":"octocat/hello-world"}'
npx @reneturcios/trustverdict scan_package '{"package":"express","ecosystem":"npm"}'
npx @reneturcios/trustverdict scan_mcp_server '{"url":"https://example.com/mcp"}'
npx @reneturcios/trustverdict verify_trust '{"agent":"did:web:example.com"}'
npx @reneturcios/trustverdict check_interaction_safety '{"agent":"did:web:example.com","interaction":"delegate"}'
npx @reneturcios/trustverdict lookup_identity '{"query":"did:web:example.com"}'
npx @reneturcios/trustverdict get_trust_badge '{"agent":"did:web:example.com"}'
npx @reneturcios/trustverdict about_agentavow '{}'
npx @reneturcios/trustverdict --version

Output is the tool's result text (the upstream JSON on success). 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/trustverdict mcp

MCP client config:

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

Docker

docker run -i ghcr.io/cloudcorprecords/trustverdict
docker run --rm ghcr.io/cloudcorprecords/trustverdict scan_repo '{"repo":"octocat/hello-world"}'

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