askjev 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Zaccaria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# askjev
+
+Unofficial [MCP](https://modelcontextprotocol.io) server for [Jev](https://docs.typesafe.ai),
+Typesafe AI's System One model. Not affiliated with Typesafe AI.
+
+Give your agent a fast second opinion. It asks a plain question about material it already
+has, Jev works out whether that is a yes/no, a scale, or a choice, and answers with
+calibrated probabilities. No generative model in the loop, one round trip, a fraction of the
+cost and latency of a sub-agent.
+
+## Status
+
+Not published yet. The pipeline works end to end against the live API and the router
+scores 100% on the first evaluation dataset. See [docs/EVAL.md](docs/EVAL.md).
+
+## Install
+
+Requires Node 22+ and a Typesafe API key in `TYPESAFE_API_KEY`.
+
+Claude Code:
+
+```sh
+claude mcp add askjev -e TYPESAFE_API_KEY=your-key -- npx -y askjev
+```
+
+Claude Desktop, Cursor, and other clients that take a JSON config:
+
+```json
+{
+  "mcpServers": {
+    "askjev": {
+      "command": "npx",
+      "args": ["-y", "askjev"],
+      "env": { "TYPESAFE_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+On Windows some hosts cannot launch `npx` directly. Use `"command": "cmd"` with
+`"args": ["/c", "npx", "-y", "askjev"]`.
+
+## The tool
+
+`ask` takes the material and a list of questions. Options are only needed when the question
+has named alternatives.
+
+```json
+{
+  "state": "Customer writes: charged twice for one order, wants it fixed today.",
+  "questions": [
+    { "question": "Does the customer ask for a refund?" },
+    { "question": "How frustrated is the customer?" },
+    { "question": "Which team should handle this?", "options": ["billing", "platform", "mobile"] }
+  ]
+}
+```
+
+Each answer comes back with probabilities, Jev's confidence, and how the question was
+routed. Read the confidence before acting on the answer.
+
+Full contract, pipeline diagrams, and the reasoning behind the design:
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). How the router is evaluated:
+[docs/EVAL.md](docs/EVAL.md).
+
+## Development
+
+```sh
+npm ci
+npm run lint
+npm run typecheck
+npm test
+```
+
+## License
+
+MIT

package/dist/ask.js

@@ -0,0 +1,137 @@
+import { choice, noul, score, } from "@typesafe-ai/sdk";
+import { buildRouting, buildRubricPick, key, readRouting, readRubricPick, } from "./router.js";
+import { RUBRICS } from "./rubrics.js";
+/**
+ * The pipeline: route each question, pick built-in rubrics where needed, answer everything
+ * in one Jev call, and shape the result. See docs/ARCHITECTURE.md, "Pipeline".
+ */
+export async function ask(jev, input) {
+    const { questions } = input;
+    const usage = { input_tokens: 0, output_tokens: 0 };
+    let model = "";
+    // Call 1: route.
+    const routingResult = await jev.systemOne(buildRouting(questions));
+    addUsage(usage, routingResult.usage);
+    model = routingResult.model;
+    const routed = questions.map((_, i) => {
+        const a = routingResult.answers[key(i)];
+        if (a?.type !== "choice")
+            throw new Error(`askjev: routing answer for ${key(i)} is missing or malformed`);
+        return readRouting(a);
+    });
+    // Call 2: pick a rubric for every scale question that came without options.
+    const needRubric = questions.flatMap((q, i) => !q.options && routed[i]?.kind === "score" ? [i] : []);
+    const picked = new Map();
+    if (needRubric.length > 0) {
+        const pickResult = await jev.systemOne(buildRubricPick(questions, needRubric));
+        addUsage(usage, pickResult.usage);
+        for (const i of needRubric) {
+            const a = pickResult.answers[key(i)];
+            if (a?.type !== "choice")
+                throw new Error(`askjev: rubric answer for ${key(i)} is missing or malformed`);
+            picked.set(i, readRubricPick(a));
+        }
+    }
+    // Build the typed questions, or an error entry for questions that cannot be asked.
+    const typed = {};
+    const answers = questions.map((q, i) => {
+        const r = routed[i];
+        if (!r)
+            return null;
+        const routing = { kind: r.kind, confidence: r.confidence };
+        if (r.kind === "noul") {
+            typed[key(i)] = noul(q.question);
+            return null;
+        }
+        if (r.kind === "choice") {
+            if (!q.options) {
+                return {
+                    kind: "error",
+                    message: `"${q.question}" asks to pick between alternatives, but no options were given. Pass options with the alternatives.`,
+                    routing,
+                };
+            }
+            typed[key(i)] = choice(q.question, Object.fromEntries(q.options.map((o) => [o, null])));
+            return null;
+        }
+        // score
+        if (q.options) {
+            typed[key(i)] = score(q.question, q.options);
+            return null;
+        }
+        const rubric = picked.get(i);
+        if (!rubric)
+            throw new Error(`askjev: no rubric was picked for ${key(i)}`);
+        typed[key(i)] = score(q.question, RUBRICS[rubric.name]);
+        return null;
+    });
+    // Call 3: answer.
+    if (Object.keys(typed).length > 0) {
+        const result = await jev.systemOne({ state: input.state, questions: typed });
+        addUsage(usage, result.usage);
+        model = result.model;
+        questions.forEach((q, i) => {
+            if (answers[i])
+                return;
+            const r = routed[i];
+            const a = result.answers[key(i)];
+            if (!r || !a)
+                throw new Error(`askjev: answer for ${key(i)} is missing`);
+            answers[i] = shape(a, r, q.options ? undefined : picked.get(i));
+        });
+    }
+    return {
+        model,
+        usage,
+        answers: answers.map((a, i) => {
+            if (!a)
+                throw new Error(`askjev: no answer was produced for ${key(i)}`);
+            return a;
+        }),
+    };
+}
+function shape(a, r, rubric) {
+    const routing = rubric
+        ? {
+            kind: r.kind,
+            confidence: r.confidence,
+            rubric: { name: rubric.name, confidence: rubric.confidence },
+        }
+        : { kind: r.kind, confidence: r.confidence };
+    switch (a.type) {
+        case "noul":
+            return {
+                kind: "noul",
+                answer: a.noul,
+                probabilities: { yes: a.noul, no: 1 - a.noul },
+                routing,
+            };
+        case "choice":
+            return {
+                kind: "choice",
+                answer: a.choice,
+                probabilities: { ...a.probabilities },
+                confidence: a.confidence,
+                routing,
+            };
+        case "score": {
+            const legend = Object.fromEntries(Object.entries(a.legend).map(([k, v]) => [k, String(v)]));
+            const base = {
+                kind: "score",
+                answer: a.score,
+                legend,
+                probabilities: { ...a.probabilities },
+                confidence: a.confidence,
+                routing,
+            };
+            return rubric ? { ...base, rubric: rubric.name, note: rubricNote(rubric.name) } : base;
+        }
+    }
+}
+function rubricNote(name) {
+    return `No options were given, so the built-in '${name}' rubric was used. Pass options for a rubric tailored to your question.`;
+}
+function addUsage(total, u) {
+    total.input_tokens += u.input_tokens;
+    total.output_tokens += u.output_tokens;
+}

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createJev } from "./jev.js";
+import { createServer } from "./server.js";
+const { version } = createRequire(import.meta.url)("../package.json");
+async function main() {
+    const jev = createJev();
+    const server = createServer(jev, version);
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    // stdout is the MCP protocol channel; diagnostics go to stderr.
+    console.error(`askjev: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});

