clef-mcp 0.1.6 → 0.2.1

package/dist/index.js

@@ -29,6 +29,7 @@ function limitsFromEnv(env = process.env) {
 }
 
 // src/config/env.ts
+var SUPPORTED_RUNTIMES = ["llama-cpp", "mlx"];
 var SUPPORTED_LOG_LEVELS = ["error", "warn", "info", "debug"];
 function parseLogLevel(value) {
   if (!value) return void 0;
@@ -40,19 +41,20 @@ function defaultClefHome() {
 }
 function loadConfig(env = process.env) {
   const logLevel = parseLogLevel(env.CLEF_LOG_LEVEL) ?? "error";
-  const runtime = env.CLEF_RUNTIME?.trim() || "llama-cpp";
-  if (runtime !== "llama-cpp") {
-    throw new Error(`Unsupported CLEF_RUNTIME "${runtime}". Supported: llama-cpp`);
+  const runtimeRaw = (env.CLEF_RUNTIME?.trim() || "llama-cpp").toLowerCase();
+  if (!SUPPORTED_RUNTIMES.includes(runtimeRaw)) {
+    throw new Error(`Unsupported CLEF_RUNTIME "${runtimeRaw}". Supported: ${SUPPORTED_RUNTIMES.join(", ")}`);
   }
+  const runtime = runtimeRaw;
   const llamaBin = env.CLEF_LLAMA_BIN?.trim() || void 0;
   const llamaReleaseTag = env.CLEF_LLAMA_RELEASE_TAG?.trim() || void 0;
   return {
     model: env.CLEF_MODEL?.trim() || "clef-flash",
     clefHome: env.CLEF_HOME?.trim() || defaultClefHome(),
-    runtime: "llama-cpp",
+    runtime,
     logLevel,
-    llamaBin,
-    llamaReleaseTag,
+    llamaBin: runtime === "llama-cpp" ? llamaBin : void 0,
+    llamaReleaseTag: runtime === "llama-cpp" ? llamaReleaseTag : void 0,
     limits: limitsFromEnv(env)
   };
 }
@@ -664,10 +666,10 @@ function isModelManifest(v) {
   const m = v;
   return m.schemaVersion === 1 && typeof m.model === "string" && typeof m.quant === "string" && typeof m.file === "string" && typeof m.modelPath === "string" && typeof m.bytes === "number";
 }
-async function readModelManifest(manifestPath) {
+async function readModelManifest(manifestPath2) {
   let raw;
   try {
-    raw = await fsp.readFile(manifestPath, "utf8");
+    raw = await fsp.readFile(manifestPath2, "utf8");
   } catch {
     return void 0;
   }
@@ -678,9 +680,9 @@ async function readModelManifest(manifestPath) {
     return void 0;
   }
 }
-async function writeModelManifest(manifestPath, manifest) {
-  await fsp.mkdir(path3.dirname(manifestPath), { recursive: true });
-  await fsp.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+async function writeModelManifest(manifestPath2, manifest) {
+  await fsp.mkdir(path3.dirname(manifestPath2), { recursive: true });
+  await fsp.writeFile(manifestPath2, JSON.stringify(manifest, null, 2) + "\n", "utf8");
 }
 async function findInstalledQuant(modelsDir, model, specs) {
   const installed = [];
@@ -733,13 +735,13 @@ function isRuntimeManifest(v) {
   const m = v;
   return m.schemaVersion === 1 && m.kind === "llama-cpp" && typeof m.releaseTag === "string" && typeof m.asset === "string" && typeof m.binaryPath === "string";
 }
-async function writeRuntimeManifest(manifestPath, manifest) {
-  await fsp.mkdir(path3.dirname(manifestPath), { recursive: true });
-  await fsp.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+async function writeRuntimeManifest(manifestPath2, manifest) {
+  await fsp.mkdir(path3.dirname(manifestPath2), { recursive: true });
+  await fsp.writeFile(manifestPath2, JSON.stringify(manifest, null, 2) + "\n", "utf8");
 }
-function readRuntimeManifest(manifestPath) {
+function readRuntimeManifest(manifestPath2) {
   try {
-    const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    const parsed = JSON.parse(fs.readFileSync(manifestPath2, "utf8"));
     return isRuntimeManifest(parsed) ? parsed : void 0;
   } catch {
     return void 0;
@@ -801,6 +803,259 @@ function resolveLlamaServerBinary(cfg, deps = {}) {
 
 // src/runtime/probe.ts
 import fs3 from "fs/promises";
+
+// src/models/mlx-install.ts
+import { execFile } from "child_process";
+import fsSync from "fs";
+import fsp2 from "fs/promises";
+import path5 from "path";
+function manifestPath(clefHome) {
+  return path5.join(pathsFor(clefHome).modelsDir, "clef-flash", "mlx", "manifest.json");
+}
+async function readMlxManifest(clefHome) {
+  let raw;
+  try {
+    raw = await fsp2.readFile(manifestPath(clefHome), "utf8");
+  } catch {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed.kind === "mlx" && typeof parsed.snapshotPath === "string") return parsed;
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function mlxIsInstalled(clefHome) {
+  const manifest = await readMlxManifest(clefHome);
+  if (!manifest) return void 0;
+  try {
+    await fsp2.access(path5.join(manifest.snapshotPath, "clef_mlx.py"));
+    return manifest;
+  } catch {
+    return void 0;
+  }
+}
+function resolveUv(envUv) {
+  if (envUv?.trim()) return envUv.trim();
+  const dirs = (process.env.PATH ?? "").split(path5.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path5.join(dir, "uv");
+    try {
+      fsSync.accessSync(candidate, fsSync.constants.X_OK);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new ClefError(
+    ClefErrorCode.RUNTIME_NOT_FOUND,
+    "uv is required for the MLX runtime but was not found on PATH.",
+    "Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh"
+  );
+}
+
+// src/runtime/mlx.ts
+import { spawn as spawn2 } from "child_process";
+import net2 from "net";
+var STDERR_TAIL_LIMIT2 = 4e3;
+function freePort2() {
+  return new Promise((resolve, reject) => {
+    const srv = net2.createServer();
+    srv.unref();
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      srv.close(() => port > 0 ? resolve(port) : reject(new Error("could not acquire a free port")));
+    });
+  });
+}
+async function fetchWithTimeout2(url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var OOM_PATTERNS2 = ["out of memory", "failed to allocate", "unable to allocate", "not enough memory"];
+var MlxRuntime = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.host = opts.host ?? "127.0.0.1";
+    this.loadTimeoutMs = opts.loadTimeoutMs ?? 18e4;
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 12e4;
+  }
+  opts;
+  proc;
+  resolvedPort;
+  host;
+  loadTimeoutMs;
+  requestTimeoutMs;
+  queue = Promise.resolve();
+  get endpoint() {
+    if (!this.resolvedPort) throw new ClefError(ClefErrorCode.RUNTIME_INIT_FAILED, "Runtime is not started");
+    return `http://${this.host}:${this.resolvedPort}`;
+  }
+  get running() {
+    return this.proc !== void 0 && this.proc.exitCode === null;
+  }
+  async load() {
+    if (this.running) return;
+    const port = this.opts.port ?? await freePort2();
+    this.resolvedPort = port;
+    const args = [
+      "run",
+      "--directory",
+      this.opts.snapshotPath,
+      "--with",
+      "mlx-vlm>=0.7.4,<0.8",
+      "--with",
+      "huggingface_hub",
+      "python",
+      "clef_mlx.py",
+      "serve",
+      "--host",
+      this.host,
+      "--port",
+      String(port)
+    ];
+    this.opts.log?.debug("spawning clef_mlx.py serve", { uv: this.opts.uvBin, snapshot: this.opts.snapshotPath });
+    let proc;
+    try {
+      proc = spawn2(this.opts.uvBin, args, { stdio: ["ignore", "pipe", "pipe"], cwd: this.opts.snapshotPath });
+    } catch (err) {
+      throw new ClefError(
+        ClefErrorCode.RUNTIME_INIT_FAILED,
+        `Failed to start the MLX server: ${err instanceof Error ? err.message : String(err)}`,
+        "Run `clef-mcp doctor` for a full diagnosis."
+      );
+    }
+    this.proc = proc;
+    let stderrTail = "";
+    proc.stderr?.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderrTail = (stderrTail + text).slice(-STDERR_TAIL_LIMIT2);
+      this.opts.log?.debug(text.trimEnd());
+    });
+    proc.stdout?.on("data", (chunk) => {
+      this.opts.log?.debug(chunk.toString().trimEnd());
+    });
+    let rejectOnExit;
+    const exitedBeforeReady = new Promise((_resolve, reject) => {
+      rejectOnExit = reject;
+    });
+    const onEarlyExit = (code, signal) => {
+      const oom = OOM_PATTERNS2.some((p) => stderrTail.toLowerCase().includes(p));
+      const message = `clef_mlx.py exited before becoming ready (code=${code ?? "null"}, signal=${signal ?? "null"})`;
+      const tail = stderrTail.trim();
+      rejectOnExit?.(
+        oom ? new ClefError(ClefErrorCode.OUT_OF_MEMORY, message, "Not enough free memory for this model. Try the llama.cpp runtime with Q4_K_M instead.") : new ClefError(ClefErrorCode.RUNTIME_INIT_FAILED, message + (tail ? `
+stderr tail:
+${tail}` : ""), "Run `clef-mcp doctor` for a full diagnosis.")
+      );
+    };
+    proc.once("exit", onEarlyExit);
+    try {
+      await Promise.race([this.waitUntilReady(), exitedBeforeReady]);
+    } finally {
+      proc.removeListener("exit", onEarlyExit);
+    }
+  }
+  async waitUntilReady() {
+    const deadline = Date.now() + this.loadTimeoutMs;
+    let lastError = "";
+    while (Date.now() < deadline) {
+      if (!this.running) throw new ClefError(ClefErrorCode.RUNTIME_INIT_FAILED, "MLX server is not running");
+      try {
+        const res = await fetchWithTimeout2(`${this.endpoint}/health`, { method: "GET" }, 2e3);
+        if (res.status === 200) return;
+        lastError = `health status ${res.status}`;
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+      }
+      await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new ClefError(
+      ClefErrorCode.MODEL_LOAD_FAILED,
+      `MLX server did not become ready within ${Math.round(this.loadTimeoutMs / 1e3)}s (last health check: ${lastError})`,
+      "The first load can take a while; subsequent loads reuse the snapshot cache."
+    );
+  }
+  async decide(input) {
+    const run = this.queue.then(() => this.decideOnce(input));
+    this.queue = run.catch(() => void 0);
+    return run;
+  }
+  async decideOnce(input) {
+    if (!this.running) {
+      throw new ClefError(ClefErrorCode.RUNTIME_INIT_FAILED, "Runtime is not loaded; call load() first");
+    }
+    let res;
+    try {
+      res = await fetchWithTimeout2(
+        `${this.endpoint}/v1/systemone`,
+        { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(input) },
+        this.requestTimeoutMs
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new ClefError(ClefErrorCode.CLEF_INFERENCE_FAILED, `Inference request failed: ${msg}`);
+    }
+    const bodyText = await res.text();
+    let body = void 0;
+    try {
+      body = bodyText ? JSON.parse(bodyText) : void 0;
+    } catch {
+    }
+    if (!res.ok) {
+      const apiMessage = body && typeof body === "object" && "error" in body ? String(body.error?.message ?? bodyText) : bodyText;
+      throw new ClefError(ClefErrorCode.CLEF_INFERENCE_FAILED, `Inference failed with HTTP ${res.status}: ${apiMessage.slice(0, 2e3)}`);
+    }
+    if (!body || typeof body !== "object") {
+      throw new ClefError(ClefErrorCode.CLEF_INFERENCE_FAILED, `Runtime returned a non-JSON response (HTTP ${res.status})`);
+    }
+    return body;
+  }
+  async health() {
+    if (!this.running) return { status: "unavailable", detail: "not started" };
+    try {
+      const res = await fetchWithTimeout2(`${this.endpoint}/health`, { method: "GET" }, 1500);
+      if (res.status === 200) return { status: "ready" };
+      return { status: "loading", detail: `health status ${res.status}` };
+    } catch (err) {
+      return { status: "unavailable", detail: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  async unload() {
+    const proc = this.proc;
+    if (!proc) return;
+    this.proc = void 0;
+    if (proc.exitCode !== null || proc.signalCode) return;
+    await new Promise((resolve) => {
+      const killTimer = setTimeout(() => {
+        try {
+          proc.kill("SIGKILL");
+        } catch {
+        }
+      }, 3e3);
+      proc.once("exit", () => {
+        clearTimeout(killTimer);
+        resolve();
+      });
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+        clearTimeout(killTimer);
+        resolve();
+      }
+    });
+  }
+};
+
+// src/runtime/probe.ts
 async function probeInference(cfg, manifest, log, loadTimeoutMs = 12e4) {
   await fs3.access(manifest.modelPath).catch(() => {
     throw new ClefError(
@@ -835,8 +1090,8 @@ async function probeInference(cfg, manifest, log, loadTimeoutMs = 12e4) {
 
 // src/models/hf.ts
 import { createHash as createHash2 } from "crypto";
-import fsp2 from "fs/promises";
-import path5 from "path";
+import fsp3 from "fs/promises";
+import path6 from "path";
 var HF_BASE_URL = "https://huggingface.co";
 function resolveUrl(repo, revision, file) {
   return `${HF_BASE_URL}/${repo}/resolve/${revision}/${file}`;
@@ -894,7 +1149,7 @@ async function downloadOnce(url, dest, opts) {
   }
   const total = opts.expectedSize ?? (res.headers.get("content-length") ? Number(res.headers.get("content-length")) : void 0);
   const hash = createHash2("sha256");
-  const handle = await fsp2.open(dest, "w");
+  const handle = await fsp3.open(dest, "w");
   let bytes = 0;
   try {
     for await (const chunk of res.body) {
@@ -909,7 +1164,7 @@ async function downloadOnce(url, dest, opts) {
   }
   const sha256 = hash.digest("hex");
   if (opts.expectedSha256 && sha256 !== opts.expectedSha256) {
-    await fsp2.rm(dest, { force: true });
+    await fsp3.rm(dest, { force: true });
     throw new ClefError(
       ClefErrorCode.CHECKSUM_MISMATCH,
       `Checksum mismatch after download: expected ${opts.expectedSha256}, got ${sha256}`,
@@ -917,7 +1172,7 @@ async function downloadOnce(url, dest, opts) {
     );
   }
   if (opts.expectedSize !== void 0 && bytes !== opts.expectedSize) {
-    await fsp2.rm(dest, { force: true });
+    await fsp3.rm(dest, { force: true });
     throw new ClefError(
       ClefErrorCode.DOWNLOAD_FAILED,
       `Downloaded size mismatch: expected ${opts.expectedSize} bytes, got ${bytes}`
@@ -928,24 +1183,24 @@ async function downloadOnce(url, dest, opts) {
 async function installModel(opts) {
   const { modelSpec, quantSpec } = opts;
   const { modelsDir } = pathsFor(opts.clefHome);
-  const manifestPath = manifestPathFor(modelsDir, modelSpec.id, quantSpec.id);
-  const existing = await readModelManifest(manifestPath);
+  const manifestPath2 = manifestPathFor(modelsDir, modelSpec.id, quantSpec.id);
+  const existing = await readModelManifest(manifestPath2);
   if (existing && (await verifyModelFiles(existing)).ok) {
     opts.log?.debug("model already installed", { model: modelSpec.id, quant: quantSpec.id });
     return { manifest: existing, alreadyInstalled: true };
   }
   const info = await fetchFileInfo(modelSpec.repo, modelSpec.revision, quantSpec.file);
-  const finalPath = path5.join(path5.dirname(manifestPath), quantSpec.file);
-  await fsp2.mkdir(path5.dirname(finalPath), { recursive: true });
-  const tmpPath = path5.join(path5.dirname(finalPath), `.download-${quantSpec.file}`);
-  await fsp2.rm(tmpPath, { force: true });
+  const finalPath = path6.join(path6.dirname(manifestPath2), quantSpec.file);
+  await fsp3.mkdir(path6.dirname(finalPath), { recursive: true });
+  const tmpPath = path6.join(path6.dirname(finalPath), `.download-${quantSpec.file}`);
+  await fsp3.rm(tmpPath, { force: true });
   opts.log?.info("downloading model", { repo: modelSpec.repo, file: quantSpec.file });
   const result = await downloadFile(info.downloadUrl, tmpPath, {
     expectedSha256: info.sha256,
     expectedSize: info.size ?? quantSpec.bytes,
     onProgress: opts.onProgress
   });
-  await fsp2.rename(tmpPath, finalPath);
+  await fsp3.rename(tmpPath, finalPath);
   const manifest = {
     schemaVersion: 1,
     model: modelSpec.id,
@@ -961,15 +1216,15 @@ async function installModel(opts) {
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
     clefMcpVersion: opts.clefMcpVersion
   };
-  await writeModelManifest(manifestPath, manifest);
+  await writeModelManifest(manifestPath2, manifest);
   opts.log?.info("model installed", { model: modelSpec.id, quant: quantSpec.id, sha256: result.sha256 });
   return { manifest, alreadyInstalled: false };
 }
 
 // src/models/llama-install.ts
-import { execFile } from "child_process";
-import fsp3 from "fs/promises";
-import path6 from "path";
+import { execFile as execFile2 } from "child_process";
+import fsp4 from "fs/promises";
+import path7 from "path";
 var GITHUB_API = "https://api.github.com/repos/ggml-org/llama.cpp";
 async function ghJson(url) {
   let res;
@@ -1023,7 +1278,7 @@ function pickAsset(release, platform, arch) {
 }
 function execTar(args, cwd) {
   return new Promise((resolve, reject) => {
-    execFile("tar", args, { cwd, timeout: 3e5 }, (err, _stdout, stderr) => {
+    execFile2("tar", args, { cwd, timeout: 3e5 }, (err, _stdout, stderr) => {
       if (err) reject(new Error(`tar ${args.join(" ")} failed: ${stderr || err.message}`));
       else resolve();
     });
@@ -1036,12 +1291,12 @@ async function findServerBinary(dir, platform) {
     const current = queue.shift();
     let entries;
     try {
-      entries = await fsp3.readdir(current, { withFileTypes: true });
+      entries = await fsp4.readdir(current, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of entries) {
-      const full = path6.join(current, entry.name);
+      const full = path7.join(current, entry.name);
       if (entry.isDirectory()) queue.push(full);
       else if (entry.name === target) return full;
     }
@@ -1052,14 +1307,14 @@ async function findServerBinary(dir, platform) {
   );
 }
 async function extractRelease(archivePath, destDir, platform) {
-  await fsp3.mkdir(destDir, { recursive: true });
+  await fsp4.mkdir(destDir, { recursive: true });
   const args = archivePath.endsWith(".zip") ? ["-xf", archivePath] : ["-xzf", archivePath];
   try {
     await execTar(args, destDir);
   } catch (err) {
     throw new ClefError(
       ClefErrorCode.DOWNLOAD_FAILED,
-      `Could not extract ${path6.basename(archivePath)}: ${err instanceof Error ? err.message : String(err)}`,
+      `Could not extract ${path7.basename(archivePath)}: ${err instanceof Error ? err.message : String(err)}`,
       "Extract the archive manually and point CLEF_LLAMA_BIN at llama-server."
     );
   }
@@ -1069,7 +1324,7 @@ async function ensureLlamaRuntime(cfg, log) {
     const resolved = resolveLlamaServerBinary(cfg);
     if (resolved.source === "managed") {
       const platformDir = llamaRuntimeDir(pathsFor(cfg.clefHome).runtimeDir, process.platform, process.arch);
-      const manifest = readRuntimeManifest(path6.join(platformDir, "runtime-manifest.json"));
+      const manifest = readRuntimeManifest(path7.join(platformDir, "runtime-manifest.json"));
       return { ...resolved, releaseTag: manifest?.releaseTag ?? "unknown", freshInstall: false };
     }
     return { ...resolved, releaseTag: resolved.source, freshInstall: false };
@@ -1101,16 +1356,16 @@ async function downloadManagedLlama(cfg, log) {
   }
   const asset = pickAsset(release, platform, arch);
   log?.info("downloading llama.cpp runtime", { tag: release.tag_name, asset: asset.name });
-  const tagDir = path6.join(platformDir, release.tag_name);
-  await fsp3.mkdir(tagDir, { recursive: true });
-  const tmpArchive = path6.join(platformDir, `.download-${asset.name}`);
-  await fsp3.rm(tmpArchive, { force: true });
+  const tagDir = path7.join(platformDir, release.tag_name);
+  await fsp4.mkdir(tagDir, { recursive: true });
+  const tmpArchive = path7.join(platformDir, `.download-${asset.name}`);
+  await fsp4.rm(tmpArchive, { force: true });
   const result = await downloadFile(asset.browser_download_url, tmpArchive, { expectedSize: asset.size, attempts: 3 });
   await extractRelease(tmpArchive, tagDir, platform);
-  await fsp3.rm(tmpArchive, { force: true });
+  await fsp4.rm(tmpArchive, { force: true });
   const binaryPath = await findServerBinary(tagDir, platform);
-  if (platform !== "win32") await fsp3.chmod(binaryPath, 493);
-  await writeRuntimeManifest(path6.join(platformDir, "runtime-manifest.json"), {
+  if (platform !== "win32") await fsp4.chmod(binaryPath, 493);
+  await writeRuntimeManifest(path7.join(platformDir, "runtime-manifest.json"), {
     schemaVersion: 1,
     kind: "llama-cpp",
     releaseTag: release.tag_name,
@@ -1126,20 +1381,20 @@ async function removeManagedRuntime(cfg) {
   const { runtimeDir } = pathsFor(cfg.clefHome);
   const dir = llamaRuntimeDir(runtimeDir, process.platform, process.arch);
   try {
-    await fsp3.stat(dir);
+    await fsp4.stat(dir);
   } catch {
     return false;
   }
-  await fsp3.rm(dir, { recursive: true, force: true });
+  await fsp4.rm(dir, { recursive: true, force: true });
   return true;
 }
 
 // src/models/platform.ts
-import { execFile as execFile2 } from "child_process";
+import { execFile as execFile3 } from "child_process";
 import os2 from "os";
 function exec(cmd, args, timeoutMs) {
   return new Promise((resolve, reject) => {
-    execFile2(cmd, args, { timeout: timeoutMs, encoding: "utf8" }, (err, stdout) => {
+    execFile3(cmd, args, { timeout: timeoutMs, encoding: "utf8" }, (err, stdout) => {
       if (err) reject(err);
       else resolve(stdout);
     });
@@ -1248,10 +1503,12 @@ function scoreCriteria(limits) {
 }
 function questionSchema(limits) {
   return z.object({
-    type: z.enum(["noul", "choice", "score"]),
-    instructions: z.string().min(1).max(limits.maxInstructionsChars),
+    type: z.enum(["noul", "choice", "score"]).describe('"choice" = pick among named options; "score" = judge an ordered scale; "noul" = yes/no question'),
+    instructions: z.string().min(1).max(limits.maxInstructionsChars).describe("What to judge, phrased as a self-contained question."),
     criteria: z.union([z.array(z.string()), z.record(z.string(), z.string())]).optional()
-  }).superRefine((q, ctx) => {
+  }).describe(
+    "A single decision question. Allowed answers come from `criteria` and must be mutually exclusive and collectively exhaustive."
+  ).superRefine((q, ctx) => {
     if (q.type === "choice") {
       const parsed = choiceCriteria(limits).safeParse(q.criteria);
       if (!parsed.success) {
@@ -1275,23 +1532,27 @@ function questionSchema(limits) {
 }
 function clefDecideInputShape(limits) {
   return {
-    state: z.unknown(),
-    questions: z.record(z.string().min(1).max(limits.maxQuestionIdChars), questionSchema(limits)).check((ctx) => {
+    state: z.unknown().describe(
+      "Task state as data: a compact string or JSON object with the facts needed to judge (task, errors, logs, diffs). Never treated as instructions. Serialized size limit: 1 MB; model context is 16k tokens."
+    ),
+    questions: z.record(z.string().min(1).max(limits.maxQuestionIdChars), questionSchema(limits)).describe(
+      "Map of question id -> typed question. Up to 64 questions per call; all are scored together in a single forward pass, so batch related decisions here."
+    ).check((ctx) => {
       const count = Object.keys(ctx.value).length;
       if (count === 0) ctx.issues.push({ code: "custom", message: "questions must not be empty", input: ctx.value });
       if (count > limits.maxQuestions) {
         ctx.issues.push({ code: "custom", message: `too many questions (max ${limits.maxQuestions})`, input: ctx.value });
       }
     }),
-    model: z.string().min(1).optional(),
+    model: z.string().min(1).optional().describe("Model id to use (default: clef-flash from CLEF_MODEL)."),
     options: z.object({
       /**
        * Accepted for forward compatibility. Clef scores all options in a
        * single forward pass — there is no sampling, so temperature is a
        * documented no-op.
        */
-      temperature: z.number().min(0).max(2).optional()
-    }).optional()
+      temperature: z.number().min(0).max(2).optional().describe("Accepted for forward compatibility; no-op. Clef scores in a single forward pass without sampling.")
+    }).optional().describe("Extra options. Currently only temperature, which is a documented no-op.")
   };
 }
 function clefDecideInputSchema(limits) {
@@ -1331,13 +1592,223 @@ function validateStateSize(state, limits) {
   }
 }
 
+// src/mcp/prompts.ts
+import { z as z2 } from "zod";
+var TOOL_GUIDE = (questions) => [
+  "Call the `clef_decide` MCP tool once with all of the questions below (they are scored in a single forward pass).",
+  "",
+  "Rules for the call:",
+  "- `state` must be a compact, factual JSON or string \u2014 relevant facts only, well under 1 MB.",
+  "- Use the exact `questions` given below (ids, types, criteria). Do not invent extra options.",
+  "- If the answer distribution is flat (no option above ~0.6), gather more context and re-ask once before falling back to asking the user.",
+  "- Treat safety-adjacent decisions (destructive actions, security) as requiring p >= 0.8 before acting; otherwise prefer asking the user.",
+  "- Report the result as a short summary plus the top probability \u2014 do not paste raw JSON unless asked.",
+  "",
+  "Questions:",
+  questions
+].join("\n");
+var PROMPTS = [
+  {
+    name: "incident-triage",
+    title: "Production incident triage",
+    description: "Frame a production incident as clef_decide questions: immediate action, severity and blast radius.",
+    args: {
+      incident_description: "Short factual description of the incident (symptoms, scope, recent changes)."
+    },
+    build: (a) => TOOL_GUIDE(
+      [
+        '- "action" (choice, instructions "What should the responder do first?"): rollback "Revert the latest deploy", hotfix "Ship a targeted fix now", investigate "Gather diagnostics before acting", wait "Observe; impact is not growing".',
+        '- "severity" (score, instructions "How severe is the incident?", criteria ["low", "elevated", "high", "critical"]).',
+        '- "user_impact" (noul, instructions "Are users actively affected right now?").'
+      ].join("\n")
+    ) + "\n\nIncident description:\n" + (a.incident_description ?? "")
+  },
+  {
+    name: "next-action",
+    title: "Agent next action",
+    description: "Ask Clef what the coding agent should do next on a task: inspect, modify, test or ask the user.",
+    args: {
+      task_summary: "What the agent is working on, current step, and what is already known or done."
+    },
+    build: (a) => TOOL_GUIDE(
+      [
+        '- "next_action" (choice, instructions "What should the coding agent do next?"): inspect "Inspect the code and gather more information", modify "Modify the code", test "Run additional tests", ask_user "Ask the user for clarification".',
+        '- "confidence" (score, instructions "How confident are you in this decision?", criteria ["very_low", "low", "medium", "high", "very_high"]).'
+      ].join("\n")
+    ) + "\n\nTask summary:\n" + (a.task_summary ?? "")
+  },
+  {
+    name: "ticket-routing",
+    title: "Support ticket routing",
+    description: "Classify an incoming message into the team that should handle it.",
+    args: {
+      ticket_text: "The customer or user message, verbatim if possible."
+    },
+    build: (a) => TOOL_GUIDE(
+      [
+        '- "department" (choice, instructions "Which team should handle the message?"): billing "Payments, invoices and refunds", technical "Bugs, errors and outages", sales "Pricing and new purchases", other "Anything else".',
+        '- "urgent" (noul, instructions "Does this need a response within the hour?").'
+      ].join("\n")
+    ) + "\n\nTicket text:\n" + (a.ticket_text ?? "")
+  },
+  {
+    name: "security-review",
+    title: "Security sanity check",
+    description: "Ask Clef whether a code snippet, change or setup smells like a security problem.",
+    args: {
+      change_summary: "The code, config or setup to review \u2014 compact but complete enough to judge."
+    },
+    build: (a) => TOOL_GUIDE(
+      [
+        '- "is_vulnerable" (noul, instructions "Does this contain a realistic security vulnerability?").',
+        '- "risk" (score, instructions "How bad is it if this ships as-is?", criteria ["informational", "low", "medium", "high", "critical"]).',
+        '- "first_mitigation" (choice, instructions "What is the first mitigation?"): fix_code "Fix the code before merging", restrict "Restrict access or add guardrails", monitor "Add detection and monitoring", none "No mitigation needed".'
+      ].join("\n") + "\nSafety rule: only act without human review when p(is_vulnerable=false) >= 0.8."
+    ) + "\n\nChange to review:\n" + (a.change_summary ?? "")
+  }
+];
+function registerPrompts(server) {
+  for (const p of PROMPTS) {
+    server.registerPrompt(
+      p.name,
+      {
+        title: p.title,
+        description: p.description,
+        argsSchema: Object.fromEntries(Object.entries(p.args).map(([k, v]) => [k, z2.string().min(1).describe(v)]))
+      },
+      ({ ...args }) => {
+        for (const key of Object.keys(p.args)) {
+          if (typeof args[key] !== "string" || !args[key]) {
+            throw new ClefError(ClefErrorCode.INVALID_INPUT, `Prompt argument "${key}" is required`);
+          }
+        }
+        return {
+          messages: [{ role: "user", content: { type: "text", text: p.build(args) } }]
+        };
+      }
+    );
+  }
+}
+
+// src/mcp/resources.ts
+import fsSync3 from "fs";
+import fsp6 from "fs/promises";
+
+// src/cli/evals.ts
+import fsp5 from "fs/promises";
+import fsSync2 from "fs";
+import { fileURLToPath } from "url";
+import path8 from "path";
+function defaultDatasetPath() {
+  let dir = path8.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const candidate = path8.join(dir, "tests", "evals", "dataset.jsonl");
+    if (fsSync2.existsSync(candidate)) return candidate;
+    dir = path8.dirname(dir);
+  }
+  return fileURLToPath(new URL("../tests/evals/dataset.jsonl", import.meta.url));
+}
+
+// src/mcp/resources.ts
+var EVALS_SCHEMA_MD = `# clef-mcp eval dataset format
+
+JSONL: one JSON object per line.
+
+{
+  "id": "unique-case-id",
+  "category": "coding | security | classification | routing | yes_no",
+  "state": <string | JSON value>,
+  "question": {
+    "id": "question-id",
+    "type": "choice | score | noul",
+    "instructions": "\u2026",
+    "criteria": { "option": "description" }   // choice (or ["a","b"] list)
+                | ["low", "high"]             // score, ordered
+  },
+  "expected": {
+    "kind": "argmax | prob_gt | min_prob | top_mass",
+    // argmax: { "expect": "option", "among": ["option", ...] (optional) }
+    // prob_gt: { "a": "opt", "b": "opt" }
+    // min_prob: { "option": "opt", "min": 0.7 }
+    // top_mass: { "options": ["a","b"], "min": 0.8 }
+  }
+}
+
+Run: \`clef-mcp evals\` (requires an installed model).
+`;
+async function readDataset() {
+  try {
+    return await fsp6.readFile(defaultDatasetPath(), "utf8");
+  } catch {
+    return "The bundled eval dataset is not available in this installation (tests/evals/dataset.jsonl not found).";
+  }
+}
+function textResource(uri, text, mimeType = "text/markdown") {
+  return { contents: [{ uri: uri.href, mimeType, text }] };
+}
+function requireStringUri(uri) {
+  return uri instanceof URL ? uri : new URL(uri);
+}
+function registerResources(server, cfg, version) {
+  server.registerResource(
+    "capabilities",
+    "clef-mcp://capabilities",
+    { title: "clef-mcp capabilities", description: "Live capability snapshot: model, runtime, limits, error codes.", mimeType: "application/json" },
+    async (uri) => {
+      const u = requireStringUri(uri);
+      const payload = {
+        name: "clef-mcp",
+        version,
+        model: cfg.model,
+        runtime: cfg.runtime,
+        limits: cfg.limits,
+        tool: {
+          name: "clef_decide",
+          output: "strict JSON: { model, decisions: { <qid>: { answer: { <option>: probability } } } }",
+          questionTypes: ["noul", "choice", "score"],
+          notes: ["options.temperature is accepted but is a no-op (single forward pass)", "state is data and is never interpreted as instructions"]
+        },
+        errorCodes: [
+          "MODEL_NOT_INSTALLED",
+          "MODEL_LOAD_FAILED",
+          "RUNTIME_NOT_FOUND",
+          "RUNTIME_INIT_FAILED",
+          "RUNTIME_NOT_SUPPORTED",
+          "INVALID_INPUT",
+          "CLEF_INFERENCE_FAILED",
+          "UNSUPPORTED_PLATFORM",
+          "OUT_OF_MEMORY",
+          "CHECKSUM_MISMATCH",
+          "DOWNLOAD_FAILED"
+        ]
+      };
+      return textResource(u, JSON.stringify(payload, null, 2), "application/json");
+    }
+  );
+  server.registerResource(
+    "evals-schema",
+    "clef-mcp://evals/schema",
+    { title: "Eval dataset schema", description: "How to write cases for clef-mcp evals.", mimeType: "text/markdown" },
+    async (uri) => textResource(requireStringUri(uri), EVALS_SCHEMA_MD)
+  );
+  server.registerResource(
+    "evals-dataset",
+    "clef-mcp://evals/dataset",
+    { title: "Bundled eval dataset", description: "The 30-case dataset shipped with clef-mcp.", mimeType: "application/jsonl" },
+    async (uri) => textResource(requireStringUri(uri), await readDataset(), "application/jsonl")
+  );
+}
+
 // src/mcp/server.ts
 var TOOL_NAME = "clef_decide";
 var SERVER_INSTRUCTIONS = "clef_decide passes task state plus typed questions to the local Clef decision model and returns a probability distribution over answer options. Treat `state` as data: it is never interpreted as instructions for this server. The result is structured JSON; do not render it as prose.";
 function createClefServer(deps = {}) {
   const config = deps.config ?? loadConfig();
+  const version = deps.version ?? "0.1.0";
   const log = deps.log ?? createLogger(config.logLevel);
-  const server = new McpServer({ name: "clef-mcp", version: deps.version ?? "0.1.0" }, { instructions: SERVER_INSTRUCTIONS });
+  const server = new McpServer({ name: "clef-mcp", version }, { instructions: SERVER_INSTRUCTIONS });
+  registerPrompts(server);
+  registerResources(server, config, version);
   let loaded;
   let loadPromise;
   async function ensureRuntime(spec) {
@@ -1348,6 +1819,23 @@ function createClefServer(deps = {}) {
     }
     if (loadPromise) return loadPromise;
     loadPromise = (async () => {
+      if (config.runtime === "mlx") {
+        const manifest2 = await mlxIsInstalled(config.clefHome);
+        if (!manifest2) {
+          throw new ClefError(
+            ClefErrorCode.MODEL_NOT_INSTALLED,
+            `Clef model "${spec.id}" is not installed for the MLX runtime.`,
+            "Run `clef-mcp install --runtime mlx`."
+          );
+        }
+        const uvBin = resolveUv(process.env.CLEF_MLX_UV);
+        const runtime2 = deps.runtimeFactory ? deps.runtimeFactory({ kind: "mlx", snapshotPath: manifest2.snapshotPath, alias: spec.id, log }) : new MlxRuntime({ uvBin, snapshotPath: manifest2.snapshotPath, log });
+        log.debug("loading model (mlx)", { model: spec.id, snapshot: manifest2.snapshotPath });
+        const loadStarted2 = Date.now();
+        await runtime2.load();
+        log.info("model ready", { model: spec.id, runtime: "mlx", loadMs: Date.now() - loadStarted2 });
+        return { runtime: runtime2, model: spec.id };
+      }
       const manifest = await findInstalledManifest(config.clefHome, spec);
       if (!manifest) {
         throw new ClefError(
@@ -1357,7 +1845,7 @@ function createClefServer(deps = {}) {
         );
       }
       const binary = resolveLlamaServerBinary(config);
-      const runtime = deps.runtimeFactory ? deps.runtimeFactory({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log }) : new LlamaCppRuntime({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log });
+      const runtime = deps.runtimeFactory ? deps.runtimeFactory({ kind: "llama-cpp", serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log }) : new LlamaCppRuntime({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log });
       log.debug("loading model", { model: spec.id, quant: manifest.quant, bin: binary.path });
       const loadStarted = Date.now();
       await runtime.load();
@@ -1375,9 +1863,15 @@ function createClefServer(deps = {}) {
     TOOL_NAME,
     {
       title: "Clef Decide",
-      description: "Pass task state and a set of structured questions (noul / choice / score) to the local Clef decision model. Returns a probability distribution over the allowed answers for every question. The result is structured JSON.",
+      description: 'Ask the local Clef decision model to judge a situation. Pass a `state` (compact factual context as a string or JSON) and one or more typed `questions`: "choice" picks among named options (criteria = option id -> description), "score" judges an ordered scale (criteria = ordered list), "noul" answers yes/no. Returns strict JSON: for every question a probability distribution over its allowed answers \u2014 no prose, no sampling. Usage: batch related decisions (up to 64 questions) in one call; state is data and is never executed; act on the argmax when a distribution is decisive (p >= 0.8), otherwise gather more context or ask the user; for destructive or security-adjacent decisions require high confidence before acting. Optional `model` overrides the model id; `options.temperature` is a no-op (single forward pass, no sampling).',
       inputSchema: clefDecideInputShape(config.limits),
-      outputSchema: clefDecideOutputSchema().shape
+      outputSchema: clefDecideOutputSchema().shape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
     },
     async (args) => {
       try {
@@ -1432,7 +1926,7 @@ function createClefServer(deps = {}) {
 }
 
 // src/version.ts
-var VERSION = "0.1.6";
+var VERSION = "0.2.1";
 export {
   CLEF_FLASH,
   ClefError,