jev-decision-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,7 @@
 # Jev Decision MCP
 
+[![Jev Decision MCP – quality and maintenance score on Glama](https://glama.ai/mcp/servers/amidabuddha/jev-decision-mcp/badges/card.svg)](https://glama.ai/mcp/servers/amidabuddha/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).
@@ -12,7 +14,56 @@ Independent community project; not affiliated with TypeSafe. Licensed under [MIT
 
 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
+## Install from npm
+
+Requires Node.js 22 or newer. The published package runs without cloning or building:
+
+```sh
+npx -y jev-decision-mcp@0.1.2
+```
+
+Set `TYPESAFE_API_KEY` in your MCP host's environment. For hosts that use
+`mcpServers` JSON configuration:
+
+```json
+{
+  "mcpServers": {
+    "jev": {
+      "command": "npx",
+      "args": ["-y", "jev-decision-mcp@0.1.2"]
+    }
+  }
+}
+```
+
+Node.js and npm must be installed and available on the host's `PATH`. If the
+host cannot resolve `npx`, use its platform-specific launcher or absolute path
+as documented by that host. GUI applications may have a different `PATH` from
+your terminal.
+
+The server communicates over stdio; starting it in a terminal waits for an MCP
+client rather than opening a web page. The npm installation does not read a
+`.env` from the caller's working directory.
+
+Package: [jev-decision-mcp on npm](https://www.npmjs.com/package/jev-decision-mcp).
+
+## Connect to Codex
+
+For the npm package, merge this into your Codex `config.toml`:
+
+```toml
+[mcp_servers.jev]
+command = "npx"
+args = ["-y", "jev-decision-mcp@0.1.2"]
+env_vars = ["TYPESAFE_API_KEY"]
+tool_timeout_sec = 45
+```
+
+Set `TYPESAFE_API_KEY` in the environment that launches Codex; `env_vars` forwards
+its existing value to the server. Keep the host tool timeout above
+`JEV_TIMEOUT_MS / 1000`. See [official Codex MCP configuration](https://developers.openai.com/codex/mcp).
+
+## Setup from source
 
 Requires Node.js 22 or newer.
 
@@ -20,8 +71,7 @@ Requires Node.js 22 or newer.
 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.
+# Copy .env.example to .env and set TYPESAFE_API_KEY.
 npm run build
 ```
 
@@ -37,41 +87,18 @@ Obtain the key from [TypeSafe Console](https://console.typesafe.ai). Use an offi
 
 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.
+### Connect a local source build
 
-Alternatively, merge this into your Codex `config.toml`, replacing the example paths with your absolute paths:
+After building, configure your host to run `node` with the absolute path to
+`dist/index.js` as its argument. For Codex, replace the npm example's `command`
+with `"node"` and `args` with `["/absolute/path/to/jev-decision-mcp/dist/index.js"]`.
+That path is a placeholder: use your own checkout path. In TOML or JSON, Windows
+paths can use forward slashes, for example `"C:/projects/jev-decision-mcp/dist/index.js"`.
+If `node` is not on the host's `PATH`, use the absolute path to your Node executable.
 
-```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.
+The source build reads the repository's `.env`, so `env_vars` is only needed if
+you supply the key through Codex's environment instead. For interactive local
+development use `npm run dev`. No host configuration is modified by setup or tests.
 
 ## Call the tool
 
@@ -94,7 +121,7 @@ Call `jev_decide` with the JSON in [examples/decision.json](examples/decision.js
 }
 ```
 
-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.
+The response contains `model`, `answers`, and `usage`, both as MCP structured content and JSON text. Jev may round probabilities to two decimal places, so their sum can differ slightly from 1. The server allows the corresponding rounding margin (up to 0.005 per option) and preserves the returned values without normalization. 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.
 
@@ -131,16 +158,36 @@ Built using the `typesafe-ai` skill and official documentation, checked Septembe
 
 ## 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.
+Publishing a stable GitHub release triggers `.github/workflows/publish-npm.yml`.
+The workflow checks that the release tag (`v` plus the package version) matches
+`package.json` and `server.json`, runs the checks, and publishes to npm using
+GitHub OIDC. It requires an npm trusted publisher configured for user
+`amidabuddha`, repository `jev-decision-mcp`, workflow filename `publish-npm.yml`,
+no environment name, and permission for direct `npm publish`. No npm token is needed.
+
+For a new release, update `package.json`, `package-lock.json`, and all version
+fields in `server.json` together, then publish a matching GitHub release from
+that commit. Confirm the **Publish npm** workflow succeeds. Existing versions
+cannot be published again; prereleases are not published by this workflow.
+
+The official MCP Registry uses the separate, manually triggered **Publish MCP
+Registry** workflow. Run it from `main` after the corresponding npm version is
+available. GitHub release creation alone does not confirm either publication.
 
 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
+Clients can launch the published npm package with
+`npx -y jev-decision-mcp@0.1.2`. 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.
+
+## Glama inspection
+
+Glama's build configuration is managed in the listing's Dockerfile admin page.
+Use build steps `npm ci` and `npm run build`, with CMD arguments
+`["node", "dist/index.js"]`. No repository Dockerfile or TypeSafe key is needed
+for inspection: the server starts without credentials and supports MCP
+initialization and `tools/list`. Decision calls still require `TYPESAFE_API_KEY`.

package/dist/schema.js

@@ -56,9 +56,16 @@ export function validateResponse(raw, input) {
             : 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");
+        const values = Object.values(answer.probabilities);
+        const sum = values.reduce((a, b) => a + b, 0);
+        // Jev can return probabilities rounded to two decimals (observed totals
+        // include 0.99). Each rounded entry can contribute at most 0.005 error.
+        // Keep the tighter check for higher-precision responses, and never
+        // normalize the upstream values or accept a distribution with no mass.
+        const roundedToCents = values.every((p) => Math.abs(p * 100 - Math.round(p * 100)) < 1e-9);
+        const tolerance = roundedToCents ? values.length * 0.005 : 0.001;
+        if (sum <= 0 || Math.abs(sum - 1) > tolerance + 1e-12)
+            throw new Error("Probabilities do not sum to one within rounding tolerance");
         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))) {

package/dist/server.js

@@ -2,7 +2,7 @@ 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" });
+    const server = new McpServer({ name: "jev-decision-mcp", version: "0.1.2" });
     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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-decision-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A local MCP server for TypeSafe Jev typed decisions",
   "type": "module",
   "engines": {

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/amidabuddha/jev-decision-mcp",
     "source": "github"
   },
-  "version": "0.1.0",
+  "version": "0.1.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "jev-decision-mcp",
-      "version": "0.1.0",
+      "version": "0.1.2",
       "transport": {
         "type": "stdio"
       },