# 🧠 `typesafe-mcp`

> MCP server for TypeSafe's Jev model

`typesafe-mcp` exposes a single `evaluate` tool that sends evidence and
questions to [TypeSafe](https://typesafe.ai) and returns structured answers and
probabilities.

It is written in JavaScript and uses the
[MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) and
[Zod](https://zod.dev). No build step is required.

## Installation

Requires Node.js 22 or later. From the project directory:

```bash
npm ci
```

Set `TYPESAFE_API_KEY` in the environment used to start the server. Keys are
available from the [TypeSafe console](https://console.typesafe.ai/settings/keys).

## Configuration

For Codex, add the following to your MCP configuration, replacing the path with
this checkout's absolute path:

```toml
[mcp_servers.typesafe]
command = "node"
args = ["/absolute/path/typesafe-mcp/server.js"]
env_vars = ["TYPESAFE_API_KEY"]
```

Other MCP clients can launch `node /absolute/path/typesafe-mcp/server.js` using
the same environment variable. The server communicates via stdin/stdout.

## Usage

Call `evaluate` with the evidence in `state` and a map of named `questions`:

```json
{
  "state": "My order arrived damaged. Please issue a refund.",
  "questions": {
    "refund_requested": {
      "type": "noul",
      "instructions": "Does the customer request a refund?"
    }
  }
}
```

| Type | Criteria | Answer |
| --- | --- | --- |
| `noul` | Optional descriptions of `true` and `false` | Probability that the condition holds |
| `choice` | Map of option names to descriptions or `null` | Selected option, probabilities, and confidence |
| `score` | Ordered array of level descriptions | Weighted score, probabilities, and confidence |

Batch independent questions for the same state in one call. `model` defaults to
`jev-latest`. State, instructions, and rubric descriptions can include
structured JSON. Encode large integer identifiers as strings to preserve their
digits.

See the [TypeSafe API reference](https://docs.typesafe.ai/api) for details on
question and answer formats. The provided evidence is sent to TypeSafe, and
standard API charges apply.

## Request Results

The API response includes the answers and token usage. Questions are validated
before sending; missing or mismatched answer types trigger MCP tool errors.
Answer values and probability distributions pass through without further
validation or automatic accept/reject decisions.

Requests have a 60-second deadline and honour MCP cancellation. HTTP errors
report the status without echoing the upstream body. Failed requests are not
retried.

## Development

```bash
npm test
```

Tests cover the MCP interface and request handling using mock responses. They
require no API key or paid calls.

To test the real API, add your local testing key to the gitignored `.env` file
as `TYPESAFE_API_KEY`, then run:

```bash
npm run test:live
```

The live test sends a single batch of synthetic evidence through the MCP server,
covering all three question types. It verifies response formats, ranges, and
allowed choices rather than exact probabilities. It incurs standard API charges
and is excluded from `npm test`.

## Licence

Licensed under the [MIT licence](LICENSE).