# jev-mcp

MCP server wrapping [TypeSafe](https://docs.typesafe.ai/)'s **Jev** System One
models. Instead of prompt-and-parse, agents get typed judgments they can use
directly in code: yes/no probabilities, multiple-choice selections with
distributions, and rubric-based scores.

## Tools

| Tool | What it does | Returns |
| --- | --- | --- |
| `jev_evaluate` | Evaluate `state` against a map of typed questions in one call (they run in parallel) | `{model, answers, usage}` |
| `jev_noul` | Yes/no judgment | `{type, noul}` — `0` = no … `1` = yes, near `0.5` = uncertain |
| `jev_choice` | Pick one option from `criteria: {"option": "rubric…"}` | `{choice, probabilities, confidence}` |
| `jev_score` | Rate along 2–10 ordered level descriptions | `{score, legend, probabilities, confidence}` |
| `jev_models` | List models your key can use | `{models: [{name, …}]}` |

Every tool takes `state` (string, object, or array — the content to judge),
an optional `model` (default `"jev-latest"`), and an optional `endpoint`
(`"direct"` or `"zen"`, default `"direct"`).

## Prerequisites

- Python 3.10+ and [`uv`](https://docs.astral.sh/uv/) (or plain `pip`)
- A TypeSafe API key → `TYPESAFE_API_KEY`
  - Optional: an OpenCode Zen key → `OPENCODE_API_KEY`, only if you want `endpoint="zen"` (models `jev-1.13` / `jev-1.13-free`)

## Quickstart

```bash
git clone https://github.com/rajasekharponakala/jev-mcp.git
cd jev-mcp
cp .env.example .env   # then put your key in .env (never commit it)
uv run --with fastmcp --with httpx server.py
```

Or with an installed environment:

```bash
pip install -e .
export TYPESAFE_API_KEY=...
jev-mcp
```

## Client configuration

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

```jsonc
{
  "mcp": {
    "servers": {
      "jev": {
        "type": "local",
        "command": ["uv", "run", "--with", "fastmcp", "--with", "httpx", "server.py"],
        "cwd": "/path/to/jev-mcp",
        "environment": {
          "TYPESAFE_API_KEY": "{env:TYPESAFE_API_KEY}"
        }
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add jev -e TYPESAFE_API_KEY=... -- uv run --with fastmcp --with httpx /path/to/jev-mcp/server.py
```

### Codex CLI (`~/.codex/config.toml`)

```bash
codex mcp add jev --env TYPESAFE_API_KEY=... -- uv run --with fastmcp --with httpx /path/to/jev-mcp/server.py
```

or manually:

```toml
[mcp_servers.jev]
command = "uv"
args = ["run", "--with", "fastmcp", "--with", "httpx", "/path/to/jev-mcp/server.py"]
env = { TYPESAFE_API_KEY = "..." }
```

### Gemini CLI (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "jev": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "--with", "httpx", "/path/to/jev-mcp/server.py"],
      "env": { "TYPESAFE_API_KEY": "..." }
    }
  }
}
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "jev": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "--with", "httpx", "/path/to/jev-mcp/server.py"],
      "env": { "TYPESAFE_API_KEY": "..." }
    }
  }
}
```

### Windsurf (`~/.codeium/windsurf/mcp_config.json`)

```json
{
  "mcpServers": {
    "jev": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "--with", "httpx", "/path/to/jev-mcp/server.py"],
      "env": { "TYPESAFE_API_KEY": "..." }
    }
  }
}
```

### Cline (`~/.cline/mcp.json`, or `cline mcp` wizard)

```json
{
  "mcpServers": {
    "jev": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "--with", "httpx", "/path/to/jev-mcp/server.py"],
      "env": { "TYPESAFE_API_KEY": "..." },
      "disabled": false
    }
  }
}
```

### Goose (`~/.config/goose/config.yaml`)

```bash
goose session --with-extension "jev:TYPESAFE_API_KEY=... uv run --with fastmcp --with httpx /path/to/jev-mcp/server.py"
```

or persist in config:

```yaml
extensions:
  jev:
    name: Jev
    cmd: uv
    args: ["run", "--with", "fastmcp", "--with", "httpx", "/path/to/jev-mcp/server.py"]
    enabled: true
    envs: { "TYPESAFE_API_KEY": "..." }
    type: stdio
    timeout: 300
```

### Claude Desktop / VS Code / other MCP JSON clients

```json
{
  "mcpServers": {
    "jev": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "--with", "httpx", "/path/to/jev-mcp/server.py"],
      "env": { "TYPESAFE_API_KEY": "..." }
    }
  }
}
```

(VS Code: same shape in `~/.vscode/mcp.json`.)

### FastMCP one-liner

The server object is named `mcp`, so FastMCP can install it directly:

```bash
fastmcp install claude-code /path/to/jev-mcp/server.py
```

then add `TYPESAFE_API_KEY` via that client's config.

## Example

```jsonc
// tool call: jev_choice
{
  "state": "Help! My payouts have been failing for 3 days.",
  "instructions": "Which team should handle this?",
  "criteria": {
    "billing": "Payments, invoicing, refunds",
    "technical": "Bugs, outages, integrations",
    "sales": "Pricing, upgrades, new accounts"
  }
}
// → {"choice": "billing", "probabilities": {"billing": 0.88, ...}, "confidence": 0.81}
```

See the [TypeSafe docs](https://docs.typesafe.ai/llms.txt) (source of truth) and
the [API reference](https://docs.typesafe.ai/api.md) for question design:
one narrow judgment per question, batch independent questions, keep policy and
thresholds in your code.

## Development

```bash
uv run --with fastmcp --with httpx python -c "
import asyncio, server
print(sorted(t.name for t in asyncio.run(server.mcp.list_tools())))
"
```

## License

[AGPL-3.0-only](LICENSE). Copyright (c) 2026 rajasekharponakala.