@reorient/mcp

Default-deny local MCP tools for deterministic Reorient release evidence.

@reorient/mcp runs over stdio and uses @reorient/core for schemas, comparison, flow replay, gates, and verification. Filesystem roots, browser hosts, model calls, remote platform reads, and uploads are separate startup grants.

Install

npm install --save-dev @reorient/[email protected]

The executable is reorient-mcp. For a one-off invocation, use:

npx --yes --package @reorient/[email protected] reorient-mcp

Add to Codex

The server starts with no filesystem access. Grant one or more absolute read roots when registering it:

codex mcp add reorient -- \
  npx --yes --package @reorient/[email protected] reorient-mcp \
  --root /absolute/project/root

Restart or resume the Codex session after changing MCP registration. The server exposes deterministic comparison, flow, path, gate, report, schema, and security capabilities within the granted roots.

Browser capture

Browser capture requires separate local-file or host grants:

npx --yes --package @reorient/[email protected] reorient-mcp \
  --root /absolute/project/root \
  --allow-file-capture \
  --host preview.example.com \
  --host localhost:3000

Capture always launches headed Chromium. Remote hosts require HTTPS; explicitly granted loopback development hosts may use HTTP. Redirects and subresources are revalidated, and stdout remains reserved for MCP protocol messages.

Install the browser binary once if it is not already present:

npx playwright install chromium

Model-backed guidance

Guidance is off by default. It requires OPENAI_API_KEY in the MCP process environment and an explicit whole-process call budget:

OPENAI_API_KEY=your-server-side-key \
npx --yes --package @reorient/[email protected] reorient-mcp \
  --root /absolute/project/root \
  --enable-model-guidance \
  --model-call-budget 9

Each non-empty compose_guidance call atomically reserves three calls: GPT-5.6 Luna classifies deterministic receipts, GPT-5.6 Terra maps changed paths, and GPT-5.6 Sol composes cited returning-user guidance. Inputs and outputs are capped, storage is disabled, and deterministic code rejects invalid receipt coverage, citations, or quoted names. The server does not automatically load .env files.

Optional platform access

Remote platform access remains disabled unless an operator supplies both the platform URL and actor. Credentials come from environment variables, never command-line arguments:

REORIENT_PLATFORM_TOKEN=read-scope-token \
npx --yes --package @reorient/[email protected] reorient-mcp \
  --root /absolute/project/root \
  --platform-url https://reorient.example.com \
  --platform-actor amara

This adds read-only get_platform_project and query_stats tools. Uploading a release requires a second process-level grant, a signing secret, a root-contained envelope file, and the literal UPLOAD_RELEASE confirmation in the tool call:

REORIENT_PLATFORM_SIGNING_SECRET=your-server-side-secret \
npx --yes --package @reorient/[email protected] reorient-mcp \
  --root /absolute/project/root \
  --platform-url https://reorient.example.com \
  --platform-actor amara \
  --enable-platform-upload

Platform redirects are refused, responses are bounded, and HTTP is accepted only for exact loopback development URLs. upload_release is an explicit external mutation and is never called by read tools.

MCP surface

• Tools: page capture, release comparison, flow recording/comparison, path replay, release gates, evidence reports, verified guidance, and optional platform operations.
• Resources: versioned Reorient JSON Schemas and the active local security boundary.
• Prompts: release review, first-divergence explanation, and deterministic migration-note drafting.

Runtime support

• Node.js 20 or newer.
• ESM package with included TypeScript declarations.
• MCP clients that support local stdio servers, including Codex.
• macOS, Linux, and Windows environments supported by Node.js and Playwright Chromium.
• Interactive desktop or virtual-display environment when browser capture is enabled.

The package uses @reorient/cli for headed capture and @reorient/core for all durable artifacts. Use matching major versions across Reorient packages.

Scope

Reorient MCP tools report inspectable release evidence. They do not certify WCAG compliance, simulate a screen reader, infer user impact, or silently mutate remote state.

MIT licensed.