jev-mcp-server 0.1.0__py3-none-any.whl

jev_mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""jev-mcp-server: MCP server for Jev (TypeSafe System One)."""
+
+__version__ = "0.1.0"

jev_mcp_server/cache.py

@@ -0,0 +1,51 @@
+"""Optional response cache (OFF by default).
+
+Enable with ``JEVMCP_CACHE=1``. The cache key is the SHA-256 of the exact
+question payload (model, question type, criteria/levels, question, context),
+so an identical decision repeated within a run returns in ~0 ms at zero API
+cost and ``usage`` is reported as ``{"cached": true}``. Keep it off when
+decisions must stay fresh (e.g. live triage of changing data).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+
+from . import config
+
+
+def _hash(payload: dict) -> str:
+    canonical = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _path(payload: dict):
+    return config.cache_dir() / f"{_hash(payload)}.json"
+
+
+def lookup(payload: dict) -> dict | None:
+    if not config.cache_enabled():
+        return None
+    try:
+        return json.loads(_path(payload).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def store(payload: dict, answer: dict) -> None:
+    if not config.cache_enabled():
+        return
+    directory = config.cache_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    tmp_path = directory / f"{_hash(payload)}.json.tmp"
+    try:
+        with open(tmp_path, "w", encoding="utf-8") as handle:
+            json.dump(answer, handle, ensure_ascii=False)
+        os.replace(tmp_path, _path(payload))
+    except OSError:
+        try:
+            tmp_path.unlink()
+        except OSError:
+            pass

jev_mcp_server/client.py

@@ -0,0 +1,63 @@
+"""Thin HTTP client for the TypeSafe System One API."""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+
+from . import __version__, config
+
+RETRY_STATUS = {429, 503, 529}
+USER_AGENT = f"jev-mcp-server/{__version__} (+https://github.com/wangkuangkuang/jev-mcp-server)"
+MISSING_KEY_MESSAGE = (
+    "No TypeSafe API key found. Either set TYPESAFE_API_KEY in the server environment, "
+    "or call the `setup` tool once with your key. Get a key at https://console.typesafe.ai/settings/keys"
+)
+
+_client: httpx.Client | None = None
+
+
+def _http() -> httpx.Client:
+    global _client
+    if _client is None:
+        _client = httpx.Client(http2=True, timeout=25, headers={"User-Agent": USER_AGENT})
+    return _client
+
+
+def ask(questions: dict) -> dict:
+    """Send one or more typed questions to System One and return the full response."""
+    key = config.resolve_key()
+    if not key:
+        raise RuntimeError(MISSING_KEY_MESSAGE)
+    body = {"model": config.model_name(), "state": {}, "questions": questions}
+    for attempt in range(3):
+        try:
+            response = _http().post(config.base_url(), json=body, headers={"Authorization": f"Bearer {key}"})
+        except httpx.HTTPError as error:
+            raise RuntimeError(f"TypeSafe connection failed ({type(error).__name__}); no decision made.") from None
+        if response.status_code in RETRY_STATUS and attempt < 2:
+            time.sleep(0.5 * 2**attempt)
+            continue
+        if response.is_error:
+            raise RuntimeError(f"TypeSafe returned HTTP {response.status_code}: {response.text[:200]}")
+        return response.json()
+    raise RuntimeError("TypeSafe unavailable after retries; no decision made.")
+
+
+def verify_key(key: str) -> dict:
+    """Prove a key works with a cheap live call before storing it."""
+    body = {
+        "model": config.model_name(),
+        "state": {},
+        "questions": {
+            "handshake": {"type": "noul", "instructions": {"question": "Is the sky blue?", "context": "key verification"}}
+        },
+    }
+    try:
+        response = _http().post(config.base_url(), json=body, headers={"Authorization": f"Bearer {key.strip()}"})
+    except httpx.HTTPError as error:
+        raise RuntimeError(f"TypeSafe connection failed ({type(error).__name__}); key NOT stored.") from None
+    if response.is_error:
+        raise RuntimeError(f"Key rejected (HTTP {response.status_code}); key NOT stored.")
+    return response.json()

jev_mcp_server/config.py

@@ -0,0 +1,64 @@
+"""Key and runtime configuration resolution.
+
+Precedence for the TypeSafe API key:
+1. ``TYPESAFE_API_KEY`` environment variable
+2. key file written by the ``setup`` tool (``~/.config/jev-mcp/key`` by default)
+
+All directories can be relocated via environment variables, mainly for tests.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+CONFIG_DIR_ENV = "JEVMCP_CONFIG_DIR"
+CACHE_DIR_ENV = "JEVMCP_CACHE_DIR"
+DEFAULT_CONFIG_DIR = Path.home() / ".config" / "jev-mcp"
+DEFAULT_CACHE_DIR = Path.home() / ".cache" / "jev-mcp"
+TRUTHY = {"1", "true", "yes", "on"}
+
+
+def config_dir() -> Path:
+    return Path(os.environ.get(CONFIG_DIR_ENV, str(DEFAULT_CONFIG_DIR)))
+
+
+def key_file() -> Path:
+    return config_dir() / "key"
+
+
+def resolve_key() -> str | None:
+    env_key = os.environ.get("TYPESAFE_API_KEY", "").strip()
+    if env_key:
+        return env_key
+    try:
+        value = key_file().read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    return value or None
+
+
+def save_key(api_key: str) -> Path:
+    directory = config_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    os.chmod(directory, 0o700)
+    target = key_file()
+    target.write_text(api_key.strip() + "\n", encoding="utf-8")
+    os.chmod(target, 0o600)
+    return target
+
+
+def base_url() -> str:
+    return os.environ.get("JEVMCP_BASE_URL", "https://api.typesafe.ai/v1/systemone").rstrip("/")
+
+
+def model_name() -> str:
+    return os.environ.get("JEVMCP_MODEL", "jev-latest")
+
+
+def cache_enabled() -> bool:
+    return os.environ.get("JEVMCP_CACHE", "").strip().lower() in TRUTHY
+
+
+def cache_dir() -> Path:
+    return Path(os.environ.get(CACHE_DIR_ENV, str(DEFAULT_CACHE_DIR)))

jev_mcp_server/server.py

@@ -0,0 +1,297 @@
+"""MCP server: Jev (TypeSafe System One) judgment tools.
+
+Tools map 1:1 to the official System One question types — ``choice``, ``score``,
+``noul`` — plus ``classify`` (batch) and ``setup`` (one-time key onboarding).
+
+Jev returns decisions and calibrated probabilities, never explanations: any
+"reason" an assistant adds on top is its own interpretation of the numbers.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import time
+
+from mcp.server.fastmcp import FastMCP
+
+from . import cache, client, config
+
+mcp = FastMCP("jev")
+
+MAX_OPTIONS = 100
+MAX_ITEMS = 100
+
+
+def _answer(questions: dict) -> tuple[dict, bool]:
+    """Cache-aware entry to the API. Returns (response, from_cache)."""
+    cached = cache.lookup(questions)
+    if cached is not None:
+        return cached, True
+    result = client.ask(questions)
+    cache.store(questions, result)
+    return result, False
+
+
+def _meta(result: dict, started: float, from_cache: bool) -> dict:
+    usage = result.get("usage", {})
+    if from_cache:
+        usage = {"input_tokens": 0, "output_tokens": 0, "cached": True}
+    return {
+        "model": result.get("model", "jev-latest"),
+        "latency_ms": round((time.perf_counter() - started) * 1000),
+        "usage": usage,
+    }
+
+
+def _validated_choice(answer: dict, ids: set) -> dict:
+    try:
+        probs = answer["probabilities"]
+        numbers = [*probs.values(), answer["confidence"]]
+        valid = (
+            answer["choice"] in ids
+            and set(probs) == ids
+            and all(type(n) in (int, float) and math.isfinite(n) and 0 <= n <= 1 for n in numbers)
+            and abs(sum(probs.values()) - 1) < 0.02
+            and probs[answer["choice"]] >= max(probs.values()) - 1e-6
+        )
+    except (KeyError, TypeError, ValueError):
+        valid = False
+    if not valid:
+        raise ValueError("Invalid TypeSafe response; no decision returned.")
+    return answer
+
+
+def _validated_options(options: dict[str, str]) -> None:
+    if len(options) != len(set(options)) or not 2 <= len(options) <= MAX_OPTIONS:
+        raise ValueError(f"Provide between 2 and {MAX_OPTIONS} uniquely-keyed options.")
+    if any(not str(k).strip() or not str(v).strip() for k, v in options.items()):
+        raise ValueError("Option ids and descriptions must be non-empty strings.")
+
+
+@mcp.tool()
+def choice(question: str, options: dict[str, str], context: str = "") -> str:
+    """Ask Jev (TypeSafe System One) to pick ONE of 2-100 mutually exclusive options, with calibrated probabilities.
+
+    The official `choice` question type — for fast, cheap structured decisions:
+    triage, routing, classification, prioritization, tie-breaking among enumerated
+    candidates. Returns probabilities over ALL options (not just the winner), so
+    near-ties are visible. NOT for open-ended generation or multi-step reasoning —
+    use an LLM for those.
+
+    Args:
+        question: The decision, e.g. "Which error class is most likely the root cause?"
+        options: Mapping of short unique id -> one-line description. 2-100 options.
+        context: Optional background facts that inform the decision. Keep it short.
+
+    Returns:
+        JSON string: {choice, confidence, probabilities (sorted desc), runner_up,
+                      model, latency_ms, usage}
+    """
+    _validated_options(options)
+    started = time.perf_counter()
+    result, from_cache = _answer(
+        {"decision": {"type": "choice", "criteria": options, "instructions": {"question": question, "context": context}}}
+    )
+    answer = _validated_choice(result.get("answers", {}).get("decision", {}), set(options))
+    probs = dict(sorted(answer["probabilities"].items(), key=lambda kv: -kv[1]))
+    ranked = list(probs)
+    return json.dumps(
+        {
+            "choice": answer["choice"],
+            "confidence": answer["confidence"],
+            "probabilities": probs,
+            "runner_up": ranked[1] if len(ranked) > 1 else None,
+            **_meta(result, started, from_cache),
+        },
+        ensure_ascii=False,
+    )
+
+
+@mcp.tool()
+def score(question: str, levels: list[str], context: str = "") -> str:
+    """Ask Jev (TypeSafe System One) to grade something on an ORDERED scale of 2-8 levels.
+
+    The official `score` question type — risk/severity/quality rubrics, e.g.
+    levels ["minor", "moderate", "severe", "critical"]. Returns a fractional
+    0-based index into `levels` (1.88 = between levels[1] and levels[2], leaning
+    to levels[2]), plus confidence and per-level probabilities.
+
+    Args:
+        question: What to grade, e.g. "Regression risk of renaming public config key X".
+        levels: 2-8 unique ordered scale points, low to high.
+        context: Optional background facts. Keep it short.
+
+    Returns:
+        JSON string: {score, nearest_level, confidence, probabilities (sorted desc),
+                      model, latency_ms, usage}
+    """
+    if not 2 <= len(levels) <= 8:
+        raise ValueError("Provide between 2 and 8 levels.")
+    if len(set(levels)) != len(levels) or any(not str(level).strip() for level in levels):
+        raise ValueError("Levels must be unique, non-empty strings.")
+    started = time.perf_counter()
+    result, from_cache = _answer(
+        {"score": {"type": "score", "criteria": levels, "instructions": {"question": question, "context": context}}}
+    )
+    answer = result.get("answers", {}).get("score", {})
+    try:
+        probs = answer["probabilities"]
+        value = answer["score"]
+        valid = (
+            type(value) in (int, float)
+            and math.isfinite(value)
+            and 0 <= value <= len(levels) - 1
+            and set(probs) == {str(i) for i in range(len(levels))}
+            and all(type(v) in (int, float) and 0 <= v <= 1 for v in probs.values())
+            and abs(sum(probs.values()) - 1) < 0.02
+        )
+    except (KeyError, TypeError, ValueError):
+        valid = False
+    if not valid:
+        raise ValueError("Invalid TypeSafe response; no score returned.")
+    readable = {levels[int(k)]: v for k, v in probs.items()}
+    nearest = min(range(len(levels)), key=lambda i: abs(i - value))
+    return json.dumps(
+        {
+            "score": value,
+            "nearest_level": levels[nearest],
+            "confidence": answer.get("confidence"),
+            "probabilities": dict(sorted(readable.items(), key=lambda kv: -kv[1])),
+            **_meta(result, started, from_cache),
+        },
+        ensure_ascii=False,
+    )
+
+
+@mcp.tool()
+def noul(question: str, context: str = "") -> str:
+    """Ask Jev (TypeSafe System One) a yes/no question; returns a 0-1 degree (>= 0.5 leans yes).
+
+    The official `noul` question type — fast, cheap binary checks: "is this change
+    breaking?", "does this log line match the reported symptom?". No probability
+    list, just the degree. NOT for questions that need multi-step reasoning — use
+    an LLM for those.
+
+    Args:
+        question: A yes/no question, e.g. "Is renaming a public config key a breaking change?"
+        context: Optional background facts. Keep it short.
+
+    Returns:
+        JSON string: {noul, verdict, model, latency_ms, usage}
+    """
+    started = time.perf_counter()
+    result, from_cache = _answer({"noul": {"type": "noul", "instructions": {"question": question, "context": context}}})
+    answer = result.get("answers", {}).get("noul", {})
+    value = answer.get("noul")
+    if type(value) not in (int, float) or not math.isfinite(value) or not 0 <= value <= 1:
+        raise ValueError("Invalid TypeSafe response; no verdict returned.")
+    return json.dumps({"noul": value, "verdict": "yes" if value >= 0.5 else "no", **_meta(result, started, from_cache)}, ensure_ascii=False)
+
+
+@mcp.tool()
+def classify(
+    items: list[str],
+    options: dict[str, str],
+    question: str = "Which category does this item belong to?",
+    context: str = "",
+) -> str:
+    """Batch-classify up to 100 items against ONE shared set of categories using Jev.
+
+    Runs the official `choice` question type once per item and aggregates the
+    results — routing support tickets, labeling log lines, triaging inbox items
+    against your own label set. Much cheaper and faster than an LLM for
+    mechanical labeling.
+
+    Args:
+        items: 1-100 non-empty strings to classify.
+        options: Mapping of short unique id -> one-line category description. 2-100 options.
+        question: Per-item question; the item itself is appended automatically.
+        context: Optional background facts shared by all items.
+
+    Returns:
+        JSON string: {results: [{item, choice, confidence, probabilities}], summary
+                      (counts per choice, sorted desc), model, total_latency_ms,
+                      usage: {input_tokens, output_tokens, calls, cached_calls}}
+    """
+    if not 1 <= len(items) <= MAX_ITEMS:
+        raise ValueError(f"Provide between 1 and {MAX_ITEMS} items.")
+    if any(not str(item).strip() for item in items):
+        raise ValueError("Items must be non-empty strings.")
+    _validated_options(options)
+    ids = set(options)
+    results = []
+    summary: dict[str, int] = {}
+    usage_in = usage_out = calls = cached_calls = 0
+    model = "jev-latest"
+    started = time.perf_counter()
+    for item in items:
+        payload = {
+            "decision": {
+                "type": "choice",
+                "criteria": options,
+                "instructions": {"question": f"{question}\nItem: {item}", "context": context},
+            }
+        }
+        result, from_cache = _answer(payload)
+        answer = _validated_choice(result.get("answers", {}).get("decision", {}), ids)
+        picked = answer["choice"]
+        summary[picked] = summary.get(picked, 0) + 1
+        results.append(
+            {
+                "item": item,
+                "choice": picked,
+                "confidence": answer["confidence"],
+                "probabilities": dict(sorted(answer["probabilities"].items(), key=lambda kv: -kv[1])),
+            }
+        )
+        model = result.get("model", model)
+        item_usage = result.get("usage", {})
+        if from_cache:
+            cached_calls += 1
+        else:
+            usage_in += item_usage.get("input_tokens", 0)
+            usage_out += item_usage.get("output_tokens", 0)
+            calls += 1
+    return json.dumps(
+        {
+            "results": results,
+            "summary": dict(sorted(summary.items(), key=lambda kv: -kv[1])),
+            "model": model,
+            "total_latency_ms": round((time.perf_counter() - started) * 1000),
+            "usage": {"input_tokens": usage_in, "output_tokens": usage_out, "calls": calls, "cached_calls": cached_calls},
+        },
+        ensure_ascii=False,
+    )
+
+
+@mcp.tool()
+def setup(api_key: str) -> str:
+    """One-time onboarding: verify a TypeSafe API key with a live call, then store it locally.
+
+    Use when TYPESAFE_API_KEY is not set in the server environment: pass your key
+    once (get one at https://console.typesafe.ai/settings/keys). It is verified
+    against the live API, then saved to ~/.config/jev-mcp/key (permissions 0600)
+    and never echoed back. An existing TYPESAFE_API_KEY env var always takes
+    precedence over the stored file.
+
+    Args:
+        api_key: Your TypeSafe API key (from console.typesafe.ai/settings/keys).
+
+    Returns:
+        JSON string: {ok, stored_path, verified}
+    """
+    key = str(api_key).strip()
+    if not key:
+        raise ValueError("api_key must be a non-empty string.")
+    client.verify_key(key)
+    path = config.save_key(key)
+    return json.dumps({"ok": True, "stored_path": str(path), "verified": True}, ensure_ascii=False)
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

jev_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,213 @@
+Metadata-Version: 2.5
+Name: jev-mcp-server
+Version: 0.1.0
+Summary: Faithful MCP server for Jev (TypeSafe System One): the three official question types — choice, score, noul — plus batch classify. Calibrated probabilities for coding agents.
+Project-URL: Homepage, https://github.com/wangkuangkuang/jev-mcp-server
+Project-URL: Repository, https://github.com/wangkuangkuang/jev-mcp-server
+Project-URL: Issues, https://github.com/wangkuangkuang/jev-mcp-server/issues
+Project-URL: Changelog, https://github.com/wangkuangkuang/jev-mcp-server/blob/main/CHANGELOG.md
+Author: wangkuangkuang
+License: MIT
+License-File: LICENSE
+Keywords: classifier,decision,jev,llm,mcp,model-context-protocol,routing,system-one,typesafe
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx[http2]>=0.27
+Requires-Dist: mcp<2,>=1.9
+Description-Content-Type: text/markdown
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+# jev-mcp-server
+
+[![CI](https://github.com/wangkuangkuang/jev-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/wangkuangkuang/jev-mcp-server/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/jev-mcp-server)](https://pypi.org/project/jev-mcp-server/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/jev-mcp-server/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**MCP server for [Jev](https://typesafe.ai) (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](#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](https://typesafe.ai) 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](https://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
+
+```bash
+claude mcp add jev --env TYPESAFE_API_KEY=YOUR_KEY -- uvx jev-mcp-server
+```
+
+### Codex (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.jev]
+command = "uvx"
+args = ["jev-mcp-server"]
+env = { TYPESAFE_API_KEY = "YOUR_KEY" }
+```
+
+### OpenCode (`~/.config/opencode/opencode.json`)
+
+```json
+{
+  "mcp": {
+    "jev": { "type": "local", "command": ["uvx", "jev-mcp-server"], "enabled": true }
+  }
+}
+```
+
+### pi (`~/.pi/agent/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "jev": { "command": "uvx", "args": ["jev-mcp-server"], "lifecycle": "lazy" }
+  }
+}
+```
+
+### Any stdio MCP client
+
+```json
+{ "command": "uvx", "args": ["jev-mcp-server"] }
+```
+
+### From source (this repo)
+
+```json
+{ "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.
+
+```json
+{"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*.
+
+```json
+{"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.
+
+```json
+{"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:
+
+```json
+{"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](https://typesafe.ai) a typical call costs ≈ $0.00002 — roughly two orders of magnitude below a frontier-LLM judgment call.
+
+## Alternatives (fair and square)
+
+- [jkudish/jev-mcp](https://github.com/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](https://github.com/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
+
+```bash
+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](LICENSE)

jev_mcp_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+jev_mcp_server/__init__.py,sha256=laVEHZoP3DMmo4xcJFACtkbrpiqJE4XtwZbpr5eE5bw,87
+jev_mcp_server/cache.py,sha256=p-WlCur6dMGaZmRnBjeoHhQcD6h0coUyNIteLc-b1CQ,1516
+jev_mcp_server/client.py,sha256=KoydREH5k-DUTfHQJ2zwPXirQVNtOXOU4wrXSmy-FHk,2458
+jev_mcp_server/config.py,sha256=-GLo5L7rw0MWANH2UV-JvbVvk0wiKCqqSG-RjbbD2w8,1703
+jev_mcp_server/server.py,sha256=_l-PoBe1isg6OonlYKz5bepPAFBha6Q8BgB25F1w4ZM,11725
+jev_mcp_server-0.1.0.dist-info/METADATA,sha256=DY5OI8pGbTvHhn0XsXpJZlgtSU3xxp4Cy6h0WrhEaqg,9782
+jev_mcp_server-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+jev_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=z1C2nPCxZkmUHp-xMFUKjNrw74up5SbE938j-XxXJwc,62
+jev_mcp_server-0.1.0.dist-info/licenses/LICENSE,sha256=KpMvmewxpr-bKh8ksJSS6ENHKp12dV1sZFPNNNdw24s,1071
+jev_mcp_server-0.1.0.dist-info/RECORD,,

jev_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

jev_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jev-mcp-server = jev_mcp_server.server:main

jev_mcp_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wangkuangkuang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.