askjev 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,9 @@
 # askjev
 
+[![CI](https://github.com/pZacca/askjev/actions/workflows/ci.yml/badge.svg)](https://github.com/pZacca/askjev/actions/workflows/ci.yml) [![Router eval](https://github.com/pZacca/askjev/actions/workflows/eval.yml/badge.svg)](https://github.com/pZacca/askjev/actions/workflows/eval.yml) [![npm](https://img.shields.io/npm/v/askjev)](https://www.npmjs.com/package/askjev) [![smithery badge](https://smithery.ai/badge/pzacca/askjev)](https://smithery.ai/servers/pzacca/askjev) [![License](https://img.shields.io/npm/l/askjev)](LICENSE)
+
+[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-blueviolet)](#claude-code) [![Claude Desktop](https://img.shields.io/badge/Claude_Desktop-supported-blueviolet)](#claude-desktop) [![Cursor](https://img.shields.io/badge/Cursor-supported-blueviolet)](#cursor) [![Codex](https://img.shields.io/badge/Codex-supported-blueviolet)](#codex)
+
 Unofficial [MCP](https://modelcontextprotocol.io) server for [Jev](https://docs.typesafe.ai),
 Typesafe AI's System One model. Not affiliated with Typesafe AI.
 
@@ -8,22 +12,52 @@ has, Jev works out whether that is a yes/no, a scale, or a choice, and answers w
 calibrated probabilities. No generative model in the loop, one round trip, a fraction of the
 cost and latency of a sub-agent.
 
-## Status
+## Demo
+
+An agent planning a workflow, asking Jev one question at a time. Every number is real.
 
-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).
+![An agent asks askjev five questions in a terminal and gets probabilities back](assets/askjev-demo.gif)
 
 ## Install
 
-Requires Node 22+ and a Typesafe API key in `TYPESAFE_API_KEY`.
+You need a Typesafe API key. The server runs in one of two places; every client below
+supports at least one.
+
+- **Hosted.** `https://jev.zacca.dev/mcp` runs this repository on Cloudflare Workers. It keeps
+  nothing: every call builds a Typesafe client from the key you send and forwards the
+  question. Send the key in the `x-api-key` header, or as a bearer token if your client
+  only has that field. The same server is listed on Smithery as
+  [pzacca/askjev](https://smithery.ai/servers/pzacca/askjev).
+- **Local.** `npx -y askjev` runs it on your machine over stdio. Requires Node 22+ and the
+  key in `TYPESAFE_API_KEY`.
+
+### Supported clients
 
-Claude Code:
+| Client | Local (stdio) | Hosted (HTTP) |
+|---|---|---|
+| [Claude Code](#claude-code) | yes | yes |
+| [Claude Desktop](#claude-desktop) | yes | no, custom connectors cannot send an API key header |
+| [Cursor](#cursor) | yes | yes |
+| [Codex](#codex) | yes | yes, as a bearer token |
+
+Claude Code and Codex were exercised end to end on both transports. Cursor follows its
+documented configuration format.
+
+#### Claude Code
 
 ```sh
+# hosted
+claude mcp add --transport http askjev https://jev.zacca.dev/mcp --header "x-api-key: your-key"
+
+# local
 claude mcp add askjev -e TYPESAFE_API_KEY=your-key -- npx -y askjev
 ```
 
-Claude Desktop, Cursor, and other clients that take a JSON config:
+#### Claude Desktop
+
+Open Settings, Developer, Edit Config. The file is
+`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and
+`%APPDATA%\Claude\claude_desktop_config.json` on Windows.
 
 ```json
 {
@@ -37,31 +71,228 @@ Claude Desktop, Cursor, and other clients that take a JSON config:
 }
 ```
 
-On Windows some hosts cannot launch `npx` directly. Use `"command": "cmd"` with
-`"args": ["/c", "npx", "-y", "askjev"]`.
+Restart Claude Desktop after saving. On Windows some hosts cannot launch `npx` directly;
+use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "askjev"]`.
 
-## The tool
+#### Cursor
 
-`ask` takes the material and a list of questions. Options are only needed when the question
-has named alternatives.
+Add to `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one project.
 
 ```json
 {
-  "state": "Customer writes: charged twice for one order, wants it fixed today.",
+  "mcpServers": {
+    "askjev": {
+      "url": "https://jev.zacca.dev/mcp",
+      "headers": { "x-api-key": "your-key" }
+    }
+  }
+}
+```
+
+For a local server use the same `command`, `args` and `env` block as Claude Desktop.
+
+#### Codex
+
+```sh
+# hosted: Codex reads the key from an environment variable and sends it as a bearer token
+export TYPESAFE_API_KEY=your-key
+codex mcp add askjev --url https://jev.zacca.dev/mcp --bearer-token-env-var TYPESAFE_API_KEY
+
+# local
+codex mcp add askjev --env TYPESAFE_API_KEY=your-key -- npx -y askjev
+```
+
+## The tool
+
+One tool, `ask`. It takes the material and a list of free-text questions. Options are only
+needed when the question has named alternatives.
+
+### Input
+
+```jsonc
+{
+  "state": "...",                       // string | object | array: the material to judge
   "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"] }
+    { "question": "Is this a bug report?" },
+    { "question": "How severe is it?" },
+    { "question": "Which team owns it?", "options": ["billing", "platform", "mobile"] },
+    { "question": "How urgent is it?",    "options": ["can wait", "this week", "today"] }
+  ]
+}
+```
+
+- `question` is free text. Jev decides whether it is a yes/no question, a scale, or a
+  choice between the given options.
+- `options` is optional. Pass it when the question has named alternatives. Order matters
+  when the options form a scale.
+- There is no way to force the question type. The whole point is that the agent does not
+  have to think about it.
+
+### Output
+
+One entry per question, in input order.
+
+```jsonc
+{
+  "answers": [
+    {
+      "kind": "noul",
+      "answer": 0.93,                               // probability of "yes"
+      "probabilities": { "yes": 0.93, "no": 0.07 },
+      "routing": { "kind": "noul", "confidence": 0.98 }
+    },
+    {
+      "kind": "score",
+      "answer": 3.4,                                // expected level, may be fractional
+      "legend": { "0": "trivial", "1": "minor", "2": "moderate", "3": "major", "4": "critical" },
+      "probabilities": { "0": 0.01, "1": 0.04, "2": 0.15, "3": 0.5, "4": 0.3 },
+      "confidence": 0.71,
+      "rubric": "severity",
+      "note": "No options were given, so the built-in 'severity' rubric was used. Pass options for a rubric tailored to your question.",
+      "routing": { "kind": "score", "confidence": 0.9, "rubric": { "name": "severity", "confidence": 0.84 } }
+    },
+    {
+      "kind": "choice",
+      "answer": "platform",
+      "probabilities": { "billing": 0.05, "platform": 0.88, "mobile": 0.07 },
+      "confidence": 0.88,
+      "routing": { "kind": "choice", "confidence": 0.97 }
+    },
+    {
+      "kind": "score",
+      "answer": 1.8,
+      "legend": { "0": "can wait", "1": "this week", "2": "today" },
+      "probabilities": { "0": 0.1, "1": 0.2, "2": 0.7 },
+      "confidence": 0.7,
+      "routing": { "kind": "score", "confidence": 0.79 }
+    }
   ]
 }
 ```
 
-Each answer comes back with probabilities, Jev's confidence, and how the question was
-routed. Read the confidence before acting on the answer.
+A question that cannot be answered does not fail the batch. Its entry has `kind: "error"`
+and a message saying what to change, and every other question is still answered:
+
+```jsonc
+{
+  "kind": "error",
+  "message": "\"Which team owns it?\" asks to pick between alternatives, but no options were given. Pass options with the alternatives.",
+  "routing": { "kind": "choice", "confidence": 0.95 }
+}
+```
+
+Everything is raw. There is no threshold and no verdict. `confidence` comes straight from
+Jev; yes/no answers have no separate confidence because the probability is the signal.
+`routing` exposes how sure Jev was about the question type, and about the rubric when one
+was picked, so a misroute is visible rather than silent.
+
+What else comes back is the operator's choice, not the agent's. `ASKJEV_INCLUDE` is a
+comma-separated list of the optional parts: `routing` (the default), `usage` (tokens summed
+over every Jev call), and `model`. Set it to `usage,routing` to add token counts, or to an
+empty string to get nothing but the answers. The tool description tells the agent what the
+server was configured to emit.
+
+## How it works
+
+```mermaid
+flowchart TD
+    A[ask: state + questions] --> B[Call 1: route<br/>one Jev call, one choice question per input question]
+    B --> C{per question}
+    C -->|options given| D{choice or score?}
+    C -->|no options| E{noul, score, or<br/>choice-without-options?}
+    D -->|choice| F[choice with options as labels]
+    D -->|score| G[score with options as ordered rubric]
+    E -->|noul| H[noul]
+    E -->|score| I[Call 2: pick rubric<br/>one Jev call, one choice question per such input question]
+    E -->|choice| X[error: this question needs options]
+    I --> J[score with built-in rubric]
+    F --> K[Call 3: answer<br/>one Jev call with every typed question]
+    G --> K
+    H --> K
+    J --> K
+    K --> L[shape answers + routing metadata + summed usage]
+```
+
+Two Jev calls in the common case, three when at least one question is a scale without
+options. The number of input questions does not change the number of calls: each step
+batches every question that needs it into a single `systemone` request.
+
+### Routing table
+
+| `options` | Router decides between | Becomes |
+|---|---|---|
+| 2+ items | choice, score | `choice` with options as labels, or `score` with options as ordered rubric |
+| absent | noul, score, choice | `noul`; `score` after picking a built-in rubric; or an error asking for options |
+| 1 item | rejected by schema validation | never reaches the router |
+
+The router's `state` is the question text itself (an object keyed by question when
+batching), and its instructions ask which kind of question that text is. The routing
+criteria are described in plain language so Jev discriminates on intent, not on keywords.
+
+### Built-in rubrics
+
+Used only for scale questions that arrive without options. A second Jev call picks the
+closest one. All have five levels so Jev has room to discriminate without the levels
+blurring together.
+
+| Name | Levels, lowest to highest |
+|---|---|
+| `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 |
+
+The list is fixed in code. Configurable rubrics are a possible later addition.
 
-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).
+## Errors
+
+| Situation | Behaviour |
+|---|---|
+| Input fails schema validation | Tool error with the Zod message. Jev is not called. |
+| Question routed to `choice` with no options | That entry becomes `kind: "error"` asking for `options`. The rest of the batch is answered normally. |
+| Jev returns 401 | Tool error: API key missing or invalid, with the env var name. |
+| Jev returns 422, 429 after retries, 5xx | Tool error with status, Jev's message, and the request id when present. |
+| Network or timeout after retries | Tool error with the SDK's message. |
+
+Errors that affect the whole call are returned as MCP tool results with `isError: true`,
+not as protocol errors, so the agent sees the message and can recover. Errors that affect
+one question are entries in `answers`, so one bad question never costs the agent the
+others.
+
+## Configuration
+
+Local, only what the Typesafe SDK already reads from the environment:
+
+| Variable | Meaning |
+|---|---|
+| `TYPESAFE_API_KEY` | Required. |
+| `TYPESAFE_DEFAULT_MODEL` | Optional, defaults to `jev-latest`. |
+| `TYPESAFE_BASE_URL` | Optional, for proxies and the smoke test stub. |
+| `TYPESAFE_LOG_LEVEL` | Optional. SDK logs go to stderr. |
+
+Plus one setting of the server's own:
+
+| Variable | Meaning |
+|---|---|
+| `ASKJEV_INCLUDE` | Optional parts of every result, comma-separated: `model`, `usage`, `routing`. Default `routing`. Empty string for answers only. An unknown name is a startup error. |
+
+stdout carries MCP protocol messages only; every diagnostic goes to stderr.
+
+Hosted, the key travels per request in the `x-api-key` header (or `Authorization:
+Bearer`). `TYPESAFE_BASE_URL`, `TYPESAFE_DEFAULT_MODEL` and `ASKJEV_INCLUDE` can be set as
+Worker vars and apply to every caller. The public instance at jev.zacca.dev runs the
+defaults.
+
+## Evaluation
+
+The router is the part that can be wrong in a way unit tests cannot catch. A versioned
+dataset of human-labelled questions runs against the live API weekly and on demand; the
+first run scored 42/42 on routing and 16/16 on rubric selection. See
+[docs/EVAL.md](docs/EVAL.md). Design decisions and rejected alternatives are in
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ## Development
 
@@ -72,6 +303,24 @@ npm run typecheck
 npm test
 ```
 
+The hosted variant is `src/worker.ts`, bundled and deployed by wrangler from
+`wrangler.jsonc`. `npm run dev` serves it on localhost. Every push to `main` that passes
+CI is deployed to jev.zacca.dev by the `deploy` job in `ci.yml`; `npm run deploy` does
+the same by hand (needs `wrangler login`).
+
+Releases are tag-driven. Bump the version in `package.json`, commit, then:
+
+```sh
+git tag v0.2.0 && git push origin main v0.2.0
+```
+
+`release.yml` checks that the tag matches `package.json`, runs the full test suite,
+publishes to npm with provenance, and creates the GitHub release with generated notes.
+
+The Smithery listing points at that domain and takes its configuration form from
+`smithery.schema.json`. After changing the schema, republish with
+`smithery mcp publish https://jev.zacca.dev/mcp -n pzacca/askjev --config-schema smithery.schema.json`.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { INCLUDE_ENV, parseInclude } from "./include.js";
 import { createJev } from "./jev.js";
 import { createServer } from "./server.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 async function main() {
+    const include = parseInclude(process.env[INCLUDE_ENV]);
     const jev = createJev();
-    const server = createServer(jev, version);
+    const server = createServer(jev, version, { include });
     await server.connect(new StdioServerTransport());
 }
 main().catch((error) => {

package/dist/http.js

@@ -0,0 +1,78 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { createJev } from "./jev.js";
+import { createServer } from "./server.js";
+/** Header that carries the caller's Typesafe API key. */
+export const API_KEY_HEADER = "x-api-key";
+/** How a remote caller supplies the key; shown in the tool description and in auth errors. */
+export const KEY_HINT = `Send your Typesafe API key in the ${API_KEY_HEADER} header, or as a bearer token in Authorization.`;
+/**
+ * The remote, multi-tenant entry point over Streamable HTTP, on web-standard Request and
+ * Response so it runs on Cloudflare Workers, Deno, Bun, or Node 22+.
+ *
+ * Stateless: every request gets a fresh server and transport, and the Typesafe client is
+ * built from the key that request carried. The key is never stored. Initialize and
+ * tools/list work without a key so registries can scan the server; only `ask` needs one.
+ */
+export function createHttpHandler(options) {
+    const path = options.path ?? "/mcp";
+    const jevFor = options.jevFor ??
+        ((apiKey) => createJev({
+            apiKey,
+            ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+            ...(options.defaultModel ? { defaultModel: options.defaultModel } : {}),
+        }));
+    return async (request) => {
+        const url = new URL(request.url);
+        if (url.pathname === "/" && request.method === "GET") {
+            return Response.json({
+                name: "askjev",
+                version: options.version,
+                mcp: path,
+                auth: KEY_HINT,
+                docs: "https://github.com/pZacca/askjev",
+            });
+        }
+        if (url.pathname !== path) {
+            return new Response("Not found", { status: 404 });
+        }
+        // Stateless: no sessions to resume (GET) or terminate (DELETE). A GET would otherwise open
+        // an SSE stream that nothing can ever write to, and hold it open with keep-alives.
+        if (request.method !== "POST") {
+            return new Response("Method not allowed", { status: 405, headers: { allow: "POST" } });
+        }
+        const apiKey = readApiKey(request.headers);
+        const jev = apiKey ? lazyJev(() => jevFor(apiKey)) : missingKeyJev;
+        const server = createServer(jev, options.version, {
+            keyHint: KEY_HINT,
+            ...(options.include ? { include: options.include } : {}),
+        });
+        // No sessionIdGenerator: stateless, one transport per request.
+        const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+        await server.connect(transport);
+        return transport.handleRequest(request);
+    };
+}
+/** The dedicated header wins; a bearer token is accepted for clients that only have that field. */
+export function readApiKey(headers) {
+    const direct = headers.get(API_KEY_HEADER)?.trim();
+    if (direct)
+        return direct;
+    const auth = headers.get("authorization")?.trim();
+    const match = auth?.match(/^bearer\s+(.+)$/i);
+    return match?.[1]?.trim() || undefined;
+}
+/** Builds the client on first use, so initialize and tools/list never construct one. */
+function lazyJev(build) {
+    let jev;
+    return {
+        systemOne: (request) => {
+            jev ??= build();
+            return jev.systemOne(request);
+        },
+    };
+}
+const missingKeyJev = {
+    systemOne: async () => {
+        throw new Error(`No Typesafe API key was sent. ${KEY_HINT}`);
+    },
+};

package/dist/include.js

@@ -0,0 +1,43 @@
+/** Optional parts of the result. The operator picks them once, in configuration. */
+export const INCLUDE_FIELDS = ["model", "usage", "routing"];
+/** What goes out when nothing is configured: the answers, plus how each was interpreted. */
+export const DEFAULT_INCLUDE = ["routing"];
+/** Environment variable that overrides the default, as a comma-separated list. */
+export const INCLUDE_ENV = "ASKJEV_INCLUDE";
+/**
+ * Parses `ASKJEV_INCLUDE`. Unset keeps the default; an empty string strips everything
+ * optional; unknown names are a startup error, not a silent no-op.
+ */
+export function parseInclude(raw) {
+    if (raw === undefined)
+        return [...DEFAULT_INCLUDE];
+    const fields = new Set();
+    for (const part of raw.split(",")) {
+        const name = part.trim().toLowerCase();
+        if (name === "")
+            continue;
+        if (!isIncludeField(name)) {
+            throw new Error(`${INCLUDE_ENV}: unknown field "${part.trim()}". Valid fields: ${INCLUDE_FIELDS.join(", ")}.`);
+        }
+        fields.add(name);
+    }
+    return INCLUDE_FIELDS.filter((f) => fields.has(f));
+}
+function isIncludeField(name) {
+    return INCLUDE_FIELDS.includes(name);
+}
+/** Drops every optional part that is not in `include`. The pipeline always produces them all. */
+export function trimOutput(output, include) {
+    const keep = new Set(include);
+    const { model, usage, answers } = output;
+    return {
+        ...(keep.has("model") && model !== undefined ? { model } : {}),
+        ...(keep.has("usage") && usage !== undefined ? { usage } : {}),
+        answers: keep.has("routing")
+            ? answers
+            : answers.map((a) => {
+                const { routing: _routing, ...rest } = a;
+                return rest;
+            }),
+    };
+}

package/dist/schema.js

@@ -33,6 +33,7 @@ export const askInputShape = {
 export const askInputSchema = z.object(askInputShape);
 // ---------- output ----------
 export const kindSchema = z.enum(["noul", "score", "choice"]);
+/** How Jev interpreted the question. Emitted when the server is configured to include routing. */
 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."),
@@ -45,7 +46,7 @@ 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,
+    routing: routingSchema.optional(),
 });
 const scoreAnswerSchema = z.object({
     kind: z.literal("score"),
@@ -58,21 +59,21 @@ const scoreAnswerSchema = z.object({
         .string()
         .optional()
         .describe("Advice when a built-in rubric was used instead of caller options."),
-    routing: routingSchema,
+    routing: routingSchema.optional(),
 });
 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,
+    routing: routingSchema.optional(),
 });
 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."),
+        .describe("Present when routing is configured and the question was routed before the error was detected."),
 });
 export const answerSchema = z.discriminatedUnion("kind", [
     noulAnswerSchema,
@@ -81,10 +82,11 @@ export const answerSchema = z.discriminatedUnion("kind", [
     errorAnswerSchema,
 ]);
 export const askOutputShape = {
-    model: z.string().describe("The Jev model that answered."),
+    model: z.string().optional().describe("The Jev model that answered. Present when configured."),
     usage: z
         .object({ input_tokens: z.number(), output_tokens: z.number() })
-        .describe("Token usage summed over every Jev call made."),
+        .optional()
+        .describe("Token usage summed over every Jev call made. Present when configured."),
     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.'),

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { APIError, AuthenticationError, TypeSafeError } from "@typesafe-ai/sdk";
 import { ask } from "./ask.js";
+import { DEFAULT_INCLUDE, trimOutput } from "./include.js";
 import { RUBRICS } from "./rubrics.js";
 import { askInputShape, askOutputShape } from "./schema.js";
 const rubricLines = Object.entries(RUBRICS)
@@ -14,34 +15,49 @@ Write each question in plain language. Jev decides whether it is a yes/no questi
 - 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) {
+`;
+/** The sentence about the result shape depends on what the operator chose to include. */
+function describeOutput(include) {
+    const keep = new Set(include);
+    const parts = ["Every answer carries probabilities and Jev's confidence"];
+    if (keep.has("routing")) {
+        parts.push('plus "routing" showing how the question was interpreted and how sure Jev was about that');
+    }
+    const extras = [keep.has("model") ? '"model"' : "", keep.has("usage") ? '"usage" (tokens)' : ""]
+        .filter(Boolean)
+        .join(" and ");
+    const extraLine = extras ? ` The result also carries ${extras}.` : "";
+    return `${parts.join(", ")}.${extraLine} Read the confidence: a low value means the material does not settle the question, so add context or decide another way.`;
+}
+/** How the caller supplies the Typesafe API key when nothing else is said: the stdio way. */
+export const ENV_KEY_HINT = "Set TYPESAFE_API_KEY in the environment of the askjev process.";
+export function createServer(jev, version, options = {}) {
+    const keyHint = options.keyHint ?? ENV_KEY_HINT;
+    const include = options.include ?? DEFAULT_INCLUDE;
     const server = new McpServer({ name: "askjev", version });
     server.registerTool("ask", {
         title: "Ask Jev",
-        description,
+        description: `${description}\n${describeOutput(include)}\n\nRequires a Typesafe API key. ${keyHint}`,
         inputSchema: askInputShape,
         outputSchema: askOutputShape,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (input) => {
         try {
-            const output = await ask(jev, input);
+            const output = trimOutput(await ask(jev, input), include);
             return {
                 content: [{ type: "text", text: JSON.stringify(output) }],
                 structuredContent: output,
             };
         }
         catch (error) {
-            return { isError: true, content: [{ type: "text", text: describeError(error) }] };
+            return { isError: true, content: [{ type: "text", text: describeError(error, keyHint) }] };
         }
     });
     return server;
 }
-export function describeError(error) {
+export function describeError(error, keyHint = ENV_KEY_HINT) {
     if (error instanceof AuthenticationError) {
-        return "Jev rejected the API key. Set TYPESAFE_API_KEY in the environment of the askjev process.";
+        return `Jev rejected the API key. ${keyHint}`;
     }
     if (error instanceof APIError) {
         const id = error.requestId ? ` (request ${error.requestId})` : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askjev",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -42,6 +42,8 @@
     "test:watch": "vitest",
     "eval": "tsx eval/run.ts",
     "smoke": "tsx test/smoke/run.ts",
+    "dev": "wrangler dev --define \"ASKJEV_VERSION:'$npm_package_version'\"",
+    "deploy": "wrangler deploy --define \"ASKJEV_VERSION:'$npm_package_version'\"",
     "prepack": "npm run clean && npm run build"
   },
   "dependencies": {
@@ -54,6 +56,10 @@
     "@types/node": "^22.20.3",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.1",
+    "wrangler": "^4.134.0"
+  },
+  "allowScripts": {
+    "workerd@1.20260917.1": true
   }
 }