package/dist/jev.js

@@ -0,0 +1,7 @@
+import { TypeSafeClient, } from "@typesafe-ai/sdk";
+export function createJev(config) {
+    const client = new TypeSafeClient(config);
+    return {
+        systemOne: (request) => client.systemOne(request),
+    };
+}

package/dist/router.js

@@ -0,0 +1,57 @@
+import { choice } from "@typesafe-ai/sdk";
+import { RUBRICS } from "./rubrics.js";
+/** Name used for question `i` in every Jev request, so answers map back by position. */
+export function key(index) {
+    return `q${index}`;
+}
+// ---------- step 1: what kind of question is this? ----------
+const WITH_OPTIONS = {
+    choice: "The options are distinct categories or alternatives with no inherent order between them. The answer is one of the options.",
+    score: "The options are ordered levels of a single quantity, listed from lowest to highest, such as degrees, ratings, grades, or urgency levels. The answer is a position on that scale.",
+};
+const WITHOUT_OPTIONS = {
+    noul: "A yes/no question. It can be answered with yes or no, true or false, or the probability that something holds.",
+    score: "A question about how much, how well, how likely, how often, or how strongly something applies. The answer is a degree on a scale.",
+    choice: "A question that asks to pick one of several named alternatives, such as which, who, or what kind, but the alternatives are not listed.",
+};
+/** Build the routing request: one choice question per input question, over the questions themselves. */
+export function buildRouting(questions) {
+    const state = {};
+    const routing = {};
+    questions.forEach((q, i) => {
+        const k = key(i);
+        state[k] = q.options ? { question: q.question, options: q.options } : { question: q.question };
+        routing[k] = choice(`What kind of question is \`${k}\`? Judge by what the question asks for${q.options ? " and by the nature of its options" : ""}.`, q.options ? WITH_OPTIONS : WITHOUT_OPTIONS);
+    });
+    return { state, questions: routing };
+}
+export function readRouting(answer) {
+    return { kind: answer.choice, confidence: answer.confidence };
+}
+// ---------- step 2: which built-in rubric fits a scale question without options? ----------
+const RUBRIC_CRITERIA = {
+    intensity: `How much, how strongly, or to what extent something applies. Levels: ${RUBRICS.intensity.join(", ")}.`,
+    quality: `How good or well done something is. Levels: ${RUBRICS.quality.join(", ")}.`,
+    severity: `How serious, harmful, or damaging something is. Levels: ${RUBRICS.severity.join(", ")}.`,
+    likelihood: `How probable something is. Levels: ${RUBRICS.likelihood.join(", ")}.`,
+    sentiment: `How positive or negative the tone or attitude is. Levels: ${RUBRICS.sentiment.join(", ")}.`,
+    frequency: `How often something happens. Levels: ${RUBRICS.frequency.join(", ")}.`,
+    agreement: `How much someone agrees with a statement. Levels: ${RUBRICS.agreement.join(", ")}.`,
+};
+/** Build the rubric-selection request for the given question indexes. */
+export function buildRubricPick(questions, indexes) {
+    const state = {};
+    const picks = {};
+    for (const i of indexes) {
+        const k = key(i);
+        const q = questions[i];
+        if (!q)
+            continue;
+        state[k] = q.question;
+        picks[k] = choice(`Which rubric best fits the scale that \`${k}\` asks about? Pick by the quantity being measured, not by the topic.`, RUBRIC_CRITERIA);
+    }
+    return { state, questions: picks };
+}
+export function readRubricPick(answer) {
+    return { name: answer.choice, confidence: answer.confidence };
+}

