@prepsavant/mcp

Local Sam MCP runner: an npm-publishable Model Context Protocol server that runs inside Claude Desktop, Cursor, or Codex. It executes pinned tests in a local sandbox (Python and JavaScript/TypeScript), uses MCP sampling to ask the host's model to speak in Sam's voice, and pushes attempts and enrichment back to your Sam account through long-lived device tokens.

Quick start

# 1. Install the runner into your MCP host (Claude Desktop / Cursor / Codex):
npx -y @prepsavant/mcp install --host claude

# 2. Authorize the runner against your Sam account (one-time):
npx -y @prepsavant/mcp auth

# 3. Restart your MCP host. The runner will appear as the `sam` server.

# 4. (Optional) Verify your environment is healthy:
npx -y @prepsavant/mcp doctor

Once the runner is registered, the coached_* MCP tools (e.g. coached_start_session, coached_ask, coached_check_in, coached_end_session) start a Coached session right inside your host — same question brief, hint ladder, scored attempts, and recap as the browser. Sam's voice is supplied via MCP sampling so your host model speaks as Sam. AI-Assisted observation is a separate flow documented further below.

Coached tool family (0.7.0)

• coached_orient — pick up where the candidate left off; surfaces a per-mode nextTool slug telling the host which tool to call next.
• coached_pick_question — search the question bank. Filters: topic AND company. Pass company as a company id, slug, or case-insensitive display name (e.g. "Anthropic").
• coached_list_companies — discover which companies have questions attached, sorted by question count desc. Use this before coached_pick_question when the candidate names a target firm.
• coached_start_session, coached_ask, coached_check_in, coached_end_session — Coached session loop.

AI-Assisted tool family (0.7.0)

These tools are intentionally separate from coached_* — the host MUST write code, run shells, and edit files in AI-Assisted mode. The ai_assisted_start_session description includes an explicit "DO NOT refuse to write code" instruction so hosts don't fall back to a Coached "no code" posture.

• ai_assisted_start_session — issues an ephemeral Ed25519 keypair, registers a capability manifest with the server, returns host instructions.
• ai_assisted_log_event — append a signed event (prompt, response, edit, shell, tool call, permission decision, etc.) to the evidence log; uploads best-effort.
• ai_assisted_snapshot — record a point-in-time workspace snapshot reference.
• ai_assisted_end_session — finalize the bundle, returning the capability manifest hash, log hash, and event count.

Migrating from practice_* (≤ 0.4.x)? The legacy practice_* aliases were removed in 0.5.0. Replace practice_list_questions → coached_pick_question, practice_start_session → coached_start_session, practice_request_hint → coached_ask, practice_check_in → coached_check_in, practice_end_session → coached_end_session. practice_submit_attempt has no replacement — Coached sessions submit code via the host editor's native run/test tools.

Two surfaces, one Coached experience

Coached isn't browser-only. Once the runner is installed, the same Coached loop is available in two surfaces:

• Browser — go to your Sam dashboard and start a Coached session, no install required.
• IDE — call the coached_* tools from Cursor, Claude Desktop, or Codex and Sam runs the same Coached loop in your host.

These are two surfaces on the same Coached experience: same job briefs, same question banks, same hint ladder, same scoring. The only difference is where you practice. AI-Assisted mode (covered below) is a separate, silent-capture flow — not a third Coached surface.

What lives where

• ~/.prepsavant/config.json — long-lived device token, chmod 600.
• ~/.prepsavant/sandbox/ — temp working directories for sandboxed runs.
• Your MCP host's config file (e.g. claude_desktop_config.json) — patched by prepsavant install to register the sam server.

AI-Assisted Mode

AI-Assisted mode lets you solve problems using Claude Code, Cursor, or Codex CLI while PrepSavant silently captures a signed, tamper-evident evidence log for post-session grading. Sam stays completely out of your tool's way — no MCP hooks, no tool interruptions.

# Start an AI-Assisted capture session (v0.4.0+)
npx -y @prepsavant/mcp start

The start command walks you through:

1. Tool selector — choose from Claude Code (Full support), Cursor (Beta), or Codex CLI (Beta).
2. Cross-platform preflight — detects the tool binary in PATH, checks the minimum version (Cursor 0.45+), verifies snapshot store is writable, and cleans up stale hooks from a previous crash.
3. Consent dialog — shows exactly what is and is not captured including tool-specific beta caveats and OS-specific coverage notes.
4. Hook install — installs hooks for the selected tool:
   • Claude Code: .claude/settings.json (workspace-scoped)
   • Cursor: .cursor/settings.json (workspace-scoped)
   • Codex CLI: ~/.codex/hooks.json (global, requires CODEX_HOOKS=1)
