Ripwire MCP

ripwire as an MCP server

Auditing somebody's .mcp.json for safety instead → ripwire-security-scan.

Trigger: "wire ripwire into my agent", "set up the ripwire MCP server", or "which ripwire MCP verb answers this?".

The 33 verbs, at a glance: 17 read verbs (analyze, rank_by — the same map, ranked by authority/hub/rrf instead of plain PageRank — for, find_symbol, find_referencing_symbols, grep, cochange, memory_recall, situational_awareness, mentions, owners, lego, batch — N read sub-queries in ONE call — fetch_body, and flags — what is BUILT but DARK here: every compile / CMake option() / getenv gate with its default and the size of the code it guards, the answer to "why don't I see feature X?", and doc_drift — which of the repo's markdown claims are now FALSE: dead file:line anchors, deleted symbols, = N constants and [N] extents the code has since changed; call it before trusting a design doc or audit you did not just write, and slice — per-line def-use rows of ONE variable inside ONE definition, flow=back|fwd|both for the transitive data-flow slice, @FILE:LINE seeds by location and pre-picks the variable the seed line names) + 13 flagship-reflex verbs (exemplar, quality_delta, quality_baseline, impact, uses, affected — which tests transitively reach a changed file/symbol, the pre-PR "what do I run?" reflex — path_between, connect — the minimal joining subgraph over N task symbols — the L4 one-call/B11-parity trio explore, from_trace, edit_check — so an MCP-only agent gets the same write & done reflexes as the CLI — and the CROSS-BRANCH pair whereis / stray_content, which answer "where does this content live?" across every branch: the question git cherry cannot, since it compares commit ancestry and every other verb indexes one worktree. stray_content marks a branch superseded when the live line re-implemented its work, which is exactly the case git cherry calls unmerged forever) + the 3 span-addressed edit verbs (replace_symbol_body, insert_before_symbol, insert_after_symbol). Only find_symbol and find_referencing_symbols attach a stable handle= instead of the body (fetch it only when you need it, via fetch_body); the edit verbs enforce a safety contract (staleness refusal, ambiguity refusal, atomic writes) detailed below and in full in mcp-reference.md.

The server exposes 33 MCP verbs: 17 read verbs (incl. rank_by/fetch_body/flags/slice), 13 flagship-reflex verbs (affected/connect/explore/from_trace/edit_check and the cross-branch pair whereis/stray_content) and 3 edit verbs — ripwire wrap codex --force prints the live count.

Wiring — ripwire wrap <agent> prints the recipe

ripwire wrap claude      # → claude mcp add ripwire -- ripwire --mcp
ripwire wrap cursor      # → JSON mcpServers stanza for .cursor/mcp.json (also: windsurf, gemini)
ripwire wrap codex       # → TOML stanza for ~/.codex/config.toml
ripwire wrap opencode    # → CLI first (AGENTS.md is read automatically); its config key is "mcp", NOT mcpServers
ripwire wrap aider       # → no MCP: ripwire . --for="<task>" > .ripwire-map.txt; aider --read .ripwire-map.txt
ripwire wrap --all       # → auto-detect installed agents, emit each one's config in one run

wrap never edits config itself — it prints; you review and run. Before printing it security-scans ./skills and .agents/skills: a CRITICAL finding blocks the recipe (exit 1) unless you pass --force; WARNs print and continue. Bare ripwire wrap lists the supported agents.

Audit the active Codex surface

Run ripwire <repo> --doctor --agent=codex after install/update or when Codex appears to be using a stale binary, missing a skill, skipping the advisory CLI-first hooks, or starting the wrong MCP executable. This extends the ordinary six-check doctor with four read-only checks over the LIVE environment: PATH binary agreement, exact parity between the installed skills and .ripwire-manifest-v1, executability of all three Codex hook roles, and the configured mcp_servers.ripwire command plus --mcp argument. Failing rows give the exact installer/wrap repair command. The report deliberately emits no config contents or full shell commands, so it is safe to paste for diagnosis; --agent=codex alone refuses because it modifies doctor.

"no project root" / "memory limit reached" / _memory_stop

$HOME, / and system directories are never a project root over MCP — not as the launch directory and not as path=: pass the project directory itself (a server started as ripwire ~ --mcp still answers about ~). A tool call refused with "memory limit reached", or an answer carrying _memory_stop in its envelope, means the memory guard cut or refused the work on a tree too large for the machine: point path= at a smaller root, or raise the limit with --max-memory=<N>[K|M|G] (or RIPWIRE_MAX_MEMORY) on the server's command line. The default (65% of RAM) is silent on real projects.

The read verbs + fetch_body (and when each beats the CLI form)

Every verb takes path (the repo root; memory_recall takes the docs/memory dir). For a split service+client checkout, pass paths: [dir1, dir2, ...] instead — the additive multi-root array (path and paths together is a usage error; the 3 edit verbs accept it too, and land a write in the correct root's real file via its label). The server keeps ONE cached workspace per canonical root set: a paths list is deduped and ordered before it's used as the cache key, so calling with the same roots in a different order still hits the warm cache instead of re-parsing; a genuinely different root set gets its own cache entry, not a shared/stale one.

Line-seeded addressing — @FILE:LINE in any resolver-backed selector. Holding a LOCATION (a diff hunk, a compiler error, a stack frame) instead of a name? Pass @src/foo.cpp:120 (1-based line) as the selector and it resolves to the innermost definition enclosing that line — accepted by find_symbol / find_referencing_symbols / impact / edit_check / path_between (from/to) / connect (each entry) / lego (type) / fetch_body (handle), and by uses (which serves the enclosing definition's NAME — its sites stay name-matched, of= echoes the seed as typed). A bad seed — malformed spec, unmatched or ambiguous path, line past EOF, a line no definition spans, two definitions sharing the line — is refused with the same specific diagnosis the CLI's --at/selector arms speak, never guessed. The NAME-matching scan verbs (owners, mentions) do not resolve seeds; a resolvable seed there refuses by naming the definition it resolves to, so the retry is in the message. CLI twin: --at=FILE:LINE (the bare enclosing-chain report) and @FILE:LINE in any SYM selector; contract gate: test/atcheck.sh + test/mcpverbscheck.sh §7.

The flagship-reflex verbs (added 2026-07 so an MCP-only agent gets the same reflexes as the CLI) — these are the moments an agent most often skips the tool for; reach for the verb, not a grep:

MCP beats the CLI when you're mid-task and will ask more than once: the server keeps the parsed {ingest, graph, rank} in memory, so after the first parse every verb answers warm (~ms, no shell round-trip). The CLI still wins for what no verb exposes — --expand/--outline, --around, --deps/--hotspots/--clones, --graph-query, --arch, --pr-context, --scip, --lint-rules, --export, and the two remaining B11 verbs with no MCP twin — --merge-scout (multi-ref UX doesn't map cleanly onto a single JSON-RPC call) and --note-add/--notes (a write verb; adding it needs the same safety-contract thinking the 3 edit verbs got) — shell out for all of these even with the server running; the on-disk warm cache keeps them fast too.

Team/CI: commit the warm cache as an index artifact. ripwire <dir> --index-out=BASE cold-parses once, writes BASE.lean.ripwirecache + BASE.rich.ripwirecache (--for/--exemplar/--metrics need RICH), then exits with no map. Generate on main, commit or CI-cache it, restore with --cache=BASE.lean.ripwirecache (or .rich.) in PR jobs so only changed files re-parse — a same-arch SPEED cache that self-heals to a cold parse if stale or cross-arch (correct, slower). See README "The committable index artifact".