package/dist/rubrics.js

@@ -0,0 +1,14 @@
+/**
+ * Built-in rubrics for scale questions that arrive without options.
+ * All have five levels, lowest to highest, so Jev can discriminate without the levels blurring.
+ */
+export const RUBRICS = {
+    intensity: ["not at all", "slightly", "moderately", "very", "extremely"],
+    quality: ["poor", "below average", "acceptable", "good", "excellent"],
+    severity: ["trivial", "minor", "moderate", "major", "critical"],
+    likelihood: ["very unlikely", "unlikely", "uncertain", "likely", "very likely"],
+    sentiment: ["very negative", "negative", "neutral", "positive", "very positive"],
+    frequency: ["never", "rarely", "sometimes", "often", "always"],
+    agreement: ["strongly disagree", "disagree", "neutral", "agree", "strongly agree"],
+};
+export const RUBRIC_NAMES = Object.keys(RUBRICS);

package/dist/schema.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+// ---------- input ----------
+const jsonValue = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValue),
+    z.record(z.string(), jsonValue),
+]));
+export const stateSchema = z
+    .union([z.string(), z.array(jsonValue), z.record(z.string(), jsonValue)])
+    .describe("The material to judge: text, a JSON object, or a JSON array.");
+export const questionInputSchema = z.object({
+    question: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("A free-text question about the state. Jev decides whether it is yes/no, a scale, or a choice."),
+    options: z
+        .array(z.string().trim().min(1))
+        .min(2)
+        .optional()
+        .describe("Named alternatives, when the question has them. Order matters if they form a scale. Omit for yes/no questions or for 'how X' questions that can use a built-in rubric."),
+});
+export const askInputShape = {
+    state: stateSchema,
+    questions: z
+        .array(questionInputSchema)
+        .min(1)
+        .describe("Questions about the same state, answered in one round trip."),
+};
+export const askInputSchema = z.object(askInputShape);
+// ---------- output ----------
+export const kindSchema = z.enum(["noul", "score", "choice"]);
+const routingSchema = z.object({
+    kind: kindSchema.describe("The question type Jev routed this question to."),
+    confidence: z.number().describe("Jev's confidence in that routing."),
+    rubric: z
+        .object({ name: z.string(), confidence: z.number() })
+        .optional()
+        .describe("Present when a built-in rubric was picked for a scale question without options."),
+});
+const noulAnswerSchema = z.object({
+    kind: z.literal("noul"),
+    answer: z.number().describe("Probability that the answer is yes, from 0 to 1."),
+    probabilities: z.object({ yes: z.number(), no: z.number() }),
+    routing: routingSchema,
+});
+const scoreAnswerSchema = z.object({
+    kind: z.literal("score"),
+    answer: z.number().describe("Expected level on the rubric. May fall between integer levels."),
+    legend: z.record(z.string(), z.string()).describe("Level index to level description."),
+    probabilities: z.record(z.string(), z.number()).describe("Probability per level index."),
+    confidence: z.number(),
+    rubric: z.string().optional().describe("Name of the built-in rubric, when one was used."),
+    note: z
+        .string()
+        .optional()
+        .describe("Advice when a built-in rubric was used instead of caller options."),
+    routing: routingSchema,
+});
+const choiceAnswerSchema = z.object({
+    kind: z.literal("choice"),
+    answer: z.string().describe("The selected option."),
+    probabilities: z.record(z.string(), z.number()).describe("Probability per option."),
+    confidence: z.number(),
+    routing: routingSchema,
+});
+const errorAnswerSchema = z.object({
+    kind: z.literal("error"),
+    message: z.string().describe("Why this question could not be answered, and what to change."),
+    routing: routingSchema
+        .optional()
+        .describe("Present when the question was routed before the error was detected."),
+});
+export const answerSchema = z.discriminatedUnion("kind", [
+    noulAnswerSchema,
+    scoreAnswerSchema,
+    choiceAnswerSchema,
+    errorAnswerSchema,
+]);
+export const askOutputShape = {
+    model: z.string().describe("The Jev model that answered."),
+    usage: z
+        .object({ input_tokens: z.number(), output_tokens: z.number() })
+        .describe("Token usage summed over every Jev call made."),
+    answers: z
+        .array(answerSchema)
+        .describe('One entry per question, in input order. A question that could not be answered has kind "error"; the others are still answered.'),
+};
+export const askOutputSchema = z.object(askOutputShape);

