typesafe-mcp

Deterministic decisions for AI agents — powered by TypeSafe AI's Jev.

npm · Documentation · Issues · Releases

An MCP server that wraps Jev, TypeSafe AI's System One decision model, so any agent can ask typed questions and get structured, auditable answers back — probabilities, confidence, and a threshold-gated act / review / abstain verdict. No generated text, no vibes.

bunx typesafe-mcp        # stdio server — add to any MCP host config, done

flowchart LR
    A[Agent] -->|tool call| M[typesafe-mcp]
    M -->|state + typed questions| J[TypeSafe Jev API]
    J --> M
    M -->|probability · certainty · decision| A

• Jev — TypeSafe AI's hosted decision model (jev-latest / jev-1.13.0). Evaluates a state plus typed questions (Noul / Choice / Score) and returns structured answers. It does not generate text, code, or explanations.

• TypeSafe — the company and API (api.typesafe.ai/v1/systemone) plus official JS/Python SDKs.

• This server — a type-safe MCP wrapper. decision is computed in code by this server, never Jev's own opinion about whether you may proceed.

Install

Add to any MCP host config — Cursor, Claude Desktop, Claude Code, Windsurf, Cline, or a custom stdio client:

{
  "mcpServers": {
    "jev": {
      "command": "bunx",
      "args": ["typesafe-mcp"],
      "env": {
        "TYPESAFE_API_KEY": "<paste-your-key-here>",
        "TYPESAFE_DEFAULT_MODEL": "jev-latest"
      }
    }
  }
}

Requires Bun on PATH. That's it — the host spawns a bundled single-file build over stdio. Without a key the server still connects and lists tools; calls return a CONFIG: error telling you where to put it.

git clone https://github.com/MarkChu-git/typesafe-mcp.git && cd typesafe-mcp
bun install
bun run start        # stdio server — exits immediately if stdin closes

Point the host at the repo path instead — see examples/stdio.mcp.json and replace /ABSOLUTE/PATH/TO/typesafe-mcp (cursor.mcp.json / claude-desktop.json are the same shape for their respective hosts).

Related MCP server: jev-judge-mcp

What it looks like

// jev_check — "Does this ticket convey urgency?"
// state: "Help! My payouts have been failing for 3 days."
{
  "type": "noul",
  "probability": 0.95,
  "answer": true,
  "certainty": 0.9,            // |0.95 − 0.5| × 2
  "decision": "act",           // 0.9 ≥ act_above 0.8
  "thresholds": { "act_above": 0.8, "review_above": 0.5 },
  "model": "jev-1.13.0",
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

Tools

Every answer also carries certainty, decision, thresholds, model, and usage.

Decision gating

Pin model to a versioned id (e.g. jev-1.13.0) once thresholds are tuned — jev-latest can drift under a calibrated gate.

中文提示：question/state 支持中文，官方建议英文——Jev 按字面理解，中文问题准确率略低。decision/certainty/thresholds 语义与语言无关。

Errors

Every failure returns isError: true with a category prefix:

Keys are redacted from error text; diagnostics go to stderr, never stdout.

Development

Bun only — no Node/npm/pnpm/yarn/npx.

bun test                 # unit + in-process MCP tests (no key needed)
bun run test:integration # live API — skips entirely without TYPESAFE_API_KEY
bun run typecheck        # tsc --noEmit
bun run lint             # oxlint
bun run inspect          # MCP Inspector over stdio
bun run scripts/record-fixture.ts   # re-record tests/fixtures from the real API (needs key)

CI: tsc + oxlint + bun test on Ubuntu (required) and macOS/Windows, CodeQL, dependency review, actionlint, zizmor. Releases publish via OIDC trusted publishing with --provenance — no long-lived npm token. See CONTRIBUTING.md.

Roadmap

Not implemented yet:

• Streamable HTTP transport (createMcpHandler + Hono/Bun.serve) for remote/shared deployments

• Object-shaped instructions on questions (structured prompts referencing state fields)

• Opinionated tools (jev_gate / jev_screen / jev_match) — pending the first business-scenario decision

License

MIT · Research notes: docs/research-jev-typesafe-mcp.md · Plan: docs/plan-build-jev-mcp.md