jev-decision-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan (amidabuddha)
+
+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,146 @@
+# Jev Decision MCP
+
+A local stdio MCP server exposing one tool, **`jev_decide`**, for typed decisions through the official TypeSafe API. Written in TypeScript with the official MCP and TypeSafe SDKs.
+
+Independent community project; not affiliated with TypeSafe. Licensed under [MIT](LICENSE).
+
+| Question | Use it for | Result |
+| --- | --- | --- |
+| `choice` | Choose a label or candidate | Choice, probabilities, confidence |
+| `score` | Rate a single dimension on 2–10 ordered levels | 0-based score, probabilities, legend, confidence |
+| `noul` | Judge whether a condition holds | Probability of yes, from 0 to 1 |
+
+Batch independent questions over the same context in one call. Answers retain their question IDs. The MCP returns judgments and token usage; the caller owns thresholds, escalation, and action execution.
+
+## Setup
+
+Requires Node.js 22 or newer.
+
+```sh
+git clone https://github.com/amidabuddha/jev-decision-mcp.git
+cd jev-decision-mcp
+npm ci
+cp -n .env.example .env
+# Edit .env and set TYPESAFE_API_KEY.
+npm run build
+```
+
+Obtain the key from [TypeSafe Console](https://console.typesafe.ai). Use an official TypeSafe key, rather than an OpenRouter or third-party gateway key.
+
+`.env` is excluded by `.gitignore`. The server reads the `.env` beside this README even when started from another working directory. Existing process environment variables take precedence. Restart the MCP server after editing `.env`.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `TYPESAFE_API_KEY` | Required for calls | TypeSafe API credential |
+| `TYPESAFE_DEFAULT_MODEL` | `jev-latest` | Default model; each call can override it |
+| `JEV_TIMEOUT_MS` | `30000` | Total deadline including retries; 1–120000 ms |
+
+The server starts without a key so a host can discover the tool. Calls then return `MISSING_API_KEY`. API traffic is fixed to `https://api.typesafe.ai/v1/systemone`; `TYPESAFE_BASE_URL` does not override it. State and questions are sent to TypeSafe and may incur API charges. The server does not persist inputs or decisions and disables SDK logging. Upstream error bodies are not exposed because they may echo submitted data.
+
+## Connect to Codex
+
+After building, run:
+
+```sh
+codex mcp add jev -- "$(command -v node)" "$PWD/dist/index.js"
+```
+
+Run this command from the repository root. It registers the absolute paths to your Node executable and built server.
+
+Alternatively, merge this into your Codex `config.toml`, replacing the example paths with your absolute paths:
+
+```toml
+[mcp_servers.jev]
+command = "/opt/homebrew/bin/node"
+args = ["/absolute/path/to/jev-decision-mcp/dist/index.js"]
+tool_timeout_sec = 45
+```
+
+Keep the host tool timeout above `JEV_TIMEOUT_MS / 1000`. The key stays in `.env`; it need not appear in the command or MCP configuration. See [official Codex MCP configuration](https://developers.openai.com/codex/mcp).
+
+For other stdio MCP hosts, configure your absolute paths similarly:
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "/opt/homebrew/bin/node",
+      "args": ["/absolute/path/to/jev-decision-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+The host starts the process and communicates over stdin/stdout. For interactive local development use `npm run dev`; this is not an HTTP server. No host configuration is modified by setup or tests.
+
+## Call the tool
+
+Call `jev_decide` with the JSON in [examples/decision.json](examples/decision.json). It combines a team choice, a refund yes/no judgment, and an urgency score. Smaller example:
+
+```json
+{
+  "state": { "request": "Please refund the duplicate charge." },
+  "questions": {
+    "route": {
+      "type": "choice",
+      "instructions": "Which team should handle `request`?",
+      "criteria": {
+        "billing": "Charges, invoices, refunds",
+        "technical": "Broken software or integrations",
+        "other": "Neither billing nor technical"
+      }
+    }
+  }
+}
+```
+
+The response contains `model`, `answers`, and `usage`, both as MCP structured content and JSON text. Choice supports 1–255 named options. Instructions and descriptions may be strings, JSON objects, or arrays; choice descriptions may also be null. Noul accepts optional `criteria.true` and `criteria.false` descriptions.
+
+Supply relevant facts, source text, and policies explicitly: Jev cannot see the caller's conversation or local files. Write complete judgments in `instructions`; IDs are only response keys. Include a no-match option when appropriate. Questions in one batch cannot see one another's answers. A noul near 0.5 is uncertainty about yes/no, not medium intensity. Confidence does not authorize actions or guarantee correctness; evaluate thresholds on representative data.
+
+## Verify
+
+```sh
+npm run check       # Type checking + mocked API tests + real stdio MCP handshake
+npm run test:live   # Explicit live API call using only the synthetic example
+npm run test:codex  # Installed Codex schema parser + native MCP discovery, no model turn
+# Add -- --live to test:codex to also call Jev through Codex's native MCP interface.
+```
+
+Normal tests use synthetic credentials and mocked HTTP responses; they do not contact TypeSafe. Tests cover mixed decisions, input/output validation, missing keys, authentication errors, rate-limit retries, deadlines, cancellation, and MCP discovery/calls. The stdio smoke test starts from another working directory and checks that stdout remains valid MCP.
+
+The live test requires your key, starts the built MCP server, calls `jev_decide` through an MCP client, validates the response, and prints judgments, elapsed time, and token usage. A passing live smoke test verifies integration, not general decision quality. SDK retries can make up to three HTTP attempts for transient failures, bounded by the total deadline.
+
+`test:codex` requires the Codex CLI. It uses an ephemeral diagnostic context without starting a model turn. It verifies that Codex rejects the original tuple-style score schema, accepts the repaired array schema, and discovers the MCP tool. Passing generic MCP client tests alone does not establish Codex compatibility.
+
+If an older session cannot see the tool after a server update, start a fresh task so it loads the rebuilt server. The MCP server is named `jev` and its tool is `jev_decide`; `$Jev` is not an installed skill.
+
+Service/configuration failures are MCP tool errors (`isError: true`), never invented decisions. Codes include `MISSING_API_KEY`, `INVALID_INPUT`, `INVALID_RESPONSE`, `API_ERROR`, `CONNECTION_ERROR`, `TIMEOUT`, and `CANCELLED`. Invalid arguments may also be rejected directly by the MCP SDK.
+
+## References
+
+Built using the `typesafe-ai` skill and official documentation, checked September 22, 2026:
+
+- [TypeSafe HTTP API](https://docs.typesafe.ai/api)
+- [TypeSafe JavaScript SDK](https://docs.typesafe.ai/sdk/javascript)
+- [Decision primitives and question design](https://docs.typesafe.ai/primitives)
+- [Function-calling cookbook](https://docs.typesafe.ai/cookbooks/function_calling)
+- [MCP server development](https://modelcontextprotocol.io/docs/develop/build-server)
+
+`jev-latest` follows TypeSafe model updates. For repeatable evaluations, set a specific supported model version. SDK versions are recorded in `package-lock.json`.
+
+## Releases and package publishing
+
+GitHub releases provide source archives. The repository also includes npm packaging
+and official MCP Registry metadata in `server.json`. npm and registry publication
+are separate steps; a GitHub release does not imply that either listing is live.
+
+To verify the publishable artifact locally, run `npm pack --dry-run`. The package
+contains the compiled server, license, README, example input, and registry metadata.
+Local `.env` files, tests, and development dependencies are not bundled.
+
+After the npm package has been published, clients can launch it with
+`npx -y jev-decision-mcp@0.1.0`. For that installation method, provide
+`TYPESAFE_API_KEY` in the MCP host's environment; the package does not read a `.env`
+from the caller's working directory. The clone-and-build setup above remains
+available independently of npm publication.

package/dist/config.js

@@ -0,0 +1,24 @@
+import { loadEnvFile } from "node:process";
+import { fileURLToPath } from "node:url";
+export function loadProjectEnv() {
+    try {
+        // Resolve beside the project, even when an MCP host starts us in another cwd.
+        // Existing process environment variables take precedence.
+        loadEnvFile(fileURLToPath(new URL("../.env", import.meta.url)));
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+}
+export function readConfig(env = process.env) {
+    const timeoutMs = Number(env.JEV_TIMEOUT_MS ?? 30000);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) {
+        throw new Error("JEV_TIMEOUT_MS must be an integer from 1 to 120000");
+    }
+    return {
+        apiKey: env.TYPESAFE_API_KEY?.trim() || undefined,
+        model: env.TYPESAFE_DEFAULT_MODEL?.trim() || "jev-latest",
+        timeoutMs,
+    };
+}

package/dist/decision.js

@@ -0,0 +1,60 @@
+import { APIConnectionError, APIError, APITimeoutError, APIUserAbortError, TypeSafeClient } from "@typesafe-ai/sdk";
+import { decisionInput, validateResponse } from "./schema.js";
+export class DecisionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function createDecider(config, fetch) {
+    const client = config.apiKey ? new TypeSafeClient({
+        apiKey: config.apiKey,
+        // Always use the official origin; tool input cannot redirect credentials.
+        baseURL: "https://api.typesafe.ai",
+        defaultModel: config.model,
+        timeout: Math.min(config.timeoutMs, 10000),
+        logLevel: "off",
+        ...(fetch ? { fetch } : {}),
+    }) : undefined;
+    return async (raw, signal) => {
+        const parsed = decisionInput.safeParse(raw);
+        if (!parsed.success)
+            throw new DecisionError("INVALID_INPUT", "Invalid decision request. Check state, instructions and criteria against the tool schema.");
+        if (!client)
+            throw new DecisionError("MISSING_API_KEY", "Set TYPESAFE_API_KEY in the project .env or process environment, then restart the MCP server.");
+        const deadline = AbortSignal.timeout(config.timeoutMs);
+        try {
+            // Runtime validation guarantees Score's minimum two entries, expressed
+            // as a tuple by the SDK but as a homogeneous array in our MCP schema.
+            const result = await client.systemOne(parsed.data, {
+                signal: signal ? AbortSignal.any([signal, deadline]) : deadline,
+            });
+            try {
+                return validateResponse(result, parsed.data);
+            }
+            catch {
+                throw new DecisionError("INVALID_RESPONSE", "TypeSafe returned a response that does not match the requested decision schema.");
+            }
+        }
+        catch (error) {
+            if (error instanceof DecisionError)
+                throw error;
+            if (error instanceof APIUserAbortError || error instanceof APITimeoutError) {
+                throw new DecisionError(signal?.aborted ? "CANCELLED" : "TIMEOUT", signal?.aborted ? "Decision request cancelled." : "TypeSafe request exceeded its timeout.");
+            }
+            if (error instanceof APIError) {
+                // Upstream bodies can echo submitted data. Expose only a status-based message.
+                const guidance = error.status === 401 ? "Check TYPESAFE_API_KEY."
+                    : error.status === 403 ? "Check account permissions."
+                        : error.status === 422 ? "Check the model, question instructions and criteria."
+                            : error.status === 429 ? "Rate limit reached; retry later."
+                                : "The service rejected the request; retry later if temporary.";
+                throw new DecisionError("API_ERROR", `TypeSafe HTTP ${error.status}. ${guidance}`);
+            }
+            if (error instanceof APIConnectionError)
+                throw new DecisionError("CONNECTION_ERROR", "Could not connect to TypeSafe. Check network access.");
+            throw new DecisionError("INTERNAL_ERROR", "The decision request failed unexpectedly.");
+        }
+    };
+}

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadProjectEnv, readConfig } from "./config.js";
+import { createDecider } from "./decision.js";
+import { createServer } from "./server.js";
+try {
+    loadProjectEnv();
+    const server = createServer(createDecider(readConfig()));
+    await server.connect(new StdioServerTransport());
+}
+catch {
+    // stdout is reserved for MCP; never print environment values or error bodies.
+    console.error("Jev MCP could not start. Check .env readability and JEV_TIMEOUT_MS (1–120000).");
+    process.exitCode = 1;
+}

package/dist/schema.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+const entry = z.union([z.string().min(1), z.record(z.string(), z.json()), z.array(z.json())]);
+const description = entry.nullable();
+const key = z.string().min(1);
+const question = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal("choice"),
+        instructions: entry,
+        criteria: z.record(key, description).refine((value) => Object.keys(value).length >= 1 && Object.keys(value).length <= 255, "Choice requires 1 to 255 options"),
+    }),
+    z.strictObject({
+        type: z.literal("score"),
+        instructions: entry,
+        // A tuple emits draft-07 `items: [...]`, which Codex cannot deserialize.
+        // Homogeneous array items preserve the same 2–10-level contract.
+        criteria: z.array(entry).min(2).max(10),
+    }),
+    z.strictObject({
+        type: z.literal("noul"),
+        instructions: entry,
+        criteria: z.strictObject({ true: description.optional(), false: description.optional() }).optional(),
+    }),
+]);
+export const decisionInput = z.strictObject({
+    state: entry.describe("Relevant source text or JSON context; include evidence, definitions and policies needed for the questions."),
+    questions: z.record(key, question).refine((value) => Object.keys(value).length > 0, "Provide at least one question")
+        .describe("Named independent questions over the same state. IDs are not model instructions; write each full judgment in instructions."),
+    model: z.string().trim().min(1).optional().describe("Optional TypeSafe model override; defaults to the configured model or jev-latest."),
+});
+const probability = z.number().min(0).max(1);
+const probabilities = z.record(key, probability);
+const answer = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("noul"), noul: probability }),
+    z.object({ type: z.literal("choice"), choice: z.string(), probabilities, confidence: probability }),
+    z.object({ type: z.literal("score"), score: z.number(), legend: z.record(key, description), probabilities, confidence: probability }),
+]);
+export const decisionOutput = z.object({
+    model: z.string().min(1),
+    answers: z.record(key, answer),
+    usage: z.object({ input_tokens: z.number().int().nonnegative(), output_tokens: z.number().int().nonnegative() }),
+});
+function sameKeys(actual, expected) {
+    return Object.keys(actual).length === expected.length && expected.every((id) => Object.hasOwn(actual, id));
+}
+export function validateResponse(raw, input) {
+    const result = decisionOutput.parse(raw);
+    if (!sameKeys(result.answers, Object.keys(input.questions)))
+        throw new Error("Answer IDs do not match questions");
+    for (const [id, question] of Object.entries(input.questions)) {
+        const answer = result.answers[id];
+        if (!answer || answer.type !== question.type)
+            throw new Error("Answer type does not match question");
+        if (answer.type === "noul")
+            continue;
+        const levels = question.type === "choice" ? Object.keys(question.criteria)
+            : question.type === "score" ? question.criteria.map((_, index) => String(index)) : [];
+        if (!sameKeys(answer.probabilities, levels))
+            throw new Error("Probability labels do not match criteria");
+        const sum = Object.values(answer.probabilities).reduce((a, b) => a + b, 0);
+        if (Math.abs(sum - 1) > 0.001)
+            throw new Error("Probabilities do not sum to one");
+        if (answer.type === "choice" && !levels.includes(answer.choice))
+            throw new Error("Unknown choice");
+        if (answer.type === "score" && (answer.score < 0 || answer.score > levels.length - 1 || !sameKeys(answer.legend, levels))) {
+            throw new Error("Score or legend does not match criteria");
+        }
+    }
+    return result;
+}