5. Capture loop — runs silently in the background. Press Ctrl+C to end the session and upload the evidence bundle.

Tool support matrix

| Tool | Status | Confidence ceiling | Hook scope | | --- | --- | --- | --- | | Claude Code | GA | High | Workspace .claude/settings.json | | Cursor | Beta (≥0.45) | Medium | Workspace .cursor/settings.json | | Codex CLI (interactive) | Beta | Medium | Global ~/.codex/hooks.json | | Codex CLI (exec --json) | Beta | High | JSONL stream (no hooks required) |

What is captured

| Captured | Not captured | | --- | --- | | Prompts and AI responses | Screen or webcam | | Tool calls and results | Microphone | | File edits the AI applies | Keystroke timing | | Shell commands (capped output) | Private API keys or credentials | | Test outcomes | Files outside the problem workspace | | Workspace diffs at key boundaries | |

Codex exec mode (high confidence)

When using Codex CLI, choose codex exec --json mode at the prompt for the highest capture fidelity. PrepSavant consumes the full JSONL event stream (messages, tool_use, tool_result, file_change, command, web_search, plan_update, reasoning) without requiring hooks. Interactive mode requires export CODEX_HOOKS=1 and is limited to medium confidence.

Troubleshooting AI-Assisted mode

Tool not found: ensure the binary is in your PATH and re-run prepsavant start.

• Claude Code: docs.anthropic.com/en/docs/claude-code
• Cursor: cursor.com
• Codex CLI: github.com/openai/codex

Cursor version too old: Cursor 0.45+ is required for hook support. Update at cursor.com.

Stale hooks warning: the runner crashed without cleaning up. Run prepsavant start again and accept the prompt to remove stale hooks. Or delete the hook config manually (see hook scope table above).

Hooks not firing (Cursor): ensure you opened Cursor in the same directory you passed to prepsavant start. The hooks are workspace-scoped.

Codex hooks not firing: set CODEX_HOOKS=1 in your environment before starting Codex interactive mode. Or use codex exec --json mode (no hooks required).

Run AI-Assisted diagnostics:

npx -y @prepsavant/mcp doctor --ai-assisted

Checks: tool versions, hook config status per tool, snapshot store writability, stale hook detection, CODEX_HOOKS env var, last 5 session IDs.

Subcommands

| Subcommand | What it does | | --- | --- | | start | Start an AI-Assisted capture session (Claude Code GA, Cursor Beta, Codex CLI Beta). | | install [--host claude\|cursor\|codex] | Patch the chosen host's config so it launches prepsavant mcp on stdio. | | auth | Run the device-link flow against the Sam API and store the resulting token. | | doctor [--ai-assisted] | Run local environment checks. --ai-assisted adds tool version detection, hook config status, and snapshot store diagnostics. | | mcp (default) | Start the MCP server on stdio. Used by your MCP host, not by you directly. |

Security model

The runner never sees your account password. It authenticates with a long-lived device token issued by the Sam dashboard. Tokens can be revoked at any time from Settings → Local Sam runner devices.

Pinned test cases are downloaded from the Sam API. Your code is executed locally in a temp directory with a wall-clock timeout. The runner does not sandbox the network or filesystem beyond Node's defaults — only run code you wrote.

Releasing a new version (manual, from your laptop)

@prepsavant/mcp is published to npm manually from the operator's laptop, as of task #834. There is no CI publish, no public mirror repo, and no Sigstore provenance attestation — the package is published "uncertified", which is fine for this project's threat model. The monorepo lives only in the Replit workspace.

Pre-flight (one-time, on your laptop)

1. Install Node ≥ 18.18 and pnpm.
2. Log in to npm with an account that has publish rights to the @prepsavant scope:

   npm login        # opens a browser for OTP
   npm whoami       # confirms you're authenticated

3. Make sure your npm 2FA is set to "Authorization and writes" (so npm publish will prompt for an OTP at publish time — this is the only thing standing between a stolen npm session and a poisoned release).

Releasing

From your laptop, in a fresh checkout of the monorepo:

# 1. Get the current code from Replit. Easiest: download the workspace
#    as a zip from Replit (Tools → "Download as zip"), unzip, and cd in.
#    Or use any other transport you've set up — there is no GitHub remote
#    by design.
cd path/to/prepsavant-monorepo

# 2. Install deps (uses pnpm-workspace.yaml + pnpm-lock.yaml).
pnpm install --frozen-lockfile

