English | 简体中文

jev-mcp-server

MCP server for Jev (TypeSafe System One) — a faithful mapping of the three official question types, plus batch classify.

When your coding agent needs a judgment — which log line is the root cause, how risky is this diff, is this change breaking — it usually burns a frontier LLM call and gets prose back. Jev answers with a typed decision and calibrated probabilities in a fraction of a second, for a fraction of a cent:

Question type	Tool	Returns	Measured*
choice	pick 1 of 2-100 options	winner + probabilities over ALL options + confidence	~0.6 s, ~$0.00002
score	grade on a rubric of 2-8 levels	fractional index + per-level probabilities	~0.5 s, ~$0.00002
noul	yes / no	0-1 degree	~0.4 s, ~$0.00001
classify	label up to 100 items	per-item choice + aggregate summary	~0.5 s × items

* Measured against jev-1.13.0, 2026-09, from real sessions (see Benchmarks).

Why this one

• 1:1 with the official API. Tool names match the System One question types (choice / score / noul), so anything you learn from TypeSafe's docs transfers directly. No invented abstractions.
• Decisions, not explanations. Jev never returns reasons — any "why" your assistant writes is its own interpretation of the probability distribution. The README (and the tool docs) say so explicitly, so reports built on top stay honest.
• Batch classify for routing/labeling workflows, with per-item caching.
• One-time setup tool: paste your API key once in chat; it's verified live, stored with 0600 permissions, and never echoed back.
• Bilingual docs (English / 简体中文), configs for Claude Code, Codex, OpenCode, pi, and any stdio MCP client.
• Offline-tested (no network in CI), retries on 429/503/529, response validation (probabilities sum to 1, winner is the max), optional response cache.

Quickstart

1. Get a TypeSafe API key at console.typesafe.ai/settings/keys.
2. Register the server with your client (pick one below).
3. Either export TYPESAFE_API_KEY, or just ask your agent: "run the jev setup tool with key tsk_...".

Claude Code

claude mcp add jev --env TYPESAFE_API_KEY=YOUR_KEY -- uvx jev-mcp-server

Codex (~/.codex/config.toml)

[mcp_servers.jev]
command = "uvx"
args = ["jev-mcp-server"]
env = { TYPESAFE_API_KEY = "YOUR_KEY" }

OpenCode (~/.config/opencode/opencode.json)

{
  "mcp": {
    "jev": { "type": "local", "command": ["uvx", "jev-mcp-server"], "enabled": true }
  }
}

pi (~/.pi/agent/mcp.json)

{
  "mcpServers": {
    "jev": { "command": "uvx", "args": ["jev-mcp-server"], "lifecycle": "lazy" }
  }
}

Any stdio MCP client

{ "command": "uvx", "args": ["jev-mcp-server"] }

From source (this repo)

{ "command": "uv", "args": ["run", "--directory", "/path/to/jev-mcp-server", "jev-mcp-server"] }

Tools

choice(question, options, context="")

Pick ONE of 2-100 mutually exclusive options. Returns probabilities over all options (near-ties are visible), confidence, and the runner-up.

{"choice": "E1", "confidence": 0.67,
 "probabilities": {"E1": 0.72, "E6": 0.2, "E5": 0.05, "E2": 0.01, "E3": 0.01, "E4": 0.01},
 "runner_up": "E6", "model": "jev-1.13.0", "latency_ms": 678,
 "usage": {"input_tokens": 1677, "output_tokens": 66}}

score(question, levels, context="")

Grade on an ordered rubric of 2-8 levels. score is a fractional 0-based index: 2.22 with levels ["minor","moderate","severe","critical"] means severe, leaning critical.

{"score": 2.22, "nearest_level": "severe", "confidence": 0.59,
 "probabilities": {"severe": 0.6, "critical": 0.2, "moderate": 0.2}, "...": "..."}

noul(question, context="")

Yes/no with a 0-1 degree (>= 0.5 leans yes). No probability list — the degree is the answer.

{"noul": 0.76, "verdict": "yes", "model": "jev-1.13.0", "latency_ms": 402, "usage": {"...": "..."}}

classify(items, options, question=..., context="")

Batch-label up to 100 items against one shared category set. One choice call per item, aggregated:

{"results": [{"item": "ticket #1", "choice": "billing", "confidence": 0.81, "probabilities": {"...": "..."}}],
 "summary": {"billing": 12, "bug": 7, "howto": 3},
 "usage": {"input_tokens": 8210, "output_tokens": 210, "calls": 22, "cached_calls": 0}}

setup(api_key)

One-time onboarding: verifies the key with a live call, stores it at ~/.config/jev-mcp/key (0600), never echoes it. An env var TYPESAFE_API_KEY always wins over the stored file.

Caching (off by default)

Set JEVMCP_CACHE=1 to enable. The cache key is the SHA-256 of the exact question payload, so:

• Identical repeated decisions (retries, re-runs, deterministic pipelines) return in ~0 ms at zero API cost; usage then reports {"cached": true}.
• classify benefits automatically: duplicate items inside one batch are single-billed.

Keep it off when decisions must stay fresh (live triage of changing data). Cache files live in ~/.cache/jev-mcp/ (override with JEVMCP_CACHE_DIR); delete them anytime.

Configuration

Variable	Default	Purpose
TYPESAFE_API_KEY	—	API key (env wins over the file written by setup)
JEVMCP_MODEL	jev-latest	Model name sent to the API
JEVMCP_BASE_URL	https://api.typesafe.ai/v1/systemone	Point at a compatible gateway (experimental)
JEVMCP_CACHE	off	1/true enables the response cache
JEVMCP_CACHE_DIR	~/.cache/jev-mcp	Cache location
JEVMCP_CONFIG_DIR	~/.config/jev-mcp	Where setup stores the key

Note on OpenRouter: Jev was announced for OpenRouter (~typesafe/jev-latest), but at publish time it does not appear in OpenRouter's public model catalog, and we could not verify a compatible call shape. If you route Jev through a gateway, set JEVMCP_BASE_URL accordingly and please open an issue with your findings.

Decisions, not explanations

Jev's contract is: a decision, calibrated probabilities, and nothing else — no rationale text. That is why it is fast and cheap. When your assistant narrates "jev chose E1 because...", that explanation is the assistant's interpretation of the numbers, not Jev's output. For formal reports (root-cause analyses, review verdicts), either let the LLM reason itself, or use the two-step pattern — Jev decides, LLM explains, clearly labeled.

Benchmarks

Measured 2026-09 against jev-1.13.0, single questions, real sessions:

Call	Latency	Input tokens	Output tokens
choice, 6 options	615-678 ms	344-1677	31-66
score, 3 levels	~500 ms	~350	~30
noul	~400 ms	~300	~25

At $42 / 1B input tokens a typical call costs ≈ $0.00002 — roughly two orders of magnitude below a frontier-LLM judgment call.

Alternatives (fair and square)

• jkudish/jev-mcp — Node/npm, ten opinionated workflow tools (verify, screen, rerank, gate...). Pick it if you want ready-made agent-safety workflows.
• itsmostafa/typesafe-mcp — Go binary, one generic evaluate tool, one-command client setup.

jev-mcp-server is the close-to-the-metal option: the three official question types, named exactly as TypeSafe names them, with batch classify, bilingual docs, and measured numbers. Pick whichever fits your taste — they're all MIT.

Development

uv sync
uv run ruff check .
uv run pytest -q

Tests are fully offline (the HTTP layer is mocked; CI never spends API credits).

License

MIT