package/dist/server.js

@@ -0,0 +1,23 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DecisionError } from "./decision.js";
+import { decisionInput, decisionOutput } from "./schema.js";
+export function createServer(decide) {
+    const server = new McpServer({ name: "jev-decision-mcp", version: "0.1.0" });
+    server.registerTool("jev_decide", {
+        title: "Ask Jev for typed decisions",
+        description: "Evaluate supplied context using TypeSafe Jev. Batch independent, narrow questions in one call: choice selects a provided label; score returns a position on 2–10 ordered levels (0-based); noul returns probability of yes, not intensity. Supply relevant evidence and full instructions; question IDs are not sent to the model. Include an other/none choice when appropriate. Questions cannot use each other's answers. Returns raw judgments, probabilities, confidence for choice/score, and token usage. Use caller-defined policies for uncertainty. This sends the supplied state and questions to TypeSafe and may incur API charges. It does not execute selected actions.",
+        inputSchema: decisionInput,
+        outputSchema: decisionOutput,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (input, extra) => {
+        try {
+            const result = await decide(input, extra.signal);
+            return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result };
+        }
+        catch (error) {
+            const safe = error instanceof DecisionError ? error : new DecisionError("INTERNAL_ERROR", "Decision request failed.");
+            return { isError: true, content: [{ type: "text", text: JSON.stringify({ error: safe.code, message: safe.message }) }] };
+        }
+    });
+    return server;
+}