# 3. Bump the version. Pick one (semver):
#      patch (0.6.0 → 0.6.1) — bug fix, no API change
#      minor (0.6.0 → 0.7.0) — additive change, backwards-compatible
#      major (0.13.0 → 1.0.0) — breaking change
( cd packages/mcp-runner && npm version patch --no-git-tag-version )
# (or edit `version` in packages/mcp-runner/package.json by hand)
#
# Recent breaking releases:
#   1.0.0 (Task #1113, Phase 3c + Task #1119) — RETIRED `coached_check_in`
#     and `ai_assisted_check_in` MCP tools and their HTTP endpoints
#     (`POST /runner/sessions/:id/check-in` and
#     `POST /runner/ai-sessions/:id/check-in`). Hosts must drive both
#     coached and AI-Assisted sessions via their split-loop pairs
#     (`*_get_context` read + `*_record_turn` / `*_record_feedback`
#     write). The IDE-rules installer now fetches BOTH the active
#     coached and AI-Assisted standing frames from the API at install
#     time (each via `?kind=` namespace) and falls back to per-kind
#     local caches (`~/.prepsavant/standing-frame.json` and
#     `~/.prepsavant/standing-frame-ai-assisted.json`) when offline.

# 4. Run the local validation suite. Catches the common breakages
#    BEFORE publishing — the version-bump guard is the same one that
#    runs as a Replit workflow on every commit.
pnpm --filter @workspace/scripts run check-mcp-runner-version-bump
pnpm --filter @prepsavant/mcp run typecheck
pnpm --filter @prepsavant/mcp run test
pnpm --filter @prepsavant/mcp run build

# 5. Inspect what will actually be in the tarball — sanity check before
#    uploading it to a public registry.
( cd packages/mcp-runner && npm pack --dry-run )

# 6. Publish. npm will prompt for your 2FA OTP.
( cd packages/mcp-runner && npm publish --access public )

Post-publish (back in the Replit workspace)

# 1. Refresh the in-repo version constants so the dashboard install
#    snippets, the runner adapter, and the version-bump guard all
#    agree with what's now on npm. This script reads
#    `npm view @prepsavant/mcp version` and writes:
#      - lib/mcp-runner-version/src/index.ts (MCP_RUNNER_VERSION)
#      - packages/mcp-runner/src/version.ts  (ADAPTER_VERSION)
#      - packages/mcp-runner/package.json    (version field)
pnpm sync-mcp-runner-version

# 2. Commit the regenerated constants. The Replit auto-checkpoint will
#    capture this; no push step is needed since there's no GitHub remote.
git add lib/mcp-runner-version packages/mcp-runner
git commit -m "chore(mcp-runner): sync version constants to <new-version>"

Verifying the release

npm view @prepsavant/mcp version             # should report the new version
npx -y @prepsavant/mcp@<new-version> --help  # smoke the install path

Cloudflare negative-caches "package not found" for a few minutes after publish — a 404 from npm view immediately after npm publish does not mean the publish failed, just wait 1–2 min and retry.

Pre-merge guard: version bump on runner-code changes

scripts/src/check-mcp-runner-version-bump.ts (registered as the mcp-runner-version-bump Replit workflow) fails when a commit changes runner-published code without also bumping packages/mcp-runner/package.json version. This catches the case where you forget to bump the version before publishing — the validator will block the merge until you fix it.

Release-relevant changes are: packages/mcp-runner/src/** (excluding tests), build.mjs, README.md, LICENSE, the vendored libs (lib/sam-market-context-shared/src/**, lib/ai-assisted-events/src/**), and any non-version field in the runner package.json.

Escape hatch: if a runner-code change genuinely doesn't need a publish (a comment-only fix, a pure rename, a refactor with no behavioural delta), add a Skip-Mcp-Runner-Bump: <reason> trailer to the commit:

fix(runner): rename internal helper for clarity

Skip-Mcp-Runner-Bump: pure rename, no shipped behavioural change

The reason is required (empty trailer doesn't pass) and is logged for auditability.

Updating the dashboard install snippets

You don't — and there's nothing to keep in sync. The dashboard always installs the npm latest dist-tag (e.g. npx -y @prepsavant/mcp install --host claude), with no version suffix anywhere a user can copy. What latest points to is controlled entirely by the release workflow: stable releases are published with --tag latest, prereleases with --tag next.

MCP_RUNNER_VERSION (and @workspace/mcp-runner-version) is still the single source of truth for the currently shipped runner version — it feeds the runner's --version output, doctor diagnostics, and any "Sam runner vX.Y.Z detected" UI — but it is no longer used to construct install commands.