🧠 typesafe-mcp

MCP server for TypeSafe's Jev model

typesafe-mcp exposes a single evaluate tool that sends evidence and questions to TypeSafe and returns structured answers and probabilities.

It is written in JavaScript and uses the MCP SDK and Zod. No build step is required.

Installation

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

npm ci

Set TYPESAFE_API_KEY in the environment used to start the server. Keys are available from the TypeSafe console.

Configuration

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

[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:

{
  "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 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

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:

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.