# jev-mcp

A local stdio MCP server that gives Cursor, Codex, and other MCP clients typed [TypeSafe Jev](https://docs.typesafe.ai/introduction.md) judgments. Jev returns Choice, Score, and Noul answers; the host agent still edits files and runs commands.

## Tools

| Tool | Purpose |
| --- | --- |
| `jev_step` | Route the next step and select a prepared call in one request |
| `jev_coding_loop` | Route the next step and decide whether a partner model is needed |
| `jev_tool_route` | Select an exact host-prepared tool call without generating arguments |
| `jev_review` | Assess a proposed patch |
| `jev_verify` | Check claims against supplied evidence |
| `jev_gate` | Combine patch review and claim verification in one upstream call |
| `jev_screen` | Screen untrusted content before the host reads it |
| `jev_rank` | Rank candidates supplied by the host |
| `jev_scope` | Check whether a prepared action is within the approved task/scope |
| `jev_triage` | Classify a failure and select a recovery strategy |
| `jev_risk` | Security-focused risk triage for a proposed patch |
| `jev_evaluate` | Ask custom, atomic typed questions |

Results include typed answers, token usage, and an `action`: `auto`, `review`, or `escalate`. Confidence measures model certainty, not factual truth. Incomplete context never permits `auto`; reduce the input and submit it again for a complete judgment. Questions that receive untrusted text carry a data-boundary instruction, and `jev_screen` adds a deterministic high-signal injection backstop. Those are defense-in-depth: screening is advisory, not a sanitizer or permission to follow external text.

Question packs are MCP resources at `jev://packs/{coding-loop,tool-route,step,review,verify,screen,rank,gate,scope,triage,risk}`. Workflow templates are MCP prompts at `jev-step-loop`, `jev-completion-gate`, `jev-screen-untrusted`, `jev-scope-check`, `jev-debug-loop`, and `jev-pr-risk`.

## Coding with fewer partner-model turns

`jev_step` answers the whole loop turn in one request: it routes the step and, when the host supplies prepared calls, selects among them. A host that would otherwise call `jev_coding_loop` and then `jev_tool_route` spends one MCP round-trip instead of two, so it spends one host-model turn instead of two. Both original tools remain available.

Let host code execute known steps and prepare exact tool calls from an existing plan. When a semantic choice is needed, pass those calls to `jev_step` or `jev_tool_route`; either returns an executable `call` only for a confident, suitable selection with complete context and validated host facts. The host executes that call and routes again using the new observation. Jev never invents arguments or executes tools.

When a new plan or code may be needed, use `jev_coding_loop` with trusted `execution` facts. Its `handoff` distinguishes tool use, context gathering, review, user input, stopping, and a partner model. Invoke a generative partner only when `partner_model.required` is `true`; the legacy `model_tier` answer alone does not request a model turn. Uncertainty and escalation do not automatically spend a partner turn.

The prepared-call router accepts at most 32 candidates. Empty or wholly ineligible lists return locally with zero Jev usage. Other routing calls use Jev; this reduces unnecessary generative handoffs by policy, but live quality and cost savings have not been measured. See [the tool contracts](docs/tools.md) and [host workflow](skills/jev-mcp/SKILL.md).

## Safety and recovery checkpoints

Use `jev_scope` before a nontrivial action whose semantic fit with the approved task matters. It checks scope, declared-effect consistency, fresh-confirmation need, and risk. External, destructive, and unknown effects never return `auto`; `auto` is not authorization.

Use `jev_triage` after a failed test or command. It selects a failure cause, classifies loop progress, and selects a recovery strategy. It never retries or edits code; the host prepares recovery calls and routes them with `jev_step`. Use `jev_risk` before review and completion gating to add security concerns (authorization, validation, secrets, data loss, concurrency, dependencies, external effects). It never grants merge permission.

## Quick start

Install Node 20+ and run from a checkout:

```bash
npm ci
npm run build
```

Set a [TypeSafe API key](https://console.typesafe.ai/settings/keys) in your shell, then run diagnostics:

```bash
export TYPESAFE_API_KEY=ts_...
node dist/index.js doctor
node dist/index.js doctor --json
```

PowerShell:

```powershell
$env:TYPESAFE_API_KEY = 'ts_...'
node dist/index.js doctor --json
```

For a deterministic local demo, set `JEV_MCP_MOCK=1` instead. Mock mode is for tests and demos, not production decisions. Neither the CLI nor MCP automatically reads `.env`; see [configuration](docs/configuration.md) for explicit environment-file use.

**Cursor:** copy [the MCP example](examples/cursor.mcp.json) into `.cursor/mcp.json`, replace its argument with the absolute path to this checkout's `dist/index.js`, and set the key in `env`.

**Codex:** register the absolute path:

```bash
codex mcp add jev --env TYPESAFE_API_KEY=ts_... -- node /absolute/path/to/jev-mcp/dist/index.js
```

Install the complete [agent skill folder](skills/jev-mcp/SKILL.md) at `.agents/skills/jev-mcp/` so Codex or Cursor knows when to call these tools. Keep its references, scripts and license together. Skill discovery and MCP configuration are separate steps; see [installation](docs/install.md). The bundled [TypeSafe reference](skills/jev-mcp/references/typesafe.md) links the relevant primary documentation; the [evidence helper](skills/jev-mcp/references/evidence.md) captures real patches and test output for completion judgments.

## CLI

```bash
node dist/index.js                       # stdio MCP
node dist/index.js doctor                # human-readable diagnostics on stderr
node dist/index.js doctor --json         # structured diagnostics on stdout
node dist/index.js eval --stdin < request.json
```

An evaluation request contains `state` and a `questions` map:

```json
{
  "state": "Production payouts are failing. Urgent.",
  "questions": {
    "urgent": { "type": "noul", "instructions": "Is this urgent?" }
  }
}
```

Diagnostics do not log request content or API keys. Calls have a 30-second total deadline by default, configurable with `JEV_MCP_TIMEOUT_MS`. API failures and invalid responses return typed errors rather than fabricated judgments.

Repeated loop turns can be served from an opt-in result cache (`JEV_MCP_CACHE_TTL_MS`), a hard per-process spend cap is available with `JEV_MCP_TOKEN_BUDGET`, and the `jev://stats` resource reports calls, actions, latency, tokens, and cache hits per tool. See [configuration](docs/configuration.md).

## Limits and policy

State plus questions must fit the estimated 64,000-token total budget and the 32,000-token state-plus-longest-question budget. State may be shortened; results expose incomplete coverage and cannot automatically accept a judgment based on omitted context. Questions alone that exceed the budget are rejected.

Rank accepts unique candidate IDs and at most 5,000 supplied candidates, with at most 250 options per upstream call. Larger lists use repeated reduction rounds; each candidate text is capped at 2,000 characters. Verify and gate accept at most 1,000 claims. It ranks supplied candidates and does not index your repository. Arithmetic and date calculations belong in host code.

All twelve tools expose an MCP output schema and return the same successful payload through both `structuredContent` and the JSON text content. Tool-route and fused-step judgments receive control-stripped candidate IDs/names, sanitized descriptions, and argument shapes; raw host arguments are retained only for the selected, locally validated call. `jev_verify` also reports `all_claims_verified`, which is stricter than its per-item classification action.

`jev_scope` never authorizes or executes an action: `auto` means no semantic scope concern, not permission. `jev_triage` selects a recovery strategy but does not retry, ask the user, or edit code. `jev_risk` is security evidence only and never grants merge or deployment permission. All three remain advisory and fail closed when coverage is incomplete.

## Development

```bash
npm test
npm run typecheck
npm run build
npm run test:package
npm run benchmark
npm run test:skill
npm run build:skill
```

The regular suite never runs live evaluations, even when a key is inherited. Package smoke testing builds and packs the project, installs the tarball into an isolated directory with `npm --offline`, then exercises its shipped CLI and MCP server. `npm run benchmark` measures compiled MCP stdio transport in deterministic mock mode. Use `npm run benchmark:ci` for broad sanity budgets. Run `npm ci` first to populate the dependency cache. No test publishes the package.

`npm run build:skill` creates a standalone versioned ZIP and checksum under ignored `artifacts/`. `npm run test:skill` checks independent extraction, contained references, all twelve documented requests, task graders, and executable workflow replay. Explicit `npm run eval:live` and `npm run eval:agent -- --host all --paired --runs 1` measure live judgments and real coding tasks separately. Read [evaluation setup and interpretation](evals/README.md) for credentials, pinned models, CLI prerequisites and report meaning.

`npm pack` and `npm publish` build automatically through `prepack`. CI checks Node 20 and 22 on Windows and Linux, including the offline packed-install smoke test.

## Documentation

| Document | Contents |
| --- | --- |
| [Changelog](docs/changelog.md) | Unreleased changes, compatibility notes, and validation |
| [Architecture](docs/architecture.md) | Request path, policy, limits, and errors |
| [Tools](docs/tools.md) | Arguments and outputs for all twelve tools |
| [Install](docs/install.md) | Host configuration and Windows checkout |
| [Hooks](docs/hooks.md) | Enforced Claude Code hooks and `jev-mcp check` |
| [Pull-request gate](docs/ci.md) | `jev-mcp ci` and an example GitHub workflow |
| [Configuration](docs/configuration.md) | Environment, thresholds, diagnostics, tests |
| [Agent skill](skills/jev-mcp/SKILL.md) | Calling guidance for the host |
| [AGENTS.md](AGENTS.md) | Short project guidance |