Review MCP Server

Ottorev — Review MCP Server

The memory an engineering assistant needs. This local stdio MCP server records names, notes, tags, and decisions against an exact CAD revision in SQLite, so an assistant can pick up where it left off — remember that a face is the mating surface, that a tolerance callout is tight, or that a review concluded hold with the requirements behind it.

It never opens the CAD file: it stores the revision the caller supplies and compares it on recall, so it works on a laptop with no CAD software and no other server running.

Quick start

Requires Node.js 26+ and npm. From this repository:

npm install
npm run build
REVIEW_MCP_DB_PATH=/absolute/path/to/review.db npm start

For any MCP client:

{
  "mcpServers": {
    "review": {
      "command": "node",
      "args": ["/absolute/path/to/review-mcp-server/dist/src/index.js"],
      "env": { "REVIEW_MCP_DB_PATH": "/absolute/path/to/review.db" }
    }
  }
}

REVIEW_MCP_DB_PATH defaults to ./review-mcp.db; parent directories are created automatically. Records persist across restarts — protect and back up the database as application data.

Tools

Results provide structured content and text; tool failures set MCP isError. Writes change local records; the client controls when to request those mutations. The server also advertises engineering-review prompts that compose with a geometry server, while the core record operations run on their own.

Artifact and subject semantics

An input artifact contains revision (sha256: plus 64 lowercase hex digits), format: "step", and optional URI and units:

{
  "revision": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "uri": "file:///work/part.step",
  "format": "step",
  "units": "mm"
}

Supply the actual revision from the producer; the example digest is illustrative. A URI groups records by locator; without a URI, the revision is the lookup key.

uri accepts either a URI or a plain filesystem path, because a path is what a caller usually has in hand:

{ "uri": "/work/part.step" }

Both spellings address the same records: a path is normalised to a file: URI before anything is stored or matched. A relative path resolves against the server working directory. Normalisation never opens the file, so a record can be written for an artifact this server cannot read.

An entity filter is revision-scoped; a text or tag filter is not. An entity ID denotes different geometry in a different revision, so recall and recall_decisions match an entity_id only against records written for the supplied revision, and match it exactly — face:3 does not match face:30. Names, notes, subjects, and tags are matched across revisions, which is how an earlier record is found at all, and every result says whether it is stale.

Each returned record contains one artifact reference, its entity IDs, and the ID scheme. The entity IDs are opaque outside that scheme and revision.

Decision records

A review names or annotates geometry. A decision is the other thing a review produces: a disposition about a revision, and the basis it rests on.

One basis item is one requirement-check, and it answers for itself:

unresolved and conflicting are first-class outcomes: a decision that carries them is a complete record of where the work stands, not a failure to decide. A basis item is refused when it cannot answer for itself — no source, or a state of unresolved/conflicting with no question.

Three properties matter more than the shape:

• A decision is bound to a revision. The revision is part of its key, so the same subject at the same revision is recalled rather than reached again, and a decision made against a different revision comes back marked stale: true, still carrying the revision it belongs to.
• Face IDs do not travel between revisions. Topological naming is unsolved in OCCT, and this API does not pretend otherwise: an entity_id filter matches only the revision that produced the ID.
• Verdicts are what make a requirement agreed. Recording a verdict turns a line the assistant proposed into one the engineer accepted or rejected — the record of how much authority the assistant actually earned.

A stored decision is the caller's own account: the requirement as stated and the evidence as quoted. This server never measures anything, so a recalled decision is a record of what was concluded, not a measurement cache — Geometry remains the authority for numbers.

Limits

Review stores authored context: names, notes, and tags bound to an artifact revision, and decisions with the requirements they rest on. It does not store verified measurements, a complete immutable audit history, or authoritative approval records, and it does not compute geometry, run simulation, or decide manufacturability. Staleness is judged from a revision the caller supplies; Review never opens the CAD file.

There are no schema migrations: the database is a working file, and a changed table shape means deleting it. The server reports the version mismatch rather than guessing at a transformation.

Development

Requires Node.js 26+ and just. A Nix flake and .envrc provide the toolchain; run direnv allow after changing either.

Server logs go to stderr as newline-delimited pino JSON. MCP_LOG_LEVEL (debug|info|warn|error), MCP_LOG_FORMAT=human, and MCP_TRACE_ID tune them; secret-like fields are redacted.

Packaging

npm pack builds first and includes compiled runtime code, package metadata, and this README. Tests and source maps are excluded. Install the tarball to check the review-mcp executable with a compatible MCP client. The server serves both protocol eras: the 2025-11-25 handshake that stock MCP hosts negotiate, and the 2026-07-28 envelope through server/discover.

License

MIT. Third-party notices: THIRD_PARTY_NOTICES.md.