package/examples/decision.json

@@ -0,0 +1,30 @@
+{
+  "state": {
+    "ticket": "I was charged twice for order A-104. Please refund the duplicate charge today.",
+    "policy": "Duplicate charges should be reviewed by billing. This tool only classifies the request."
+  },
+  "questions": {
+    "team": {
+      "type": "choice",
+      "instructions": "Which team should handle the issue in `ticket`?",
+      "criteria": {
+        "billing": "Charges, invoices, or refunds",
+        "technical": "Broken features or software failures",
+        "other": "Neither billing nor technical"
+      }
+    },
+    "refund_requested": {
+      "type": "noul",
+      "instructions": "Does the customer explicitly request a refund in `ticket`?"
+    },
+    "urgency": {
+      "type": "score",
+      "instructions": "How time-sensitive is the customer's requested response in `ticket`?",
+      "criteria": [
+        "No response deadline or time pressure is stated",
+        "A response is requested within several days",
+        "A response is requested today or immediately"
+      ]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "jev-decision-mcp",
+  "version": "0.1.0",
+  "description": "A local MCP server for TypeSafe Jev typed decisions",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "npm run build && tsx --test test/*.test.ts",
+    "check": "tsc -p tsconfig.check.json && npm test",
+    "test:live": "npm run build && tsx scripts/live-test.ts",
+    "test:codex": "npm run build && node --import tsx scripts/check-codex-schema.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@typesafe-ai/sdk": "0.6.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.0"
+  },
+  "license": "MIT",
+  "author": "Stefan (amidabuddha)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amidabuddha/jev-decision-mcp.git"
+  },
+  "homepage": "https://github.com/amidabuddha/jev-decision-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/amidabuddha/jev-decision-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "jev",
+    "typesafe",
+    "codex",
+    "classification"
+  ],
+  "bin": {
+    "jev-decision-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "examples/decision.json",
+    "server.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "mcpName": "io.github.amidabuddha/jev-decision-mcp"
+}

package/server.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.amidabuddha/jev-decision-mcp",
+  "description": "Typed Jev decisions in one batched tool: choice, score, and yes/no probabilities.",
+  "repository": {
+    "url": "https://github.com/amidabuddha/jev-decision-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "jev-decision-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "TYPESAFE_API_KEY",
+          "description": "Your TypeSafe API key from console.typesafe.ai",
+          "isRequired": true,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "TYPESAFE_DEFAULT_MODEL",
+          "description": "Default Jev model",
+          "default": "jev-latest",
+          "format": "string"
+        },
+        {
+          "name": "JEV_TIMEOUT_MS",
+          "description": "Total request deadline in milliseconds, including retries (1\u2013120000)",
+          "default": "30000",
+          "format": "number"
+        }
+      ]
+    }
+  ]
+}