typesafe-mcp

An MCP server that wraps Jev, TypeSafe AI's System One decision model, so any agent can ask typed questions and get structured answers back.

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

• TypeSafe: the company and API (https://api.typesafe.ai/v1/systemone) plus official JS/Python SDKs. The name is not a generic TypeScript MCP library.

• This repo: a type-safe MCP wrapper. decision (act/review/abstain) is computed by this server in code — it is never Jev's own opinion about whether you may proceed.

Install and run

Published to npm as a single-file Bun bundle — no clone needed:

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

Paste that block into any MCP host's config (Cursor ~/.cursor/mcp.json, Claude Desktop claude_desktop_config.json, Claude Code .claude.json, Windsurf, Cline — all the same shape). Requires Bun on PATH.

Running from source instead:

bun install
bun run start        # stdio server — exits immediately if stdin closes

then point your host at the repo path — see examples/stdio.mcp.json and replace /ABSOLUTE/PATH/TO/typesafe-mcp with this repo's absolute path (examples/cursor.mcp.json and examples/claude-desktop.json are the same JSON shape — the only difference is which host file it goes in).

Never commit real keys — .cursor/mcp.json, .mcp.json, .env* are gitignored. Without a key the server still connects and lists tools; calls return a CONFIG: error telling you where to put the key.

Related MCP server: aside-jev

Tools

Every answer also carries:

• certainty — Noul: |probability − 0.5| × 2; Choice/Score: API confidence

• decision — act / review / abstain from certainty vs thresholds (default act_above 0.8, review_above 0.5; both overridable per call, review_above ≤ act_above)

• thresholds — the values actually applied, so callers can audit the gate

Pin model to a versioned id (e.g. jev-1.13.0) once you have tuned thresholds — jev-latest can drift under your calibrated gates.

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

Errors

Every failure returns isError: true with a category prefix — CONFIG (missing key), VALIDATION (bad args, names the field), AUTH, RATE_LIMIT (hint: batch via jev_ask), OVERLOADED, TIMEOUT, NETWORK, INVALID_REQUEST, UPSTREAM. Server-side stderr logs mirror the category; API keys are redacted from error text.

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: .github/workflows/ci.yml — frozen lockfile, typecheck, oxlint, bun test on Ubuntu (required) + macOS/Windows. CodeQL and a security workflow (audit, dependency review, actionlint, zizmor) also run.

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

Status

• P0 done: scaffold + jev_models/jev_check over stdio

• P1 done: jev_classify/jev_score/jev_ask

• Published to npm as typesafe-mcp — bunx typesafe-mcp runs the bundled single-file build (bun run build → dist/, rebuilt on npm publish via prepack)

• Research notes: docs/research-jev-typesafe-mcp.md; plan: docs/plan-build-jev-mcp.md

• GitHub Flow + Conventional Commits; main requires PR + CI, Conventional title, and both platform checks