MCPAUDIT

MCP servers hand a language model a list of tools, and the model follows their descriptions as instructions. That makes a tool description an untrusted input with unusual reach: it can contradict its own safety annotations, hide characters, name another server's tools, carry terminal escapes into whatever renders the report, or simply be rewritten after you approved it with no version bump and nothing changing on your side. Meanwhile the specification moved out from under the ecosystem — revision 2026-07-28 removed the initialize handshake — so "does this server follow the spec?" stopped having one answer. There was no single local command that would answer both questions about a server before you connected an agent to it.

Two lanes behind one command, with era resolution in front of both. Point mcpaudit at a command (stdio) or a URL (Streamable HTTP); it probes server/discover, falls back to an initialize handshake, and settles which specification era the server belongs to before a single check runs. Lane A asks whether the server implements the spec correctly, Lane B asks whether it is dangerous, and a separate drift detector answers "has this changed since I approved it?" against a baseline you pinned. Every rule carries its own documented false-positive modes as a required field, and RULES.md is generated from that metadata so the docs cannot drift from the code. Output is terminal, JSON or SARIF, with exit codes designed for CI.

MCP servers hand a language model a list of tools, and the model treats their descriptions as instructions. That is a lot of reach for a string you did not write, fetched from a server you did not audit — and those descriptions can be rewritten after you have approved them, with no version bump and nothing changing on your machine. At the same time the specification moved: revision 2026-07-28 removed the initialize handshake and made server/discover mandatory. mcpaudit is the command that runs before you connect an agent to a server: point it at a command or a URL, and it reports what breaks the spec and what looks dangerous, locally, with nothing installed alongside it.

The first real finding was about the ecosystem rather than any one server. Four official reference servers were audited with the tool at v0.1.0 and the raw --json for each was committed to the repo — all four answer server/discover with an error, complete an initialize handshake, and report protocol 2025-11-25. Nothing ships that speaks the current revision. A conformance suite written straight against 2026-07-28 would have produced a page of red against every real server on earth, which is why era resolution was pulled in front of the entire rule registry: checks that do not apply to a server's era are skipped with a stated reason, never failed. Across those four audits that is four checks skipped per run, and the difference between two findings per server and unusable noise.

The framing was fixed before the first check was written, and it is load-bearing: a first-pass linter that catches common issues, not a security audit. It reads what a server says about itself and applies documented heuristics — it does not sandbox, does not read source, and does not prove anything. That framing is enforced structurally rather than by discipline: falsePositiveModes is a required field on every rule and on every finding the tool emits, so a check that cannot state how it misfires cannot compile. The nine findings across the four reference servers were all hygiene and spec-currency observations, none at error severity, and none needed a disclosure.

A target is either a command or a URL. Commands run over stdio, spawned with shell:false through a hand-written tokenizer so a crafted target string cannot smuggle shell metacharacters; URLs run over Streamable HTTP. Both feed one client that never throws — a hostile server is data, so every request resolves to one of six named outcomes (result, error, timeout, transport-error, invalid-json, invalid-envelope) under caps on line size, body size and stderr. A server that emits garbage, hangs, or dies mid-conversation produces a finding instead of a stack trace.

Era detection sits between the transport and the rules. server/discover is attempted first; a -32601 sends the client down the legacy initialize path. The resolved era is then matched against each rule's declared appliesTo list, and a mismatch produces a skip with a reason recorded in the report — the engine does this before any rule body executes, so an inapplicable check cannot fire at all.

The rule registry holds nine conformance checks (C0–C8) and seven safety checks (S1–S7); surface drift lives outside it because it needs a caller-supplied baseline, which is why src/rules/ holds seven files while the documentation lists eight safety entries. Every rule is self-describing: its metadata — severity, applicable eras, spec reference, CWE, false-positive modes, remediation — lives beside its logic, is copied onto every finding it emits, and is the sole source RULES.md is rendered from. One AuditReport fans out to three renderers: a styled terminal report that respects NO_COLOR and collapses to plain monospace off-TTY, --json, and SARIF 2.1.0. Findings are sanitised before display, because otherwise a server flagged for ANSI injection could inject ANSI into the report flagging it.

The audit that shaped the tool was of the ecosystem, not the code. The current specification revision, 2026-07-28, removed the initialize handshake and made server/discover mandatory — and nothing ships that speaks it. Every one of the four official reference servers audited answers server/discover with an error and falls back to an initialize handshake at 2025-11-25; the committed audit JSON records the era as "legacy" for all four. A flat conformance suite built against the current spec would therefore have failed every real server on contact, which is a tool nobody installs twice. That single finding is why era resolution happens before any check runs.

Six defects, four of them hidden behind a green test suite. The worst: the packed CLI produced no output at all under npx, because the entry-point guard compared import.meta.url against process.argv[1] and npm installs bin as a symlink — every unit test passed throughout, and only running the packed tarball caught it, so npm pack → install into a clean directory → run is now a CI step rather than a pre-release ritual. A determinism check could never fire, because the deliberately-broken fixture's tool names were symmetrical and reversing their order was a no-op; a fourth tool broke the palindrome. S6 scanned raw wire bytes looking for an ESC character that always arrives JSON-escaped, so it was structurally incapable of matching; it now scans decoded text. Four false positives fired at error severity against real reference servers because the word "clearly" matched the destructive verb "clear" with no trailing word boundary — caught by hand-reviewing every finding before the README table was published, and fixed with a two-tier verb model where weak verbs (remove, reset, clear) only count in a tool's name and only beside a stateful object. The rug-pull detector hashed uncanonicalised JSON, so a server that merely reordered its keys would have looked like a deliberate downgrade on every re-audit. And the first version of the weekly spec-drift job was circular: it read the protocol version out of the versioned file, which always matches itself.

Four official reference servers were audited with the raw --json committed under audits/, so the README table is checkable rather than summarised by hand. The totals re-derived from those files: nine findings across the four servers, at info, warn and low severity only — zero at error severity, and no exploitable vulnerability, so no private disclosure was needed. Era-awareness is visible in the same files: each run skips four checks with a stated reason ("applies to modern servers; this one is legacy") instead of failing them, which is the difference between two findings per server and a wall of noise. Calibration is reproducible offline in two commands from the repo — the malicious fixture returns 22 findings, the benign one returns zero — and the packed tarball installs into a clean directory with an empty dependency tree.