@dsh-jev/mcp 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @dsh-jev/mcp
+
+MCP server (stdio) exposing the jev System One primitives (`choice` / `score`
+/ `noul`) from `@dsh-jev/core` as MCP tools. Published as
+`@dsh-jev/mcp` (bin: `dsh-jev-mcp`). Every tool degrades gracefully:
+when the jev API is unreachable, timed out, or malformed, the tool still
+returns the caller-supplied fallback and clearly marks `jev: degraded (reason)`.
+
+## Tools
+
+| Tool | Input | Behavior |
+| --- | --- | --- |
+| `jev_choice` | `question`, `options[]`, `fallbackPick?` | Picks one option; falls back to `fallbackPick` (default: first option). |
+| `jev_score` | `subject`, `criteria[]`, `fallbackScore?` | One [0,1] score per criterion; falls back to a neutral score (default 0.5). |
+| `jev_noul` | `prompt`, `fallbackText?` | Unconstrained reflection; falls back to given/empty text. |
+
+Auth: set `JEV_API_KEY` in the server process environment (Bearer token).
+
+## dsh wiring (`cordis.patch.yml`)
+
+⚠️ New plugin instances MUST be declared under `- insert:` — a top-level
+`- id:` only patches entries already present in the composed tree and is
+silently dropped when the id does not exist.
+
+Add to the target profile's `cordis.patch.yml` (e.g.
+`~/.config/dsh/profiles/<name>/cordis.patch.yml`, or its `.tmpl` source, then
+`chezmoi apply`):
+
+```yaml
+- insert:
+    - id: dsh-jev-mcp
+      config:
+        command:
+          # stdio command must be an absolute path in GUI/launchd contexts
+          # (no fnm on PATH there). Adjust to your node location:
+          command: /Users/you/.local/share/fnm/aliases/default/bin/node
+          args:
+            - /Users/you/workspace/opensource/dsh-jev/packages/jev-mcp/dist/index.js
+          env:
+            JEV_API_KEY: ${JEV_API_KEY}
+```
+
+> Do not hardcode your macOS username in public docs/configs — use chezmoi
+> `{{ .chezmooi.homeDir }}` templating (source `.tmpl`) for real deployments.
+
+Verify the composed tree picks it up:
+
+```sh
+dsh --profile <name> --dump-config | grep -A5 dsh-jev-mcp
+# and confirm no `patch: entry "dsh-jev-mcp" not found` warning in the header
+```
+
+Remember `--dump-config` only validates composition; a real boot of the
+profile is required to verify the plugin imports cleanly.
+
+## Build & run
+
+```sh
+pnpm install && pnpm build
+node dist/index.js   # speaks MCP over stdio
+```

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * @dsh-jev/mcp — MCP stdio server wrapping @dsh-jev/core.
+ *
+ * Tools (all degrade, never error the tool call, when System One is unreachable):
+ *   - jev_choice: pick one of N options
+ *   - jev_score:  score a subject against criteria
+ *   - jev_noul:   unconstrained "noul" reflection
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * @dsh-jev/mcp — MCP stdio server wrapping @dsh-jev/core.
+ *
+ * Tools (all degrade, never error the tool call, when System One is unreachable):
+ *   - jev_choice: pick one of N options
+ *   - jev_score:  score a subject against criteria
+ *   - jev_noul:   unconstrained "noul" reflection
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { createJevClient } from '@dsh-jev/core';
+const client = createJevClient();
+const server = new McpServer({ name: 'dsh-jev-mcp', version: '0.1.0' });
+function report(out) {
+    const status = out.ok ? 'jev: ok' : `jev: degraded (${out.error})`;
+    return { content: [{ type: 'text', text: `${status}\n${JSON.stringify(out.value, null, 2)}` }] };
+}
+server.tool('jev_choice', 'Pick one option for a decision via jev System One. Degrades to fallbackPick on failure.', {
+    question: z.string().describe('The decision question'),
+    options: z.array(z.string()).min(1).describe('Candidate options'),
+    fallbackPick: z.string().optional().describe('Option to use if jev is unavailable (default: first option)'),
+}, async ({ question, options, fallbackPick }) => {
+    const fbIndex = Math.max(0, options.indexOf(fallbackPick ?? options[0]));
+    const out = await client.choice({ question, options }, { pickedIndex: fbIndex, picked: options[fbIndex] });
+    return report(out);
+});
+server.tool('jev_score', 'Score a subject against named criteria via jev System One (each score in [0,1]).', {
+    subject: z.string(),
+    criteria: z.array(z.string()).min(1),
+    fallbackScore: z.number().min(0).max(1).optional().describe('Neutral score used on failure (default 0.5)'),
+}, async ({ subject, criteria, fallbackScore }) => {
+    const fb = fallbackScore ?? 0.5;
+    const out = await client.score({ subject, criteria }, { scores: criteria.map(() => fb) });
+    return report(out);
+});
+server.tool('jev_noul', 'Unconstrained jev "noul" reflection on a prompt.', {
+    prompt: z.string(),
+    fallbackText: z.string().optional().describe('Text used if jev is unavailable (default: empty)'),
+}, async ({ prompt, fallbackText }) => {
+    const out = await client.noul({ prompt }, { text: fallbackText ?? '' });
+    return report(out);
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@dsh-jev/mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing jev System One choice/score/noul tools to dsh (DeepSeek Harness)",
+  "type": "module",
+  "bin": {
+    "dsh-jev-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@dsh-jev/core": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "license": "MIT"
+}