@jkudish/jev-mcp 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.10.0
+
+- Opt-in stateless Streamable HTTP: `jev-mcp --http` (or `JEV_MCP_TRANSPORT=http`) serves MCP 2026-07-28 per request and 2025-era clients through the SDK's stateless fallback, with no sessions, on `PORT` (default 8080) at `/mcp`, with `/health`. `HOST` defaults to loopback; binding beyond it is explicit. `JEV_MCP_AUTH_TOKEN` gates it with a bearer token and is required unless `HOST` is loopback; Host/Origin rebinding guards answer fixed-string 403s. Concurrent requests are capped at `JEV_MCP_MAX_CONCURRENCY` (default 16) with `429` backpressure, and a cancelled request aborts its in-flight regex worker and Jev calls. Stdio stays the default. Via [#37](https://github.com/jkudish/jev-mcp/pull/37) by shivasymbl.
+- Stdio now also answers 2026-07-28 clients; 2025-era clients see no change.
+- Client-visible provider errors are fixed strings (provider name and status only); upstream response text, including reflected credentials, never reaches tool error content.
+- `jev_classify` keeps label ids collision-free and tallies on a null prototype, so labels like `constructor` or `__proto__` can no longer shadow `Object.prototype` or collide with generated ids. Via [#36](https://github.com/jkudish/jev-mcp/pull/36) by kittimzhe.
+- `jev_verify` no longer mistakes an evidence item literally named `none` for its internal no-source option; the internal key now skips occupied `none_N` ids. Via [#38](https://github.com/jkudish/jev-mcp/pull/38) by xujiantop-crypto.
+- Internal: `@modelcontextprotocol/sdk` 1.x replaced by the v2 packages `@modelcontextprotocol/server` and `@modelcontextprotocol/node` 2.1.0; tools are registered once and replayed onto a fresh server per connection or request.
+
+## 0.9.0
+
+- Ships an agent skill inside the package: `skills/jev/` is included in the npm tarball, so coding agents get judgment-tool policy — which tool to call when, fail-closed handling, privacy — without hand-written prompts. Prompted by [#34](https://github.com/jkudish/jev-mcp/issues/34) by panaalexandrucristian.
+- `jev_extract` keeps multi-letter regex flags (`gi`) intact instead of mangling them into `gig` and throwing. Found in [#34](https://github.com/jkudish/jev-mcp/issues/34).
+- Internal: zod 4 and TypeScript 7; no tool behavior changes. `tools/list` input schemas gain a `propertyNames` field from zod 4's JSON Schema conversion. Via [#35](https://github.com/jkudish/jev-mcp/pull/35).
+- Dependency updates: `@jkudish/jev-agent-tools` 0.1.2 and `@modelcontextprotocol/sdk` 1.30.1.
+
 ## 0.8.0
 
 - New `jev_noul` tool: batched calibrated probability for stated propositions, labeled likely / unlikely / uncertain. Prompted by [#31](https://github.com/jkudish/jev-mcp/issues/31).

package/README.md

@@ -3,6 +3,10 @@
 [![CI](https://github.com/jkudish/jev-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jkudish/jev-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+<p align="center">
+  <img src=".github/jev-mcp-og.png" alt="jev-mcp — Fast, cheap, typed judgments from TypeSafe's Jev model, as MCP tools." />
+</p>
+
 Fast, cheap, typed judgments from TypeSafe's Jev model, as MCP tools.
 
 Give your agent eleven judgment tools:
@@ -124,6 +128,34 @@ args = ["-y", "@jkudish/jev-mcp"]
 
 Some MCP clients filter the environment before spawning servers, which silently drops `TYPESAFE_API_KEY`. If the server reports a missing key, pass it explicitly as shown above.
 
+### Remote / HTTP
+
+Stdio is the default. To host one shared server for a team or a remote agent, run it in stateless HTTP mode:
+
+```bash
+JEV_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" TYPESAFE_API_KEY=ts_... npx -y @jkudish/jev-mcp --http
+```
+
+It listens on `PORT` (default `8080`) and `HOST` (default `127.0.0.1` — set `HOST=0.0.0.0` explicitly to serve beyond your machine), serves MCP at `/mcp` and a health check at `/health`. It speaks MCP 2026-07-28 and falls back to stateless serving for 2025-era clients, so it keeps no sessions and scales behind any load balancer. Every call spends your Jev key, so `JEV_MCP_AUTH_TOKEN` is required unless `HOST` is loopback. Clients send it as a bearer token:
+
+```bash
+claude mcp add --transport http jev https://jev.example.com/mcp --header "Authorization: Bearer $JEV_MCP_AUTH_TOKEN"
+```
+
+The server itself speaks plain HTTP: terminate TLS at a reverse proxy or load balancer before exposing it beyond loopback, and put connection limits and request rate limits at that ingress — the process bounds admitted `/mcp` requests (`JEV_MCP_MAX_CONCURRENCY`, default 16; excess shed with `429`) and caps request bodies at 4 MiB, but it does not limit sockets waiting to finish headers or repeatedly rejected requests.
+
+### Agent skill
+
+The package ships an agent skill (`skills/jev/`) that teaches coding agents when to reach for each tool instead of answering from their own reading — the difference between tools that sit registered-but-unused and tools that get called. Copy it into your client's skills directory:
+
+```bash
+npm pack @jkudish/jev-mcp@latest
+tar -xzf jkudish-jev-mcp-*.tgz
+mkdir -p .claude/skills && cp -R package/skills/jev .claude/skills/
+```
+
+Claude Code reads `.claude/skills`, OpenCode `.opencode/skills`, and Codex and generic agents `.agents/skills`. In Amp, the skill's frontmatter bundles the MCP server, so dropping it into a skills directory wires up both.
+
 ## The tools
 
 ### jev_verify

package/dist/http.d.ts

@@ -0,0 +1,5 @@
+import { type McpServer } from "@modelcontextprotocol/server";
+export declare function serveHttp(factory: () => McpServer, env?: NodeJS.ProcessEnv): Promise<{
+    server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
+    url: string;
+}>;

package/dist/http.js

@@ -0,0 +1,101 @@
+// Opt-in stateless Streamable HTTP transport (`jev-mcp --http`).
+//
+// Serves MCP 2026-07-28 per request and 2025-era clients through the SDK's
+// stateless fallback: no sessions, no Mcp-Session-Id, nothing held between
+// requests, so any number of replicas can sit behind a plain load balancer.
+import { createServer as createNodeServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { toNodeHandler } from "@modelcontextprotocol/node";
+const LOOPBACK = new Set(["127.0.0.1", "::1", "localhost"]);
+// Fixed-string rejection: never echo the rejected Host/Origin back (reflection
+// of attacker-controlled values), unlike the SDK's guards.
+const FORBIDDEN_BODY = JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Forbidden" }, id: null });
+function forbidden(res) {
+    res.writeHead(403, { "content-type": "application/json" }).end(FORBIDDEN_BODY);
+}
+function isLoopbackHost(host) {
+    if (!host)
+        return false;
+    let hostname = host.toLowerCase();
+    const bracketed = hostname.match(/^\[(.+)\](?::\d+)?$/);
+    if (bracketed)
+        hostname = bracketed[1];
+    else
+        hostname = hostname.replace(/:\d+$/, "");
+    return hostname === "127.0.0.1" || hostname === "::1" || hostname === "localhost";
+}
+function isLoopbackOrigin(origin) {
+    if (origin === undefined)
+        return true;
+    try {
+        return isLoopbackHost(new URL(origin).host);
+    }
+    catch {
+        return false;
+    }
+}
+export async function serveHttp(factory, env = process.env) {
+    // Loopback by default: binding a public interface is an explicit act.
+    const host = env.HOST || "127.0.0.1";
+    const port = Number(env.PORT || 8080);
+    const token = Buffer.from(env.JEV_MCP_AUTH_TOKEN ?? "");
+    const maxInFlight = Number(env.JEV_MCP_MAX_CONCURRENCY ?? 16);
+    // The server spends the operator's Jev key on every call; never expose it unauthenticated.
+    if (token.length === 0 && !LOOPBACK.has(host)) {
+        throw new Error("JEV_MCP_AUTH_TOKEN is required when HTTP mode binds a non-loopback HOST");
+    }
+    if (!Number.isInteger(maxInFlight) || maxInFlight < 1) {
+        throw new Error("JEV_MCP_MAX_CONCURRENCY must be a positive integer");
+    }
+    const authorized = (header) => {
+        if (token.length === 0)
+            return true;
+        const given = Buffer.from(header?.startsWith("Bearer ") ? header.slice(7) : "");
+        return given.length === token.length && timingSafeEqual(given, token);
+    };
+    // On loopback, reject foreign Host/Origin headers so a web page cannot reach
+    // the server through DNS rebinding (the spec's Origin-validation MUST).
+    const onLoopback = LOOPBACK.has(host);
+    const mcp = toNodeHandler(createMcpHandler(factory), {
+        onerror: (error) => console.error(`[jev-mcp] http: ${error.message}`),
+    });
+    let inFlight = 0;
+    const server = createNodeServer((req, res) => {
+        const path = (req.url ?? "/").split("?")[0];
+        if (path === "/health") {
+            res.writeHead(200, { "content-type": "text/plain" }).end("ok");
+        }
+        else if (path !== "/mcp") {
+            res.writeHead(404).end();
+        }
+        else if (onLoopback && (!isLoopbackHost(req.headers.host) || !isLoopbackOrigin(req.headers.origin))) {
+            forbidden(res);
+        }
+        else if (!authorized(req.headers.authorization)) {
+            res.writeHead(401, { "www-authenticate": "Bearer" }).end();
+        }
+        else if (inFlight >= maxInFlight) {
+            // Backpressure: each in-flight request replays tools and may spend the
+            // operator's Jev key; shed load instead of queueing it.
+            res.writeHead(429, { "retry-after": "1" }).end();
+        }
+        else {
+            inFlight++;
+            void mcp(req, res).finally(() => inFlight--);
+        }
+    });
+    await new Promise((resolve) => server.listen(port, host, resolve));
+    const { port: bound, address: boundAddress } = server.address();
+    // "localhost" must actually resolve to loopback; a poisoned resolver must not
+    // silently turn a loopback bind into a public one.
+    if (onLoopback && boundAddress !== "127.0.0.1" && boundAddress !== "::1" && boundAddress !== "::ffff:127.0.0.1") {
+        server.close();
+        throw new Error(`HOST ${host} resolved to non-loopback ${boundAddress}; refusing to serve`);
+    }
+    const shutdown = () => server.close(() => process.exit(0));
+    process.once("SIGTERM", shutdown);
+    process.once("SIGINT", shutdown);
+    return { server, url: `http://${host.includes(":") ? `[${host}]` : host}:${bound}/mcp` };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+import { McpServer } from "@modelcontextprotocol/server";
+export declare function createServer(): McpServer;