# jev-paper-review-mcp

> 🇨🇳 [中文文档](README.zh-CN.md)

> Let your agent score paper excerpts with **confidence-calibrated structured decisions** instead of parsing free-form LLM text.
> Powered by [TypeSafe Jev](https://typesafe.ai) (System One decision model).

A **single-purpose MCP tool** that turns a paper's abstract / method / results excerpt into a calibrated review score
(three ordinal dimensions — `soundness` / `novelty` / `clarity` — plus an overall `accept` / `revise` / `reject` verdict).
Your agent gets a **structured, verifiable decision**, not a prose essay.

```
npm install && npm run build
node dist/index.js doctor      # print dependency/mode diagnostics
```

Connect `node dist/index.js` in your MCP client and use the `review_paper` tool.

---

## Why not just wrap another LLM

Jev is a **decision model**, not a chat model. You give it `{ state, questions }` and it returns a
**probability distribution + confidence** — not a JSON blob you have to guess at. That makes it a natural fit for "peer review", a
**judgment task with a standard rubric**:

| Dimension | Scale (low → high) |
|---|---|
| `soundness` | weak · adequate · strong · exceptional |
| `novelty` | incremental · moderate · original · breakthrough |
| `clarity` | confusing · acceptable · clear · excellent |
| `verdict` | accept · minor_revision · major_revision · reject |

Each dimension returns a `score` (ordinal index), `label`, `probabilities` (distribution), and `confidence` (calibrated confidence).

---

## Tool: `review_paper`

**Input**
| Param | Type | Description |
|---|---|---|
| `text` | string | The paper excerpt to review (abstract / method / results — any of them) |
| `venue` | string? | Optional, e.g. `ICLR` / `NeurIPS`; affects expectations only, never the logic |

**Output fields**
| Field | Meaning |
|---|---|
| `soundness / novelty / clarity` | Three-dimension scores, each with `score` / `label` / `probabilities` / `confidence` |
| `verdict` | `{ choice, probabilities, confidence }` — overall conclusion |
| `confidence` | **Minimum** of each dimension's `confidence` (see gate logic below) |
| `recommendation` | `accept` / `minor_revision` / `major_revision` / `reject` / `desk_reject` |
| `reasoning_flags` | Human-readable hints (e.g. `weak_or_flawed_methodology`, `verify_novelty_before_accept`) |
| `mocked` | Whether running in mock mode |

**Decision gate logic** (agents must follow)
- `desk_reject`: `verdict=reject` **and** `soundness ≤ weak` → high-confidence direct reject
- `reject`: `verdict=reject`
- `major_revision`: `verdict=major_revision` (append `soundness_concerns` if soundness is low)
- `minor_revision` / `accept`: per verdict

> ⚠️ **Safety note**: a high probability on one dimension **does not mean it can decide for a human**. Before any action,
> check `confidence` first — this service only emits strong conclusions when `confidence` is sufficient. Output is **advisory only**.

---

## Example

```json
{
  "soundness": { "score": 3, "label": "exceptional", "confidence": 0.82, "probabilities": {"0":0.0,"1":0.0,"2":0.15,"3":0.85} },
  "novelty":   { "score": 2, "label": "original",     "confidence": 0.74, "probabilities": {"0":0.1,"1":0.15,"2":0.75,"3":0.0} },
  "clarity":   { "score": 2, "label": "clear",        "confidence": 0.79, "probabilities": {"0":0.05,"1":0.2,"2":0.75,"3":0.0} },
  "verdict":   { "choice": "accept", "confidence": 0.8, "probabilities": {"0":0.8,"1":0.05,"2":0.05,"3":0.1} },
  "confidence": 0.74,
  "recommendation": "accept",
  "reasoning_flags": []
}
```

---

## Extremely low cost

A single decision is just one Jev call; state is truncated at 60k characters, so it's **tens of thousands of tokens per call**,
with no LLM calls at all — far cheaper per unit than a chat model. There's no token-usage chart because it's already that cheap —
think of it as "one cheap gate in your review pipeline".

---

## Zero-key / local-first

- No `TYPESAFE_API_KEY` set → automatically enters **mock mode** (deterministic offline stub, zero-config for CI / demos)
- `JEV_MCP_MOCK=1` → force mock
- Set `TYPESAFE_API_KEY` → call the real Jev API (default `jev-latest` @ `https://api.typesafe.ai/v1/systemone`)

**Environment variables**
| Variable | Default | Description |
|---|---|---|
| `TYPESAFE_API_KEY` | — | Required for real calls; blank falls back to mock |
| `JEV_MODEL` | `jev-latest` | Model name |
| `JEV_BASE_URL` | Official endpoint | Override for self-hosted / proxy |
| `JEV_MCP_MOCK` | `0` | `1` forces mock |
| `JEV_MCP_TIMEOUT_MS` | `30000` | Per-request timeout |

---

## Tests

```bash
npm test     # smoke + MCP protocol handshake (mock mode, no key needed)
```

---

## License

MIT