clef-mcp 0.1.2 → 0.1.4

package/README.md

@@ -26,11 +26,14 @@ Clef does **not** generate prose. It reads a `state` plus a set of typed questio
 # 1. Detect hardware, download the model (~6 GB) + llama.cpp runtime, verify checksum + inference
 npx clef-mcp install
 
-# 2. Run the MCP server (stdio)
+# 2. Register the MCP server + agent skill in your clients (zcode, claude-code, codex, cursor)
+npx clef-mcp setup
+
+# 3. Run the MCP server (stdio)
 npx clef-mcp
 ```
 
-`clef-mcp` (step 2) never downloads anything. If the model is missing, tool calls return a structured `MODEL_NOT_INSTALLED` error with a hint.
+`clef-mcp` (step 3) never downloads anything. If the model is missing, tool calls return a structured `MODEL_NOT_INSTALLED` error with a hint. Steps 1 and 2 can be combined: `npx clef-mcp install --setup`.
 
 ### Register with your MCP client
 
@@ -63,6 +66,18 @@ args = []
 }
 ```
 
+**ZCode** — `~/.zcode/cli/config.json` (user scope; servers auto-connect in new sessions):
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "clef-mcp": { "command": "clef-mcp", "args": [], "type": "stdio" }
+    }
+  }
+}
+```
+
 **Generic MCP client** — any client that speaks MCP over stdio: run `clef-mcp` as the server command.
 
 Ready-made snippets live in [`examples/`](examples/).
@@ -131,11 +146,29 @@ Strictly structured — the server never turns the result into prose:
 
 `state` is treated strictly as **data**: it is never interpreted as instructions for the MCP server itself (see [Security](#security--data-handling)).
 
+## Teach your agent (skill)
+
+The tool schema tells the client *what* `clef_decide` accepts; agents also need to know *when* to reach for it and *how* to frame decisions. The bundled skill covers that: decision patterns (next action / routing / classification / noul / score), batching up to 64 questions into one forward pass, writing mutually exclusive criteria, interpreting distributions (argmax vs flat), thresholds for safety-adjacent calls, and error recovery.
+
+Install it for your agent(s):
+
+```bash
+# automatic (registers the MCP server too)
+clef-mcp setup
+
+# or copy the skill manually
+cp -r skills/clef-decisions ~/.agents/skills/                     # from this repo
+cp -r "$(npm root -g)/clef-mcp/skills/clef-decisions" ~/.agents/skills/  # from the npm package
+```
+
+`~/.agents/skills/` is the shared location for ZCode / Claude Code / Codex-style agents.
+
 ## CLI
 
 ```bash
 clef-mcp              # run the MCP server on stdio (default command)
 clef-mcp install      # detect hardware → download model + runtime → verify checksum → verify inference
+clef-mcp setup        # register the MCP server + agent skill in zcode / claude-code / codex / cursor
 clef-mcp models       # list models/quantizations and install status
 clef-mcp status       # runtime, model, memory summary
 clef-mcp doctor       # full diagnosis (platform, RAM, GPU, binary, model, checksum*, inference, MCP config)
