jev-mcp
A local stdio MCP server that gives Cursor, Codex, and other MCP clients typed TypeSafe Jev judgments. Jev returns Choice, Score, and Noul answers; the host agent still edits files and runs commands.
Tools
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 and host workflow.
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:
npm ci
npm run build
Set a TypeSafe API key in your shell, then run diagnostics:
export TYPESAFE_API_KEY=ts_...
node dist/index.js doctor
node dist/index.js doctor --json
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 for explicit environment-file use.
Cursor: copy the MCP example 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:
codex mcp add jev --env TYPESAFE_API_KEY=ts_... -- node /absolute/path/to/jev-mcp/dist/index.js
Install the complete agent skill folder 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. The bundled TypeSafe reference links the relevant primary documentation; the evidence helper captures real patches and test output for completion judgments.
CLI
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:
{
"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.
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
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 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.