# Jev MCP Proxy

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![Protocol](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/license-MIT-purple.svg)](LICENSE)

A high-performance [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) proxy server that routes System One evaluation requests from AI agent skills directly to TypeSafe AI's **Jev** model.

---

## Background: System One & Jev

As introduced by TypeSafe AI in [*Introducing System One Models & Jev*](https://typesafe.ai/blog/introducing-system-one-models-and-jev), **System One models** represent a new class of frontier AI designed for automation within code. Rather than generating conversational strings token-by-token, Jev takes program state and answers typed questions in parallel with calibrated probabilities.

- **Fast & Hardware-Aware**: 70ms–500ms end-to-end response time.
- **Typed Outputs**: Strictly evaluates against defined rubrics (no string hallucinations or schema mismatches).
- **Calibrated Uncertainty**: Communicates exact confidence scores and probabilities.

This MCP server acts as the **dedicated router** between agent skills (in Google Antigravity, Claude Code, Cursor, etc.) and Jev.

```
┌─────────────────────────────────────────────────────────────┐
│                       Agent Platform                        │
│             (Google Antigravity / Claude Code)             │
│                                                             │
│   ┌──────────────────┐             ┌────────────────────┐   │
│   │  Routing Skill   │             │  Moderation Skill  │   │
│   └────────┬─────────┘             └─────────┬──────────┘   │
└────────────┼─────────────────────────────────┼──────────────┘
             │           MCP Tools             │
             ▼                                 ▼
┌─────────────────────────────────────────────────────────────┐
│                    Jev MCP Proxy Server                     │
│    (jev_evaluate, jev_choice, jev_noul, jev_score)          │
│                                                             │
│  - JSON-RPC stdio transport                                 │
│  - Auto-retries with exponential backoff on 429 & 529       │
│  - Stderr request tracing & latency measurement             │
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTPS / Bearer Token
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                 TypeSafe AI Jev API                         │
│         (https://api.typesafe.ai/v1/systemone)              │
└─────────────────────────────────────────────────────────────┘
```

---

## Features

- **Lean & Focused**: The only functionality of this MCP server is to route requests to Jev when skills need them.
- **Full Parallel Evaluation**: `jev_evaluate` allows evaluating arbitrary state against multiple typed questions in a single round-trip.
- **Convenience Tool Shortcuts**: High-level tools (`jev_choice`, `jev_noul`, `jev_score`) for common skill operations.
- **Resilience**: Automatic retry logic with exponential backoff for HTTP `429` (Rate Limit) and `529` (Service Overloaded).
- **Live Tracing**: Emits structured timing, token usage, and status traces directly to `stderr` (visible in MCP host logs without interfering with JSON-RPC over stdout).

---

## Exposed MCP Tools

### 1. `jev_evaluate`
Primary batch router for TypeSafe AI Jev. Evaluates state (text or structured data) against multiple typed questions simultaneously.

**Parameters:**
- `state` (`string | object | array`, required): The application state, document, log, or conversation context to evaluate.
- `questions` (`object`, required): Dictionary of question IDs mapping to question definitions.
  - `type`: `"noul"` | `"choice"` | `"score"`
  - `instructions`: Prompt or criteria instructions.
  - `criteria`: Required for `choice` (map of options to descriptions) and `score` (list of level strings). Optional for `noul`.
- `model` (`string`, optional): Jev model version (default: `"jev-latest"`).
- `api_key` (`string`, optional): Override for `TYPESAFE_API_KEY`.

**Example:**
```json
{
  "state": "The user reported: Database pool connection timeout after 30s in checkout service.",
  "questions": {
    "is_incident": {
      "type": "noul",
      "instructions": "Does this indicate a production incident?"
    },
    "service_area": {
      "type": "choice",
      "instructions": "Which domain team owns this?",
      "criteria": {
        "database": "Database servers and connection pooling",
        "billing": "Checkout, credit cards, payment logic",
        "frontend": "UI buttons and rendering"
      }
    }
  }
}
```

---

### 2. `jev_choice`
Categorical classification shortcut. Selects one option from a defined set, returning the selected choice, confidence score, and full probability distribution.

**Parameters:**
- `state` (`string | object | array`): Context to evaluate.
- `instructions` (`string | object | array`): What the model should decide.
- `criteria` (`object`): Dictionary mapping option keys to descriptive rubrics.
- `model` (`string`, optional): Default `"jev-latest"`.
- `question_id` (`string`, optional): Default `"choice"`.

**Example Response:**
```json
{
  "choice": "database",
  "confidence": 0.88,
  "probabilities": {
    "database": 0.88,
    "billing": 0.10,
    "frontend": 0.02
  },
  "usage": { "input_tokens": 140, "output_tokens": 25 }
}
```

---

### 3. `jev_noul`
Binary probability shortcut. Evaluates a yes/no question and returns the calibrated probability ($0.0 \le P \le 1.0$) that the statement is true.

**Parameters:**
- `state` (`string | object | array`): Context to evaluate.
- `instructions` (`string | object | array`): The yes/no question.
- `criteria` (`object`, optional): Optional definitions for `{"true": "...", "false": "..."}`.

**Example Response:**
```json
{
  "probability": 0.95,
  "is_likely": true,
  "usage": { "input_tokens": 98, "output_tokens": 12 }
}
```

---

### 4. `jev_score`
Rubric rating shortcut. Rates state across an ordered rubric of at least two descriptive levels, returning a weighted score and confidence.

**Parameters:**
- `state` (`string | object | array`): Context to evaluate.
- `instructions` (`string | object | array`): Rating criteria.
- `criteria` (`array` of strings): Ordered list of descriptive levels (e.g. `["Low", "Medium", "High", "Critical"]`).

**Example Response:**
```json
{
  "score": 2.8,
  "confidence": 0.84,
  "legend": { "0": "Low", "1": "Medium", "2": "High", "3": "Critical" },
  "probabilities": { "0": 0.0, "1": 0.05, "2": 0.15, "3": 0.80 }
}
```

---

## Installation & Setup

### Prerequisites
- Python 3.10+
- [`uv`](https://github.com/astral-sh/uv) (recommended) or `pip`

```bash
git clone https://github.com/altregubov/jev-antigravity-mcp.git
cd jev-antigravity-mcp
uv sync
```

### Environment Variables
- `TYPESAFE_API_KEY`: Your API key from the [TypeSafe AI Console](https://console.typesafe.ai/keys).
- `TYPESAFE_BASE_URL`: (Optional) Custom API endpoint (default: `https://api.typesafe.ai/v1/systemone`).
- `JEV_DEBUG`: Set to `"1"` (default) to log request traces to `stderr`.

---

## Configuration

### Google Antigravity 2.0

#### Option A: Zero-Install from GitHub via `uvx` (Recommended)
No local repository cloning needed. Antigravity will automatically fetch and run the server in an isolated environment.

Add the following to your global Antigravity MCP configuration (`~/.gemini/config/mcp_config.json`):

```json
{
  "mcpServers": {
    "jev-proxy": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/altregubov/jev-antigravity-mcp",
        "jev-mcp"
      ],
      "env": {
        "TYPESAFE_API_KEY": "YOUR_TYPESAFE_API_KEY"
      }
    }
  }
}
```

#### Option B: Via the Antigravity 2.0 Desktop UI
1. Open the **Antigravity 2.0** desktop app.
2. In the left-hand sidebar, click **Skills & Customizations** (or click the **`...`** menu in the top-right $\rightarrow$ **MCP Servers**).
3. Click **Add MCP Server** (or **+**).
4. Configure as **Stdio Transport**:
   - **Name**: `jev-proxy`
   - **Command**: `uvx`
   - **Arguments**: `--from git+https://github.com/altregubov/jev-antigravity-mcp jev-mcp`
   - **Environment Variables**:
     - `TYPESAFE_API_KEY`: `YOUR_TYPESAFE_API_KEY`
5. Click **Save & Connect**.

#### Option C: Local Development / Cloned Repository
If you cloned the repository locally:

```json
{
  "mcpServers": {
    "jev-proxy": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/jev-antigravity-mcp",
        "jev-mcp"
      ],
      "env": {
        "TYPESAFE_API_KEY": "YOUR_TYPESAFE_API_KEY"
      }
    }
  }
}
```

> **Note**: After adding the server, start a **New Conversation** or click **Refresh** in **Skills & Customizations** to mount the tools (`jev_evaluate`, `jev_choice`, `jev_noul`, `jev_score`).

### Claude Code / Cursor
Add to your Claude Code or Cursor MCP configuration:

```json
{
  "mcpServers": {
    "jev-proxy": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/jev-antigravity-mcp",
        "jev-mcp"
      ],
      "env": {
        "TYPESAFE_API_KEY": "YOUR_TYPESAFE_API_KEY"
      }
    }
  }
}
```

---

## Tracing and Diagnostics

The proxy logs structured traces to `stderr` without interfering with the JSON-RPC communication on `stdout`:

```text
[17:45:03] [jev_proxy] INFO: --> Routing request to JEV: POST https://api.typesafe.ai/v1/systemone | model=jev-latest | questions=['is_incident', 'service_area']
[17:45:04] [jev_proxy] INFO: <-- 200 OK from JEV in 184.2ms | model=jev-1.13.0 | tokens(in=320, out=45)
```

To see complete HTTP wire traces (request headers, connection pools, raw bytes):
```bash
HTTPX_LOG_LEVEL=trace uv run jev-mcp
```

---

## Running Tests

The test suite covers client routing, question shortcuts, error handling (401, 422), rate limit backoff retries, and stdio JSON-RPC handshakes:

```bash
uv run pytest
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.