@@ -143,7 +176,7 @@ clef-mcp uninstall    # remove the model (and optionally the managed runtime)
 clef-mcp evals        # run the evaluation dataset against the installed model
 ```
 
-Useful flags: `install --quant Q8_0 --yes --skip-probe`, `doctor --deep` (re-hashes the model file), `uninstall --runtime --yes`.
+Useful flags: `install --quant Q8_0 --yes --skip-probe`, `install --setup` (runs setup right after install), `setup --clients zcode,cursor --no-skill`, `doctor --deep` (re-hashes the model file), `uninstall --runtime --yes`.
 
 ## Configuration (environment variables)
 

package/dist/cli.js

@@ -1,29 +1,15 @@
 #!/usr/bin/env node
-
-// src/clef/errors.ts
-var ClefErrorCode = {
-  MODEL_NOT_INSTALLED: "MODEL_NOT_INSTALLED",
-  MODEL_LOAD_FAILED: "MODEL_LOAD_FAILED",
-  RUNTIME_NOT_FOUND: "RUNTIME_NOT_FOUND",
-  RUNTIME_INIT_FAILED: "RUNTIME_INIT_FAILED",
-  RUNTIME_NOT_SUPPORTED: "RUNTIME_NOT_SUPPORTED",
-  INVALID_INPUT: "INVALID_INPUT",
-  CLEF_INFERENCE_FAILED: "CLEF_INFERENCE_FAILED",
-  UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM",
-  OUT_OF_MEMORY: "OUT_OF_MEMORY",
-  CHECKSUM_MISMATCH: "CHECKSUM_MISMATCH",
-  DOWNLOAD_FAILED: "DOWNLOAD_FAILED"
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
-var ClefError = class extends Error {
-  code;
-  hint;
-  constructor(code, message, hint) {
-    super(message);
-    this.name = "ClefError";
-    this.code = code;
-    this.hint = hint;
-  }
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
 };
+
+// src/clef/errors.ts
 function errorJson(err) {
   if (err instanceof ClefError) {
     return {
@@ -53,12 +39,268 @@ function exitCodeFor(err) {
   }
   return 1;
 }
+var ClefErrorCode, ClefError;
+var init_errors = __esm({
+  "src/clef/errors.ts"() {
+    "use strict";
+    ClefErrorCode = {
+      MODEL_NOT_INSTALLED: "MODEL_NOT_INSTALLED",
+      MODEL_LOAD_FAILED: "MODEL_LOAD_FAILED",
+      RUNTIME_NOT_FOUND: "RUNTIME_NOT_FOUND",
+      RUNTIME_INIT_FAILED: "RUNTIME_INIT_FAILED",
+      RUNTIME_NOT_SUPPORTED: "RUNTIME_NOT_SUPPORTED",
+      INVALID_INPUT: "INVALID_INPUT",
+      CLEF_INFERENCE_FAILED: "CLEF_INFERENCE_FAILED",
+      UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM",
+      OUT_OF_MEMORY: "OUT_OF_MEMORY",
+      CHECKSUM_MISMATCH: "CHECKSUM_MISMATCH",
+      DOWNLOAD_FAILED: "DOWNLOAD_FAILED"
+    };
+    ClefError = class extends Error {
+      code;
+      hint;
+      constructor(code, message, hint) {
+        super(message);
+        this.name = "ClefError";
+        this.code = code;
+        this.hint = hint;
+      }
+    };
+  }
+});
+
+// src/cli/prompt.ts
+import readline from "readline/promises";
+async function confirm(question, yes) {
+  if (yes) return true;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new ClefError(
+      ClefErrorCode.INVALID_INPUT,
+      "Refusing to proceed interactively without a terminal.",
+      "Re-run with --yes to confirm non-interactively."
+    );
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+var init_prompt = __esm({
+  "src/cli/prompt.ts"() {
+    "use strict";
+    init_errors();
+  }
+});
+
+// src/cli/setup.ts
+var setup_exports = {};
+__export(setup_exports, {
+  SERVER_ENTRY: () => SERVER_ENTRY,
+  installSkill: () => installSkill,
+  runSetup: () => runSetup
+});
+import { execFile as execFile4 } from "child_process";
+import fsSync2 from "fs";
+import fsp6 from "fs/promises";
+import os4 from "os";
+import path9 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+function bundledSkillPath() {
+  return fileURLToPath2(new URL("../skills/clef-decisions/SKILL.md", import.meta.url));
+}
+async function mergeJsonServerEntry(file, serverKey, container) {
+  let doc = {};
+  try {
+    doc = JSON.parse(await fsp6.readFile(file, "utf8"));
+  } catch {
+    doc = {};
+  }
+  if (container === "mcp.servers") {
+    const mcp = doc.mcp ?? {};
+    const servers = mcp.servers ?? {};
+    if (servers[serverKey]) return "already-configured";
+    servers[serverKey] = { ...SERVER_ENTRY };
+    mcp.servers = servers;
+    doc.mcp = mcp;
+  } else {
+    const servers = doc.mcpServers ?? {};
+    if (servers[serverKey]) return "already-configured";
+    servers[serverKey] = { command: SERVER_ENTRY.command, args: [...SERVER_ENTRY.args] };
+    doc.mcpServers = servers;
+  }
+  await fsp6.mkdir(path9.dirname(file), { recursive: true });
+  await fsp6.writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
+  return "configured";
+}
+async function setupCodex() {
+  const file = path9.join(HOME(), ".codex", "config.toml");
+  let content = "";
+  try {
+    content = await fsp6.readFile(file, "utf8");
+  } catch {
+    content = "";
+  }
+  if (content.includes("[mcp_servers.clef-mcp]")) {
+    return { client: "codex", status: "already-configured", detail: file };
+  }
+  const next = (content && !content.endsWith("\n") ? content + "\n" : content) + "\n" + CODEX_SECTION;
+  await fsp6.mkdir(path9.dirname(file), { recursive: true });
+  await fsp6.writeFile(file, next, "utf8");
+  return { client: "codex", status: "configured", detail: file };
+}
+async function setupZcode() {
+  const file = path9.join(HOME(), ".zcode", "cli", "config.json");
+  const status = await mergeJsonServerEntry(file, "clef-mcp", "mcp.servers");
+  return { client: "zcode", status, detail: file };
+}
+async function setupCursor() {
+  const file = path9.join(HOME(), ".cursor", "mcp.json");
+  const status = await mergeJsonServerEntry(file, "clef-mcp", "mcpServers");
+  return { client: "cursor", status, detail: file };
+}
+function whichCli(bin) {
+  const dirs = (process.env.PATH ?? "").split(path9.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path9.join(dir, bin);
+    try {
+      fsSync2.accessSync(candidate, fsSync2.constants.X_OK);
+      return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function setupClaudeCode() {
+  const claude = whichCli("claude");
+  if (!claude) {
+    return {
+      client: "claude-code",
+      status: "manual-hint",
+      detail: "claude CLI not found \u2014 run manually: claude mcp add clef-mcp -- clef-mcp"
+    };
+  }
+  const existing = await new Promise((resolve) => {
+    execFile4(claude, ["mcp", "list"], { timeout: 3e4, encoding: "utf8" }, (_err, stdout) => resolve(String(stdout)));
+  });
+  if (existing.includes("clef-mcp")) {
+    return { client: "claude-code", status: "already-configured", detail: "claude mcp list" };
+  }
+  await new Promise((resolve, reject) => {
+    execFile4(
+      claude,
+      ["mcp", "add", "--scope", "user", "clef-mcp", "--", "clef-mcp"],
+      { timeout: 6e4, encoding: "utf8" },
+      (err) => err ? reject(err) : resolve()
+    );
+  });
+  return { client: "claude-code", status: "configured", detail: "claude mcp add --scope user" };
+}
+async function installSkill() {
+  const src = bundledSkillPath();
+  const destDir = path9.join(HOME(), ".agents", "skills", "clef-decisions");
+  const dest = path9.join(destDir, "SKILL.md");
+  let content = "";
+  try {
+    content = await fsp6.readFile(dest, "utf8");
+  } catch {
+  }
+  const incoming = await fsp6.readFile(src, "utf8");
+  if (content === incoming) {
+    return { client: "skill", status: "already-configured", detail: dest };
+  }
+  await fsp6.mkdir(destDir, { recursive: true });
+  await fsp6.writeFile(dest, incoming, "utf8");
+  return { client: "skill", status: "configured", detail: dest };
+}
+function parseClients(raw) {
+  const all = ["zcode", "claude-code", "codex", "cursor"];
+  if (!raw || raw === "all") return all;
+  const wanted = raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  for (const w of wanted) {
+    if (!all.includes(w)) {
+      throw new ClefError(
+        ClefErrorCode.INVALID_INPUT,
+        `Unknown client "${w}".`,
+        `Available: ${all.join(", ")} (or "all")`
+      );
+    }
+  }
+  return wanted;
+}
+async function runSetup(opts) {
+  const wantSkill = opts.skill === true || opts.noSkill !== true;
+  const clients = parseClients(opts.clients);
+  const plan = [...clients, ...wantSkill ? ["skill"] : []];
+  console.log(`Setup will register clef-mcp with: ${plan.join(", ")}
+`);
+  const ok = await confirm("Continue?", opts.yes === true);
+  if (!ok) {
+    console.log("Aborted. Nothing was changed.");
+    return;
+  }
+  const reports = [];
+  for (const client of clients) {
+    try {
+      if (client === "zcode") reports.push(await setupZcode());
+      else if (client === "cursor") reports.push(await setupCursor());
+      else if (client === "codex") reports.push(await setupCodex());
+      else if (client === "claude-code") reports.push(await setupClaudeCode());
+    } catch (err) {
+      reports.push({
+        client,
+        status: "manual-hint",
+        detail: `failed: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+  }
+  if (wantSkill) {
+    try {
+      reports.push(await installSkill());
+    } catch (err) {
+      reports.push({
+        client: "skill",
+        status: "manual-hint",
+        detail: `failed: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+  }
+  console.log("");
+  for (const r of reports) {
+    const mark2 = r.status === "configured" ? "+" : r.status === "already-configured" ? "=" : "!";
+    console.log(`${mark2}  ${r.client.padEnd(12)} ${r.status.padEnd(20)} ${r.detail}`);
+  }
+  console.log("\nDone. Restart your MCP clients (new agent sessions) to pick up the server.");
+}
+var SERVER_ENTRY, HOME, CODEX_SECTION;
+var init_setup = __esm({
+  "src/cli/setup.ts"() {
+    "use strict";
+    init_errors();
+    init_prompt();
+    SERVER_ENTRY = { command: "clef-mcp", args: [], type: "stdio" };
+    HOME = () => os4.homedir();
+    CODEX_SECTION = [
+      "[mcp_servers.clef-mcp]",
+      'command = "clef-mcp"',
+      "args = []",
+      ""
+    ].join("\n");
+  }
+});
+
+// src/cli/index.ts
+init_errors();
 
 // src/mcp/server.ts
+init_errors();
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/clef/systemone.ts
+init_errors();
 function stateToString(state) {
   if (typeof state === "string") return state;
   try {
@@ -369,6 +611,7 @@ function llamaServerName(platform) {
 }
 
 // src/models/registry.ts
+init_errors();
 var GB = 1024 ** 3;
 var CLEF_FLASH = {
   id: "clef-flash",
@@ -516,6 +759,7 @@ function readRuntimeManifest(manifestPath) {
 }
 
 // src/runtime/binary.ts
+init_errors();
 import fs2 from "fs";
 import path4 from "path";
 function existsExecutable(p) {
@@ -571,6 +815,7 @@ function resolveLlamaServerBinary(cfg, deps = {}) {
 }
 
 // src/runtime/llama-cpp.ts
+init_errors();
 import { spawn } from "child_process";
 import net from "net";
 var STDERR_TAIL_LIMIT = 4e3;
@@ -802,6 +1047,7 @@ ${tail}` : ""),
 };
 
 // src/mcp/schema.ts
+init_errors();
 import { z } from "zod";
 function criteriaDescription(limits) {
   return z.string().min(1).max(limits.maxCriteriaDescChars);
@@ -1021,6 +1267,7 @@ function createClefServer(deps = {}) {
 import { Command } from "commander";
 
 // src/cli/doctor.ts
+init_errors();
 import { execFile as execFile2 } from "child_process";
 import os3 from "os";
 import { promisify } from "util";
@@ -1028,6 +1275,7 @@ import fsp2 from "fs/promises";
 import path5 from "path";
 
 // src/models/platform.ts
+init_errors();
 import { execFile } from "child_process";
 import os2 from "os";
 function exec(cmd, args, timeoutMs) {
@@ -1105,6 +1353,7 @@ function formatBytes(bytes) {
 }
 
 // src/runtime/probe.ts
+init_errors();
 import fs3 from "fs/promises";
 async function probeInference(cfg, manifest, log, loadTimeoutMs = 12e4) {
   await fs3.access(manifest.modelPath).catch(() => {
@@ -1315,6 +1564,7 @@ ${failed.length} critical check(s) failed.`
 }
 
 // src/cli/evals.ts
+init_errors();
 import fsp3 from "fs/promises";
 import fsSync from "fs";
 import { fileURLToPath } from "url";
@@ -1424,11 +1674,13 @@ ${passed}/${results.length} passed (${(rate * 100).toFixed(1)}%), required >= ${
 }
 
 // src/models/llama-install.ts
+init_errors();
 import { execFile as execFile3 } from "child_process";
 import fsp5 from "fs/promises";
 import path8 from "path";
 
 // src/models/hf.ts
+init_errors();
 import { createHash as createHash2 } from "crypto";
 import fsp4 from "fs/promises";
 import path7 from "path";
@@ -1726,28 +1978,11 @@ async function removeManagedRuntime(cfg) {
   return true;
 }
 
-// src/cli/prompt.ts
-import readline from "readline/promises";
-async function confirm(question, yes) {
-  if (yes) return true;
-  if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    throw new ClefError(
-      ClefErrorCode.INVALID_INPUT,
-      "Refusing to proceed interactively without a terminal.",
-      "Re-run with --yes to confirm non-interactively."
-    );
-  }
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
-    return answer === "" || answer === "y" || answer === "yes";
-  } finally {
-    rl.close();
-  }
-}
+// src/cli/install.ts
+init_prompt();
 
 // src/version.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.4";
 
 // src/cli/install.ts
 var OS_NAMES = {
@@ -1817,11 +2052,18 @@ Model license: ${spec.licenseId} \u2014 ${spec.licenseUrl}`);
     const probe = await probeInference(config, manifest, log);
     console.log(`  Inference OK (${(probe.latencyMs / 1e3).toFixed(1)}s incl. model load, via ${probe.binarySource} binary)`);
   }
+  if (opts.setup) {
+    const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
+    console.log("");
+    await runSetup2({ yes: opts.yes });
+    return;
+  }
   console.log("\nDone. Start the MCP server with:\n\n  clef-mcp\n");
-  console.log("Then register it with your MCP client, e.g.:\n");
+  console.log("Register it with your agents (or run `clef-mcp setup` to do it automatically):\n");
   console.log("  Claude Code : claude mcp add clef-mcp -- clef-mcp");
   console.log("  Codex       : add [mcp_servers.clef-mcp] to ~/.codex/config.toml (see README)");
-  console.log("  Cursor      : add clef-mcp to .cursor/mcp.json (see README)\n");
+  console.log("  Cursor      : add clef-mcp to .cursor/mcp.json (see README)");
+  console.log("  ZCode       : add clef-mcp to ~/.zcode/cli/config.json (see README)\n");
 }
 
 // src/cli/models-cmd.ts
@@ -1841,7 +2083,11 @@ async function runModels() {
   }
 }
 
+// src/cli/index.ts
+init_setup();
+
 // src/cli/status.ts
+init_errors();
 async function runStatus() {
   const config = loadConfig();
   const info = await detectPlatform();
@@ -1881,7 +2127,9 @@ async function runStatus() {
 }
 
 // src/cli/uninstall.ts
-import fsp6 from "fs/promises";
+init_errors();
+import fsp7 from "fs/promises";
+init_prompt();
 async function runUninstall(opts) {
   const config = loadConfig();
   const spec = getModelSpec(opts.model ?? config.model);
@@ -1905,7 +2153,7 @@ async function runUninstall(opts) {
     return;
   }
   if (target) {
-    await fsp6.rm(target, { recursive: true, force: true });
+    await fsp7.rm(target, { recursive: true, force: true });
     console.log(`Removed: ${target}`);
   }
   if (opts.runtime) {
@@ -1932,13 +2180,20 @@ program.action(async () => {
     handleCliError(err);
   }
 });
-program.command("install").description("Detect the machine, download a Clef model + runtime, verify checksum and inference.").option("--model <id>", "model to install (default: clef-flash)").option("--quant <id>", "quantization override: Q4_K_M | Q8_0 | BF16").option("-y, --yes", "assume yes for all prompts (non-interactive)").option("--skip-runtime", "do not download/verify the llama.cpp runtime").option("--skip-probe", "skip the post-install inference verification").action(async (opts) => {
+program.command("install").description("Detect the machine, download a Clef model + runtime, verify checksum and inference.").option("--model <id>", "model to install (default: clef-flash)").option("--quant <id>", "quantization override: Q4_K_M | Q8_0 | BF16").option("-y, --yes", "assume yes for all prompts (non-interactive)").option("--skip-runtime", "do not download/verify the llama.cpp runtime").option("--skip-probe", "skip the post-install inference verification").option("--setup", "also register the MCP server + agent skill in detected clients (same as running `clef-mcp setup`)").action(async (opts) => {
   try {
     await runInstall(opts);
   } catch (err) {
     handleCliError(err);
   }
 });
+program.command("setup").description("Register the MCP server + agent skill in your clients (zcode, claude-code, codex, cursor).").option("--clients <list>", "comma-separated subset: zcode,claude-code,codex,cursor (default: all)").option("--skill", "install the agent skill (default)").option("--no-skill", "do not touch the agent skill").option("-y, --yes", "assume yes for all prompts (non-interactive)").action(async (opts) => {
+  try {
+    await runSetup(opts);
+  } catch (err) {
+    handleCliError(err);
+  }
+});
 program.command("models").description("List known Clef models, quantizations and install status.").action(async () => {
   try {
     await runModels();