rogerchappel/toolmirror

toolmirror

Local-first registry and drift detector for agent tool catalogs.

toolmirror imports JSON tool definitions from MCP-style catalogs, Codex/OpenClaw dumps, or hand-written files. It normalizes them into a stable lockfile, redacts sensitive defaults, generates Markdown reference docs, diffs snapshots, and flags risky tool surfaces.

Install

npm install
npm run build

For local CLI use from this checkout:

npm link

Use

Normalize one or more tool dumps:

toolmirror import tools.json --output toolmirror.lock.json

Use - for one input from standard input. An import may combine that single stdin input with file inputs, but supplying - more than once is a usage error and exits with status 1 before stdin is read.

File and stdin inputs may begin with a UTF-8 byte-order mark; the mark is stripped before parsing, so Windows PowerShell or editor dumps import unchanged and produce lockfiles identical to the same BOM-free content. When JSON parsing fails the command exits 1 and the diagnostic is toolmirror: <input: <message, naming the failing file path or stdin so multi-input commands identify which input is broken.

When multiple inputs define the same tool name, identical normalized definitions are collapsed into one entry. Its source is the lexicographically first source location, so reversing the inputs does not change the lockfile. Conflicting same-name definitions are rejected with exit status 1; the diagnostic names the tool and every conflicting source location instead of silently choosing one.

Generate Markdown documentation:

toolmirror docs toolmirror.lock.json --output TOOLING.md

Generated index links use deterministic heading anchors. Tool names that normalize to the same anchor receive stable numeric suffixes such as foo-bar-2.

Compare exactly two snapshots. The command exits 2 when catalogs differ:

toolmirror diff old.lock.json new.lock.json