jevx-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+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.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/README.md

@@ -0,0 +1,53 @@
+# Jevx MCP
+
+Run **[Jev AI](https://jevx.org)** typed decisions from any MCP client — Claude, Cursor, Cline, Codex. Give it a state and the questions you branch on, get back a choice, a score or a yes/no, with a calibrated probability on every option.
+
+Jev AI is a zero-shot decision model from TypeSafe: text or JSON in, typed values out — no dataset, fine-tune or retrain when the label set changes. Jevx is an independent playground and API for Jev AI and is not affiliated with TypeSafe AI.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `decide` | Send a state and up to 16 typed questions, get back choices, scores and noul values with probabilities |
+| `validate_questions` | Check a question's shape locally, free and without an API key, before spending credits on a malformed request |
+| `open_in_jevx` | The URL to try or continue a decision in the browser playground |
+
+## Install
+
+```bash
+npx jevx-mcp
+```
+
+### Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "jevx": {
+      "command": "npx",
+      "args": ["-y", "jevx-mcp"],
+      "env": { "JEVX_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+Create a key at [jevx.org/settings/apikeys](https://jevx.org/settings/apikeys?utm_source=mcp). There is no anonymous decisions endpoint — a key is required, same as running the playground signed out.
+
+### Cursor / Cline
+
+Point the client at `npx -y jevx-mcp` (stdio transport) and set `JEVX_API_KEY` in its environment.
+
+## Question shapes
+
+| type | criteria | returns |
+|---|---|---|
+| `choice` | object of option to meaning, two or more options | `choice`, `probabilities`, `confidence` |
+| `score` | ordered array, low to high | `score`, `probabilities`, `confidence` |
+| `noul` | exactly the keys `true` and `false` | value between 0 and 1, where exactly `0.5` means the model declined |
+
+The API answers HTTP 200 with a non-zero `code` on a refusal (bad key, malformed request); `decide` and `validate_questions` both surface that as a normal tool error, not a silent success.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,53 @@
+export type ChoiceQuestion = {
+    type: 'choice';
+    instructions: string;
+    criteria: Record<string, string>;
+};
+export type NoulQuestion = {
+    type: 'noul';
+    instructions: string;
+    criteria: {
+        true: string;
+        false: string;
+    };
+};
+export type ScoreQuestion = {
+    type: 'score';
+    instructions: string;
+    criteria: string[];
+};
+export type Question = ChoiceQuestion | NoulQuestion | ScoreQuestion;
+export type Answer = {
+    type: 'choice';
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence: number;
+} | {
+    type: 'noul';
+    noul: number;
+} | {
+    type: 'score';
+    score: number;
+    legend?: Record<string, string>;
+    probabilities: Record<string, number>;
+    confidence: number;
+};
+export type DecisionResult = {
+    answers: Record<string, Answer>;
+    model: string;
+    id: string;
+    charged: number;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        cost: number;
+    };
+};
+export declare class JevxError extends Error {
+}
+export declare const credentialsHint = "Set JEVX_API_KEY to run this \u2014 create one at https://jevx.org/settings/apikeys. There is no anonymous decisions endpoint: an account is required, same as running the playground signed out.";
+export declare function hasApiKey(): boolean;
+/** Local shape check, the same rules the API enforces. Returns problems, empty when valid. */
+export declare function validateQuestions(questions: Record<string, unknown>): string[];
+/** Run one typed decision against jevx.org. Throws JevxError on a bad key or an API refusal. */
+export declare function decide(state: string | Record<string, unknown> | unknown[], questions: Record<string, Question>, model?: string): Promise<DecisionResult>;

package/dist/client.js

@@ -0,0 +1,85 @@
+/**
+ * The whole of what this server needs from jevx.org: one POST. Zero
+ * dependencies — plain fetch against the same endpoint the site's own
+ * playground uses, so an MCP run is priced and charged exactly like a run on
+ * the site.
+ */
+const BASE_URL = (process.env.JEVX_BASE_URL?.replace(/\/$/, '')) || 'https://jevx.org';
+export class JevxError extends Error {
+}
+export const credentialsHint = 'Set JEVX_API_KEY to run this — create one at https://jevx.org/settings/apikeys. There is no anonymous decisions endpoint: an account is required, same as running the playground signed out.';
+export function hasApiKey() {
+    return Boolean(process.env.JEVX_API_KEY?.trim());
+}
+/** Local shape check, the same rules the API enforces. Returns problems, empty when valid. */
+export function validateQuestions(questions) {
+    const errors = [];
+    const names = Object.keys(questions ?? {});
+    if (!names.length)
+        errors.push('questions: add at least one question');
+    if (names.length > 16)
+        errors.push(`questions: ${names.length} is over the limit of 16 per request`);
+    for (const name of names) {
+        const q = questions[name];
+        const p = `questions.${name}`;
+        if (!q || typeof q !== 'object') {
+            errors.push(`${p}: expected an object`);
+            continue;
+        }
+        if (q.type !== 'choice' && q.type !== 'noul' && q.type !== 'score') {
+            errors.push(`${p}.type: expected choice | noul | score`);
+            continue;
+        }
+        if (typeof q.instructions !== 'string' || !q.instructions.trim())
+            errors.push(`${p}.instructions: required text`);
+        const c = q.criteria;
+        if (c === undefined || c === null) {
+            errors.push(`${p}.criteria: required`);
+        }
+        else if (q.type === 'score') {
+            if (!Array.isArray(c) || c.length < 2)
+                errors.push(`${p}.criteria: expected an array of two or more steps, low to high`);
+        }
+        else if (typeof c !== 'object' || Array.isArray(c)) {
+            errors.push(`${p}.criteria: expected an object`);
+        }
+        else {
+            const keys = Object.keys(c);
+            if (q.type === 'noul') {
+                if (keys.length !== 2 || !keys.includes('true') || !keys.includes('false')) {
+                    errors.push(`${p}.criteria: noul takes exactly the keys "true" and "false" (writing yes/no is the common mistake)`);
+                }
+            }
+            else if (keys.length < 2) {
+                errors.push(`${p}.criteria: choice needs two or more options`);
+            }
+        }
+    }
+    return errors;
+}
+/** Run one typed decision against jevx.org. Throws JevxError on a bad key or an API refusal. */
+export async function decide(state, questions, model) {
+    const key = process.env.JEVX_API_KEY?.trim();
+    if (!key)
+        throw new JevxError(credentialsHint);
+    const res = await fetch(`${BASE_URL}/api/decisions/run`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+        body: JSON.stringify({ state, questions, ...(model ? { model } : {}) }),
+    });
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        throw new JevxError(`jevx.org returned non-JSON (HTTP ${res.status})`);
+    }
+    // The API answers HTTP 200 with `code: -1` for refusals (bad key, malformed
+    // request). Reading the status code alone reports success on a failure.
+    if (json.code !== 0)
+        throw new JevxError(json.message || `request failed (HTTP ${res.status})`);
+    if (!json.data || json.data.error)
+        throw new JevxError(json.data?.error || 'empty response');
+    return json.data;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * jevx-mcp — run Jev AI typed decisions from any MCP client.
+ *
+ * Every call goes through jevx.org's public decisions API with the caller's
+ * own API key, so a run costs the same credits and is billed exactly like a
+ * run made in the Jevx playground.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { credentialsHint, decide, hasApiKey, JevxError, validateQuestions, } from './client.js';
+const server = new McpServer({ name: 'jevx-mcp', version: '0.1.0' });
+const text = (body) => ({ content: [{ type: 'text', text: body }] });
+const fail = (body) => ({ ...text(body), isError: true });
+const questionSchema = z
+    .record(z.string(), z.object({
+    type: z.enum(['choice', 'noul', 'score']).describe('choice = pick one of several options; noul = yes/no with exactly the keys true and false; score = one step on an ordered scale'),
+    instructions: z.string().describe('Plain-language instructions for this one question.'),
+    criteria: z
+        .union([z.record(z.string(), z.string()), z.array(z.string())])
+        .describe('choice: object of option to meaning (2+ options). noul: object with exactly the keys "true" and "false". score: ordered array, low to high.'),
+}))
+    .describe('Up to 16 named questions, all judged against the same state.');
+server.registerTool('validate_questions', {
+    title: 'Check a Jev AI question shape',
+    description: 'Run the same shape checks the Jev API enforces, without spending credits or needing an API key. Use this first when writing questions by hand — a malformed question otherwise comes back as a deeply nested validation error.',
+    inputSchema: { questions: questionSchema },
+}, async ({ questions }) => {
+    const problems = validateQuestions(questions);
+    if (!problems.length)
+        return text('No shape problems found. Every question has a type, instructions and criteria in the shape the API accepts.');
+    return fail(`${problems.length} problem(s):\n` + problems.map((p) => `- ${p}`).join('\n'));
+});
+server.registerTool('decide', {
+    title: 'Run a Jev AI decision',
+    description: 'Send a state (text or JSON) and up to 16 typed questions to Jev AI on jevx.org, and get back the choice, score or yes/no for each — with a calibrated probability on every option. Needs JEVX_API_KEY. Branch your own code on the returned probabilities, not just the top label; a noul of exactly 0.5 means the model declined to answer.',
+    inputSchema: {
+        state: z.union([z.string(), z.record(z.string(), z.unknown()), z.array(z.unknown())]).describe('The thing being judged: plain text, or a JSON object/array.'),
+        questions: questionSchema,
+        model: z.string().optional().describe('Pin a dated model id for reproducible answers; omit to use the floating alias.'),
+    },
+}, async ({ state, questions, model }) => {
+    if (!hasApiKey())
+        return fail(credentialsHint);
+    const problems = validateQuestions(questions);
+    if (problems.length)
+        return fail(`Fix the question shape first:\n` + problems.map((p) => `- ${p}`).join('\n'));
+    try {
+        const result = await decide(state, questions, model);
+        const lines = Object.entries(result.answers).map(([name, a]) => {
+            if (a.type === 'choice')
+                return `- ${name}: ${a.choice} (confidence ${a.confidence}) — probabilities ${JSON.stringify(a.probabilities)}`;
+            if (a.type === 'score')
+                return `- ${name}: ${a.score} (confidence ${a.confidence}) — probabilities ${JSON.stringify(a.probabilities)}`;
+            return `- ${name}: ${a.noul}${a.noul === 0.5 ? ' (declined to answer)' : ''}`;
+        });
+        return text(`Model: ${result.model}\nCharged: ${result.charged} credits\n\n${lines.join('\n')}\n\nRequest id: ${result.id}`);
+    }
+    catch (e) {
+        const message = e instanceof JevxError ? e.message : String(e);
+        return fail(`Decision refused: ${message}`);
+    }
+});
+server.registerTool('open_in_jevx', {
+    title: 'Open the Jevx playground',
+    description: 'The URL to try or continue a decision in the browser playground.',
+    inputSchema: {},
+}, async () => text('https://jevx.org/?utm_source=mcp'));
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "jevx-mcp",
+  "version": "0.1.0",
+  "mcpName": "org.jevx/jevx-mcp",
+  "description": "MCP server for Jevx (jevx.org) — run Jev AI typed decisions (choice, score, noul with probabilities) from any MCP client, on your own Jevx API key.",
+  "keywords": ["mcp", "model-context-protocol", "jev-ai", "decisions", "classification", "zero-shot", "typesafe", "jevx"],
+  "homepage": "https://jevx.org",
+  "bugs": { "url": "https://github.com/hanshs474/jevx-mcp/issues" },
+  "repository": { "type": "git", "url": "git+https://github.com/hanshs474/jevx-mcp.git" },
+  "license": "MIT",
+  "author": "Jevx (https://jevx.org)",
+  "type": "module",
+  "bin": { "jevx-mcp": "dist/index.js" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": { "build": "tsc && chmod +x dist/index.js", "start": "node dist/index.js", "prepublishOnly": "npm run build", "test": "node --test test/decide.test.js" },
+  "dependencies": { "@modelcontextprotocol/sdk": "^1.12.0", "zod": "^3.23.8" },
+  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0" },
+  "engines": { "node": ">=18" }
+}