Repotector MCP Server

Repotector ⬡

The repo guardian AI agents handshake with before they touch your code.

An arriving agent knocks at the front door, is handed the map, and signs the register on the way out — so the next agent continues in two minutes instead of wandering for an hour, and a refactor doesn't quietly break what already works.

Portable and self-contained: pure Node ESM, two dependencies (@modelcontextprotocol/sdk, zod). Works on any repo — JS/TS deeply, other stacks in honest orientation-lite.

Install into any repo

cd /path/to/your/repo
npx repotector init

init scans the repo (never fails you on day one — see grandfathered baseline below), wires the MCP server into .mcp.json, and writes the doorway blocks so every arriving agent knows to handshake. It writes only inside .repotector/ and inside REPOTECTOR:BEGIN/END markers — your prose and config are never overwritten. See SECURITY.md for the exact posture.

Under .repotector/:

Plus, at the repo root, a regenerated JOURNAL.md — the diario di bordo, newest-first, that handshake serves the tail of so the next agent continues prior work instead of re-deriving it.

The front door (handshake-first)

The MCP server refuses deep tools until an agent calls handshake — and the initialize response already tells the agent to. In return the agent gets oriented in one call, and its exit is recorded for the next one.

• handshake({ who, model?, purpose? }) — orientation, ground rules, live gate verdict, map freshness, passport. Read-only and fast (no tree walk).
• city_map() — intent, stack, built-vs-missing, brain pointers. On a non-JS repo it says orientation-lite instead of faking an empty map.
• find_existing({ intent }) — REUSE: does it already exist? Don't rebuild.
• blast_radius({ changedFiles? }) — PROTECT: transitive dependents + impacted routes/components. Omit changedFiles to use the git diff.
• canon_check({ changedFiles? }) — INTEGRATE: the repo's canon rules.
• atlas_query({ query }) — keyword search across the map.
• quality_gates() — line-budget / structure / secret-hygiene, reported as regressions vs grandfathered debt.
• register() — who's inside now and the full crossing log.
• journal({ limit? }) — the repo's recent story: what prior agents did and left unfinished. whats_next() — the sensible next work, derived from DNA gaps + open threads + TODOs, every suggestion citing its evidence.
• dna_query({ clause?, topic? }) — what the repo specified (authored from a .psx/ mirror, or inferred, never merged). dna_coverage() — per clause: implemented / partial / missing. dna_diff({ changedFiles? }) — which clauses a change touches.
• depart({ summary? }) — sign out; the git delta of your visit is recorded even if you forget the summary. Your summary becomes the next agent's briefing.

Grandfathered baseline — never red on day one

A guardian that fails your repo the moment you install it gets uninstalled the moment you install it. So init snapshots the debt that already exists (oversize files, tracked secrets, missing paths). Gates then fail only on regressions against that floor — a new offender, an offender that grew, a new leak. Pre-existing debt is reported loudly, never blocking. repotector baseline re-snapshots after you pay it down.

v1.2 "Gatekeeper" — from advisor to checkpoint

• Commit guard — repotector hooks installs a pre-commit that runs the gates; gates exits non-zero on regressions, so hooks and CI actually block. Grandfathered baseline means it never blocks day-one debt — only new damage.
• Protected paths — intent.protect.paths globs (CI workflows, LICENSE…) that agents must not touch: change-based, never grandfathered, overridden only by editing the intent (an explicit, diffable act).
• Claims — claim({ paths }) declares your work zone; overlapping claims from live sessions answer granted:false with who/why. Advisory by design (blocking would be theater on a filesystem we don't control); claims die with the session.
• Decision records — depart({ decisions: [{ chose, over, because }] }) writes the why to the register and projects DECISIONS.md; the handshake serves standing decisions and decisions_query answers "was this deliberate?" — so agent 2 doesn't undo agent 1's choice.
• repotector doctor — one command, semaphore answer to "how protected is this repo, really?", with a fix for every red.

v1.3 "Merge Guard" — commit without colliding

• merge_check — a zero-damage TRIAL merge (git merge-tree) of HEAD against the integration base, run BEFORE you commit: reports clean/conflicted with the exact files, each attributed to who holds that zone (live claims — and, in PSX Workbench repos, the Merge Machine's leases via the .psx mirror). CLI: repotector merge-check [target] (exit 1 on conflicts, so hooks/CI can gate on it). Zero network: it trial-merges against your LOCAL refs and says so — fetch first for the freshest truth.

Resilient register — agents die without signing out

Sessions that enter and never leave (the agent was killed, the pipe closed) are auto-departed on the next handshake, with the git delta of what they touched. The ledger never fills with immortal open sessions, and a depart carries real work even when nobody called it.

CLI

npx repotector init          # scan, wire .mcp.json, write the doors — day-one green
npx repotector refresh       # re-derive the map + re-stamp the doorway blocks
npx repotector handshake     # orientation + live gate + passport (logged visit)
npx repotector city-map      # built-vs-missing + brain pointers
npx repotector dna-coverage  # per specified clause: implemented / missing
npx repotector whats-next    # the sensible next work, with evidence
npx repotector journal       # the diario di bordo (regenerates JOURNAL.md)
npx repotector gates         # regressions vs grandfathered debt
npx repotector baseline      # re-snapshot the grandfathered floor
npx repotector register      # the visitor ledger
npx repotector lock <pass>   # optional passphrase gate on the deep map
npx repotector mcp           # start the stdio MCP server

Honesty

Repotector guards repos, so it holds itself to its own standard. The lock is a compliance signal, not filesystem access control; the register is append-integrity, not tamper-proof; a static badge is self-reported. It spawns only git, makes no network calls, and pins exact versions in .mcp.json. The full threat model is in SECURITY.md — no security theater.

Determinism

The Atlas fingerprint is a SHA-256 over sorted source contents (16 hex chars), no timestamps — the same tree always fingerprints the same. Large files (>1MB, generated/minified) are marked, never read into the fingerprint. builtAtHead stamps the git sha so freshness can be checked without a walk.

License

MIT © PSX System. The core an agent needs in a repo is free forever; the compounding brain (Genome cloud, authored DNA) is the premium layer.