@vouch-tools/cli

vouch check — the npm audit of MCP tools. Reads your project's MCP client config, looks up each declared server's current Vouch behaviour score, and fails (non-zero exit) if any tool scores below your threshold.

npx @vouch-tools/cli check

(Not published yet as of this writing — until it is, run it from inside this repo instead: cd packages/cli && npx tsx bin/vouch.ts check.)

What it checks

It looks for .mcp.json (falling back to mcp.json) in the current directory — the same mcpServers format used by Claude Code, Claude Desktop, Cursor, and most other MCP clients:

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] }
  }
}

For each declared server, it searches Vouch's public API for a matching server (first by the config key, e.g. filesystem; if that finds nothing, by a package name or host guessed from command/args/url) and checks every tool that server has a published score for.

A server that can't be matched, or matches more than one candidate ambiguously, is reported and skipped — never guessed, and never a reason to fail the build. Only an actual measured score below the threshold fails.

Usage

vouch check [--config <path>] [--api <url>] [--threshold <n>] [--json]

| Flag | Default | Meaning | |---|---|---| | --config | auto-detected .mcp.json / mcp.json in cwd | Path to the MCP config to check | | --api | https://vouch.tools | Base URL of the Vouch public API | | --threshold | 70 | Minimum behaviour score (0–100) to pass | | --json | off | Machine-readable report instead of the human-readable listing |

Exit codes

| Code | Meaning | |---|---| | 0 | Every measured tool met the threshold (unmeasured/ambiguous/not-found tools don't count against this) | | 1 | At least one tool scored below the threshold | | 2 | Bad invocation (unknown or missing subcommand) | | 3 | No MCP config found or it declared no servers — nothing was checked |

Real-usage telemetry (opt-in)

@vouch-tools/cli also exports wrapClient(), an SDK for reporting anonymised outcomes from real MCP invocations your own code is already making — never arguments, never responses, never credentials, and nothing is ever sent unless you explicitly opt in:

import { wrapClient } from "@vouch-tools/cli";

const client = new Client(/* ... */);
await client.connect(transport);

// Only tool identity, success/failure, error class, and timing ever leave
// the machine — and only once report:true is set explicitly here.
await wrapClient(client, { report: true, server: { key: "filesystem" } });

await client.callTool({ name: "read_file", arguments: { path: "..." } }); // unchanged, now also reported

Pass { report: true, inspect: true } to log exactly what would be sent instead of sending it. A random id persists to ~/.vouch/reporter-id on first use — stable per machine, never tied to any real identity. Reports are k-anonymised before anything publishes (see docs/methodology/v0.2.md's "Real-usage telemetry" section) and are never blended into a tool's behaviour score.

What this doesn't do yet

Publishing to npm and a packaged GitHub Action wrapper around vouch check are still outstanding — see CLAUDE.md.