package/dist/server.js

@@ -0,0 +1,54 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { APIError, AuthenticationError, TypeSafeError } from "@typesafe-ai/sdk";
+import { ask } from "./ask.js";
+import { RUBRICS } from "./rubrics.js";
+import { askInputShape, askOutputShape } from "./schema.js";
+const rubricLines = Object.entries(RUBRICS)
+    .map(([name, levels]) => `  - ${name}: ${levels.join(" < ")}`)
+    .join("\n");
+const description = `Ask Jev, a fast non-generative judgment model, one or more questions about some material you already have. Use it for a quick second opinion, a classification, a rating, or a yes/no check instead of reasoning it out yourself or spawning a sub-agent.
+
+Write each question in plain language. Jev decides whether it is a yes/no question, a scale, or a choice:
+- Yes/no: "Does this ticket ask for a refund?" You get the probability of yes.
+- Choice: pass "options" with the named alternatives. "Which team owns this?" with options ["billing", "platform"].
+- Scale: pass "options" as ordered levels, lowest first. "How urgent is this?" with options ["can wait", "this week", "today"]. Without options, a built-in rubric is picked for you:
+${rubricLines}
+
+Every answer carries probabilities and Jev's confidence, plus "routing" showing how the question was interpreted. Read the confidence: a low value means the material does not settle the question, so add context or decide another way.
+
+Requires TYPESAFE_API_KEY in the server's environment.`;
+export function createServer(jev, version) {
+    const server = new McpServer({ name: "askjev", version });
+    server.registerTool("ask", {
+        title: "Ask Jev",
+        description,
+        inputSchema: askInputShape,
+        outputSchema: askOutputShape,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (input) => {
+        try {
+            const output = await ask(jev, input);
+            return {
+                content: [{ type: "text", text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: describeError(error) }] };
+        }
+    });
+    return server;
+}
+export function describeError(error) {
+    if (error instanceof AuthenticationError) {
+        return "Jev rejected the API key. Set TYPESAFE_API_KEY in the environment of the askjev process.";
+    }
+    if (error instanceof APIError) {
+        const id = error.requestId ? ` (request ${error.requestId})` : "";
+        return `Jev returned HTTP ${error.status}${id}: ${error.message}`;
+    }
+    if (error instanceof TypeSafeError || error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "askjev",
+  "version": "0.1.0",
+  "description": "Unofficial MCP server for Jev, Typesafe AI's System One model. Ask free-text questions; Jev routes them to choice, score, or yes/no and answers with calibrated probabilities.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "jev",
+    "typesafe",
+    "typesafe-ai",
+    "system-one",
+    "agents"
+  ],
+  "license": "MIT",
+  "author": "Pedro Zaccaria",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pZacca/askjev.git"
+  },
+  "homepage": "https://github.com/pZacca/askjev#readme",
+  "bugs": {
+    "url": "https://github.com/pZacca/askjev/issues"
+  },
+  "funding": "https://github.com/sponsors/pZacca",
+  "type": "module",
+  "bin": {
+    "askjev": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "eval": "tsx eval/run.ts",
+    "smoke": "tsx test/smoke/run.ts",
+    "prepack": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@typesafe-ai/sdk": "^0.6.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.14",
+    "@types/node": "^22.20.3",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
+  }
+}