@lifeaitools/clauth 2.1.1 → 2.10.0

package/cli/mcp/providers/clauth-core-provider.js

@@ -0,0 +1,461 @@
+// cli/mcp/providers/clauth-core-provider.js
+// clauth's own core vault-operation MCP tools, as their own provider file
+// registering against the shared cli/mcp/tool-registry.js. Third and
+// largest file-level split (after terminal-provider.js and
+// ops-provider.js) — 17 registrations: ping, unlock, lock, status,
+// knowledge, list, search, get, inject, enable, disable, test, scrub,
+// set_project, self_check, generate_token, enroll_machine.
+//
+// Unlike the two earlier providers, this group had no single pre-existing
+// service module to lean on — its dependencies span several existing
+// modules (fingerprint.js, api.js, services/service-status.js,
+// recovery.js, conf-path.js, enrollment-script.js) plus two small,
+// genuinely generic local helpers (writeTempSecret, copyToClipboard) that
+// had no callers outside this group (confirmed via grep before moving) and
+// moved alongside it. call_agent stayed in serve.js -- it depends on
+// runCallAgent, a non-trivial serve.js-local function not yet extracted.
+//
+// LOG_FILE is intentionally NOT imported from serve.js: that constant has
+// 67 references there (clauth's own daemon-log path, used well beyond MCP
+// tools) and stays serve.js's own. clauth_generate_token's use of it here
+// is the one place this provider needs it, so the same trivial one-line
+// expression is repeated rather than threading an import for a single
+// constant used once.
+//
+// serve.js imports this file for its side effect (the registerTool() calls
+// below run at import time) — see the `import "../mcp/providers/
+// clauth-core-provider.js";` line in cli/commands/serve.js.
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import crypto from "node:crypto";
+import { execSync } from "node:child_process";
+import Conf from "conf";
+import { mcpResult, mcpError, registerTool, requireMcpWrite } from "../tool-registry.js";
+import { deriveToken } from "../../fingerprint.js";
+import * as api from "../../api.js";
+import { getConfOptions } from "../../conf-path.js";
+import { writeCredentialWithRecovery } from "../../recovery.js";
+import { writeEnrollmentScript } from "../../enrollment-script.js";
+import {
+  ENV_MAP,
+  invalidateServiceStatusCache,
+  sanitizeServiceMetadata,
+  getCachedServiceStatus,
+  searchServices,
+} from "../../services/service-status.js";
+
+const LOG_FILE = path.join(os.tmpdir(), "clauth-serve.log");
+
+function writeTempSecret(service, value) {
+  const filePath = path.join(os.tmpdir(), `.clauth-${service}`);
+  fs.writeFileSync(filePath, value, { mode: 0o600 });
+  setTimeout(() => { try { fs.unlinkSync(filePath); } catch {} }, 30_000);
+  return filePath;
+}
+
+function copyToClipboard(value) {
+  const platform = os.platform();
+  if (platform === "win32") {
+    execSync("clip", { input: value, stdio: ["pipe", "pipe", "pipe"] });
+  } else if (platform === "darwin") {
+    execSync("pbcopy", { input: value, stdio: ["pipe", "pipe", "pipe"] });
+  } else {
+    execSync("xclip -selection clipboard", { input: value, stdio: ["pipe", "pipe", "pipe"] });
+  }
+}
+
+registerTool("clauth_ping", async (args, vault) => {
+  return mcpResult(
+    vault.password
+      ? `unlocked | pid: ${process.pid} | failures: ${vault.failCount}/${vault.MAX_FAILS}`
+      : `locked | pid: ${process.pid} | failures: ${vault.failCount}/${vault.MAX_FAILS}`
+  );
+});
+
+registerTool("clauth_unlock", async (args, vault) => {
+  const pw = args.password;
+  if (!pw) return mcpError("password is required");
+  try {
+    const { token, timestamp } = deriveToken(pw, vault.machineHash);
+    const result = await api.test(pw, vault.machineHash, token, timestamp);
+    if (result.error) return mcpError(`Unlock failed: ${result.error}`);
+    vault.password = pw;
+    return mcpResult("Vault unlocked");
+  } catch (err) {
+    return mcpError(`Unlock failed: ${err.message}`);
+  }
+});
+
+registerTool("clauth_lock", async (args, vault) => {
+  vault.password = null;
+  return mcpResult("Vault locked — password cleared from memory");
+});
+
+registerTool("clauth_status", async (args, vault) => {
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await getCachedServiceStatus({
+      password: vault.password,
+      machineHash: vault.machineHash,
+      token,
+      timestamp,
+      whitelist: vault.whitelist,
+    });
+    if (result.error) return mcpError(result.error);
+    const services = result.services || [];
+    const lines = ["SERVICE                  TYPE         PROJECT                STATUS       KEY    LAST RETRIEVED",
+                    "-------                  ----         -------                ------       ---    --------------"];
+    for (const s of services) {
+      const hasStoredKey = !!(s.has_key || s.vault_key);
+      const status = s.enabled ? "ACTIVE" : (hasStoredKey ? "SUSPENDED" : "NO KEY");
+      const hasKey = hasStoredKey ? "yes" : "—";
+      const lastGet = s.last_retrieved ? new Date(s.last_retrieved).toLocaleDateString() : "never";
+      const proj = (s.project || "—").padEnd(22);
+      lines.push(`${s.name.padEnd(24)} ${(s.key_type || "").padEnd(12)} ${proj} ${status.padEnd(12)} ${hasKey.padEnd(6)} ${lastGet}`);
+    }
+    lines.push(`\nmetadata cache: ${result.cached ? "hit" : "miss"} (${result.cache_ttl_ms}ms TTL)`);
+    return mcpResult(lines.join("\n"));
+  } catch (err) {
+    return mcpError(err.message);
+  }
+});
+
+registerTool("clauth_knowledge", async (args, vault) => {
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await getCachedServiceStatus({
+      password: vault.password,
+      machineHash: vault.machineHash,
+      token,
+      timestamp,
+      project: args.project,
+      whitelist: vault.whitelist,
+      force: args.refresh === true,
+    });
+    if (result.error) return mcpError(result.error);
+    return mcpResult(JSON.stringify({
+      services: (result.services || []).map(sanitizeServiceMetadata),
+      cached: !!result.cached,
+      cache_ttl_ms: result.cache_ttl_ms,
+      contract: {
+        safe_for_agents: true,
+        raw_secret_rule: "Fetch one exact /v/<service> only when a command needs that secret.",
+        bulk_rule: "Do not walk every service name or bulk-retrieve all secrets.",
+      },
+    }, null, 2));
+  } catch (err) {
+    return mcpError(err.message);
+  }
+});
+
+registerTool("clauth_list", async (args, vault) => {
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await getCachedServiceStatus({
+      password: vault.password,
+      machineHash: vault.machineHash,
+      token,
+      timestamp,
+      whitelist: vault.whitelist,
+    });
+    if (result.error) return mcpError(result.error);
+    const services = result.services || [];
+    return mcpResult(services.map(s => s.name).join(", "));
+  } catch (err) {
+    return mcpError(err.message);
+  }
+});
+
+registerTool("clauth_search", async (args, vault) => {
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await searchServices({
+      password: vault.password,
+      machineHash: vault.machineHash,
+      token,
+      timestamp,
+      query: args.query,
+      project: args.project,
+      includeAddresses: args.addresses === true,
+      whitelist: vault.whitelist
+    });
+    if (result.error) return mcpError(result.error);
+    return mcpResult(JSON.stringify(result, null, 2));
+  } catch (err) {
+    return mcpError(err.message);
+  }
+});
+
+registerTool("clauth_get", async (args, vault) => {
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  const service = (args.service || "").toLowerCase();
+  const target = args.target || "file";
+  if (!service) return mcpError("service is required");
+  if (vault.whitelist && !vault.whitelist.includes(service)) {
+    return mcpError(`Service '${service}' not in whitelist`);
+  }
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await api.retrieve(vault.password, vault.machineHash, token, timestamp, service);
+    if (result.error) return mcpError(result.error);
+    const value = typeof result.value === "string" ? result.value : JSON.stringify(result.value);
+
+    if (target === "clipboard") {
+      try {
+        copyToClipboard(value);
+        return mcpResult(`${service} copied to clipboard`);
+      } catch (err) {
+        return mcpError(`Clipboard failed: ${err.message}. Use target 'file' instead.`);
+      }
+    }
+
+    if (target === "stdout") {
+      return {
+        content: [{ type: "text", text: `WARNING: secret in response — will appear in transcript. Use 'file' or 'clipboard' mode instead.\n\n${value}` }],
+        isError: true
+      };
+    }
+
+    // Remote caller (claude.ai via tunnel) — can't read local temp files
+    // Return value inline in MCP response (safe: stays in AI context, not a shell transcript)
+    if (vault.remote) {
+      const envVar = ENV_MAP[service] || service.toUpperCase().replace(/-/g, "_");
+      return mcpResult(`${envVar}=${value}`);
+    }
+
+    // Default: file (local callers)
+    const envVar = ENV_MAP[service] || service.toUpperCase().replace(/-/g, "_");
+    const filePath = writeTempSecret(service, value);
+    return mcpResult(`${service} → ${filePath} (auto-deletes in 30s)\nEnv var: ${envVar}\nUsage: export ${envVar}=$(cat ${filePath.replace(/\\/g, "/")})`);
+  } catch (err) {
+    return mcpError(err.message);
+  }
+});
+
+registerTool("clauth_inject", async (args, vault) => {
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  const services = args.services || [];
+  if (!services.length) return mcpError("services array is required");
+  if (services.length > 5 && args.allow_many !== true) {
+    return mcpError("Refusing to retrieve more than 5 services at once. Use clauth_knowledge for discovery, then request only the exact secrets needed. Pass allow_many=true only for an intentional bulk operation.");
+  }
+
+  const lines = [];
+  const errors = [];
+  for (const svc of services) {
+    const service = svc.toLowerCase();
+    if (vault.whitelist && !vault.whitelist.includes(service)) {
+      errors.push(`${service}: not in whitelist`);
+      continue;
+    }
+    try {
+      const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+      const result = await api.retrieve(vault.password, vault.machineHash, token, timestamp, service);
+      if (result.error) { errors.push(`${service}: ${result.error}`); continue; }
+      const value = typeof result.value === "string" ? result.value : JSON.stringify(result.value);
+      const envVar = ENV_MAP[service] || service.toUpperCase().replace(/-/g, "_");
+      lines.push(`export ${envVar}="${value.replace(/"/g, '\\"')}"`);
+    } catch (err) {
+      errors.push(`${service}: ${err.message}`);
+    }
+  }
+
+  if (!lines.length) return mcpError(`No services retrieved:\n${errors.join("\n")}`);
+
+  // Remote caller — return env vars inline
+  if (vault.remote) {
+    let msg = lines.join("\n");
+    if (errors.length) msg += `\n\nErrors:\n${errors.join("\n")}`;
+    return mcpResult(msg);
+  }
+
+  // Local caller — write temp env file
+  const envFilePath = path.join(os.tmpdir(), ".clauth-env");
+  fs.writeFileSync(envFilePath, `${lines.join("\n")}\n`, { mode: 0o600 });
+  setTimeout(() => { try { fs.unlinkSync(envFilePath); } catch {} }, 30_000);
+
+  let msg = `${lines.length} service(s) → ${envFilePath.replace(/\\/g, "/")} (auto-deletes in 30s)\nUsage: source ${envFilePath.replace(/\\/g, "/")}`;
+  if (errors.length) msg += `\n\nErrors:\n${errors.join("\n")}`;
+  return mcpResult(msg);
+});
+
+registerTool("clauth_enable", async (args, vault) => {
+  const writeError = requireMcpWrite(vault);
+  if (writeError) return writeError;
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  const service = (args.service || "").toLowerCase();
+  if (!service) return mcpError("service is required");
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await api.enable(vault.password, vault.machineHash, token, timestamp, service, true);
+    if (result.error) return mcpError(result.error);
+    invalidateServiceStatusCache(vault.machineHash);
+    return mcpResult(`${service} enabled`);
+  } catch (err) {
+    return mcpError(err.message);
+  }
+});
+
+registerTool("clauth_disable", async (args, vault) => {
+  const writeError = requireMcpWrite(vault);
+  if (writeError) return writeError;
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  const service = (args.service || "").toLowerCase();
+  if (!service) return mcpError("service is required");
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await api.enable(vault.password, vault.machineHash, token, timestamp, service, false);
+    if (result.error) return mcpError(result.error);
+    invalidateServiceStatusCache(vault.machineHash);
+    return mcpResult(`${service} disabled`);
+  } catch (err) {
+    return mcpError(err.message);
+  }
+});
+
+registerTool("clauth_test", async (args, vault) => {
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await api.test(vault.password, vault.machineHash, token, timestamp);
+    if (result.error) return mcpError(`FAIL: ${result.error}`);
+    return mcpResult(`PASS — machine: ${vault.machineHash.slice(0, 16)}... | window: ${new Date(result.timestamp).toISOString()}`);
+  } catch (err) {
+    return mcpError(`FAIL: ${err.message}`);
+  }
+});
+
+registerTool("clauth_scrub", async (args, vault) => {
+  const target = args.target || "latest";
+  try {
+    const { runScrub: doScrub } = await import("../../commands/scrub.js");
+    // runScrub writes to stdout via chalk — capture isn't clean in MCP mode.
+    // Call it and trust it works; report success.
+    await doScrub(target === "all" ? "all" : undefined, {});
+    return mcpResult(`Scrub complete (target: ${target})`);
+  } catch (err) {
+    return mcpError(`Scrub failed: ${err.message}`);
+  }
+});
+
+registerTool("clauth_set_project", async (args, vault) => {
+  const writeError = requireMcpWrite(vault);
+  if (writeError) return writeError;
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  const service = (args.service || "").toLowerCase();
+  const project = args.project;
+  if (!service) return mcpError("service is required");
+  if (project === undefined) return mcpError("project is required (empty string to clear)");
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await api.updateService(vault.password, vault.machineHash, token, timestamp, service, { project: project || "" });
+    if (result.error) return mcpError(result.error);
+    invalidateServiceStatusCache(vault.machineHash);
+    return mcpResult(project ? `${service} → project: ${project}` : `${service} → project cleared`);
+  } catch (err) {
+    return mcpError(err.message);
+  }
+});
+
+registerTool("clauth_self_check", async (args, vault) => {
+  // Test connectivity via the Cloudflare tunnel and/or localhost daemon
+  const tunnelUrl = vault.tunnelUrl;
+  const results = [];
+
+  // Check localhost daemon
+  try {
+    const r = await fetch("http://127.0.0.1:52437/ping", { signal: AbortSignal.timeout(3000) });
+    const data = await r.json();
+    results.push(`Local daemon: PASS (${data.locked ? "locked" : "unlocked"}, failures: ${data.failures ?? 0})`);
+  } catch (err) {
+    results.push(`Local daemon: FAIL — http://127.0.0.1:52437 not reachable (${err.message})`);
+  }
+
+  // Check tunnel
+  if (tunnelUrl) {
+    try {
+      const r = await fetch(`${tunnelUrl}/ping`, { signal: AbortSignal.timeout(5000) });
+      const data = await r.json();
+      results.push(`Tunnel: PASS — ${tunnelUrl} reachable (${data.locked ? "locked" : "unlocked"})`);
+      results.push(`claude.ai SSE endpoint: ${tunnelUrl}/sse`);
+      results.push(`claude.ai MCP endpoint: ${tunnelUrl}/mcp`);
+    } catch (err) {
+      results.push(`Tunnel: FAIL — ${tunnelUrl} not reachable (${err.message})`);
+      results.push("claude.ai MCP connector will not work until tunnel is restored.");
+      results.push("Fix: clauth serve start --tunnel clauth.prtrust.fund");
+    }
+  } else {
+    results.push("Tunnel: NOT RUNNING — claude.ai connector requires the tunnel.");
+    results.push("Start with: clauth serve start --tunnel clauth.prtrust.fund");
+  }
+
+  return mcpResult(results.join("\n"));
+});
+
+registerTool("clauth_generate_token", async (args, vault) => {
+  const writeError = requireMcpWrite(vault);
+  if (writeError) return writeError;
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  const service = (args.service || "").trim().toLowerCase();
+  const prefix = args.prefix || "";
+  if (!service) return mcpError("service name is required");
+  try {
+    const randomHex = crypto.randomBytes(32).toString("hex");
+    const generatedToken = `${prefix}${randomHex}`;
+    const { result } = await writeCredentialWithRecovery({
+      password: vault.password,
+      machineHash: vault.machineHash,
+      service,
+      value: generatedToken,
+      logFile: LOG_FILE,
+      normalize: false,
+    });
+    if (result.error) return mcpError(result.error);
+    invalidateServiceStatusCache(vault.machineHash);
+    return mcpResult(`Token generated and stored under "${service}"`);
+  } catch (err) {
+    return mcpError(`generate_token failed: ${err.message}`);
+  }
+});
+
+registerTool("clauth_enroll_machine", async (args, vault) => {
+  const writeError = requireMcpWrite(vault);
+  if (writeError) return writeError;
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  try {
+    const { token, timestamp } = deriveToken(vault.password, vault.machineHash);
+    const result = await api.createEnrollment(
+      vault.password,
+      vault.machineHash,
+      token,
+      timestamp,
+      args.label,
+      Number(args.ttl_minutes || 60),
+      args.install_id
+    );
+    if (result.error) return mcpError(result.error);
+    const localConfig = new Conf(getConfOptions());
+    const supabaseUrl = localConfig.get("supabase_url") || process.env.CLAUTH_SUPABASE_URL || "";
+    const anonKey = localConfig.get("supabase_anon_key") || process.env.CLAUTH_SUPABASE_ANON_KEY || "";
+    const scriptPath = writeEnrollmentScript({
+      supabaseUrl,
+      anonKey,
+      enrollmentCode: result.enrollment_code,
+      label: args.label,
+    });
+    return mcpResult(JSON.stringify({
+      enrollment_code: result.enrollment_code,
+      install_id: result.install_id,
+      expires_at: result.expires_at,
+      script_path: scriptPath,
+      new_computer_steps: [`Run ${scriptPath} on the new computer. It installs clauth, enrolls with this one-time code, installs startup, then deletes itself.`]
+    }, null, 2));
+  } catch (err) {
+    return mcpError(`enroll_machine failed: ${err.message}`);
+  }
+});

package/cli/mcp/providers/ops-provider.js

@@ -0,0 +1,42 @@
+// cli/mcp/providers/ops-provider.js
+// The clauth_ops_* MCP tools (Vultr deployment-control passthrough), as
+// their own provider file registering against the shared
+// cli/mcp/tool-registry.js. Second file-level split (after
+// terminal-provider.js) — chosen next because callOpsFromMcp's only two
+// dependencies (vaultRetrieveValue, requestOps) already live in their own
+// clean modules, and callOpsFromMcp itself is used by nothing outside these
+// 7 registrations (confirmed via grep before moving it), so it's safe to
+// move alongside them rather than keep shared.
+//
+// serve.js imports this file for its side effect (the registerTool() calls
+// below run at import time) — see the `import "../mcp/providers/
+// ops-provider.js";` line in cli/commands/serve.js.
+import { mcpResult, mcpError, registerTool } from "../tool-registry.js";
+import { vaultRetrieveValue } from "../../services/vault-read.js";
+import { requestOps } from "../../commands/ops.js";
+
+async function callOpsFromMcp(vault, method, requestPath, body, { write = false } = {}) {
+  if (write && !vault.writeEnabled) return mcpError("MCP write tools are disabled by default. Launch clauth with CLAUTH_MCP_WRITE=1 for an explicit write-capable session.");
+  if (!vault.password) return mcpError("Vault is locked — call clauth_unlock first");
+  const endpoint = process.env.CLAUTH_OPS_APPROVED_ORIGIN;
+  if (!endpoint) return mcpError("service_not_available");
+  try {
+    const url = new URL(endpoint);
+    if (url.protocol !== "https:") return mcpError("service_not_available");
+    const service = process.env.CLAUTH_OPS_TOKEN_SERVICE || "vultr-ops-api-token";
+    const credential = await vaultRetrieveValue(vault, service);
+    if (credential.error || !credential.value) return mcpError("service_not_available");
+    const payload = await requestOps({ endpoint: url.toString().replace(/\/$/, ""), token: String(credential.value), method, path: requestPath, body });
+    return mcpResult(JSON.stringify(payload, null, 2));
+  } catch {
+    return mcpError("service_not_available");
+  }
+}
+
+registerTool("clauth_ops_catalog", async (args, vault) => callOpsFromMcp(vault, "GET", "/v1/ops/catalog"));
+registerTool("clauth_ops_processes", async (args, vault) => callOpsFromMcp(vault, "GET", "/v1/ops/processes"));
+registerTool("clauth_ops_describe", async (args, vault) => callOpsFromMcp(vault, "GET", `/v1/ops/processes/${encodeURIComponent(args.application || "")}`));
+registerTool("clauth_ops_deploy", async (args, vault) => callOpsFromMcp(vault, "POST", "/v1/ops/deployments", { application: args.application, ...(args.ref ? { ref: args.ref } : {}) }, { write: true }));
+registerTool("clauth_ops_promote", async (args, vault) => callOpsFromMcp(vault, "POST", "/v1/ops/promotions", { application_uuid: args.application_uuid }, { write: true }));
+registerTool("clauth_ops_job", async (args, vault) => callOpsFromMcp(vault, "GET", `/v1/ops/jobs/${encodeURIComponent(args.job_id || "")}`));
+registerTool("clauth_ops_run", async (args, vault) => callOpsFromMcp(vault, "POST", "/v1/ops/operations", { operation: args.operation, input: args.input && typeof args.input === "object" ? args.input : {} }, { write: true }));

package/cli/mcp/providers/terminal-provider.js

@@ -0,0 +1,81 @@
+// cli/mcp/providers/terminal-provider.js
+// The terminal-session + channel-event MCP tools, as their own provider file
+// registering against the shared cli/mcp/tool-registry.js — the first true
+// file-level split of what was, until now, one large registerTool(...) block
+// living entirely inside cli/commands/serve.js. Chosen as the first slice to
+// move because every dependency it needs (startTerminalSession et al.,
+// channelEvents) already lives in its own clean service module — nothing
+// here reaches back into serve.js-local state, unlike clauth_*'s vault
+// operations or call_agent's runCallAgent (still serve.js-local, deferred).
+//
+// serve.js imports this file for its side effect (the registerTool() calls
+// below run at import time) — see the `import "../mcp/providers/
+// terminal-provider.js";` line in cli/commands/serve.js.
+import path from "node:path";
+import { mcpResult, mcpError, registerTool } from "../tool-registry.js";
+import { channelEvents, defaultTerminalCwd } from "../../services/terminal-registry.js";
+import { startTerminalSession, listTerminalSessions, stopTerminalSession } from "../../services/terminal-sessions.js";
+import { sendTerminalMessage, recvTerminalResponse } from "../../services/terminal-dispatch.js";
+import { showTerminalSession } from "../../services/terminal-window.js";
+
+registerTool("terminal_start", async (args, vault) => {
+  const { name, knowledge_tier, context_md, use_warm, cwd: requestedCwd } = args;
+  if (!name) return mcpError("name required");
+  const cwd = requestedCwd ? path.resolve(String(requestedCwd)) : defaultTerminalCwd();
+  const result = startTerminalSession(name, knowledge_tier || 'db_only', context_md || null, cwd, use_warm === true);
+  if (result.error) return mcpError(`${result.error}: ${result.message}`);
+  return mcpResult(JSON.stringify(result));
+});
+
+registerTool("terminal_send", async (args, vault) => {
+  const { session_id, message } = args;
+  if (!session_id || !message) return mcpError("session_id and message required");
+  const result = sendTerminalMessage(session_id, message);
+  if (result.error) return mcpError(`${result.error}: ${result.message}`);
+  return mcpResult(JSON.stringify(result));
+});
+
+registerTool("terminal_list", async (args, vault) => {
+  return mcpResult(JSON.stringify(listTerminalSessions()));
+});
+
+registerTool("terminal_show", async (args, vault) => {
+  const { session_id } = args;
+  if (!session_id) return mcpError("session_id required");
+  const result = showTerminalSession(session_id);
+  if (result.error) return mcpError(`${result.error}: ${result.message}`);
+  return mcpResult(JSON.stringify(result));
+});
+
+registerTool("terminal_recv", async (args, vault) => {
+  const { session_id } = args;
+  if (!session_id) return mcpError("session_id required");
+  const result = recvTerminalResponse(session_id);
+  if (result.error) return mcpError(`${result.error}: ${result.message}`);
+  return mcpResult(JSON.stringify(result));
+});
+
+registerTool("terminal_stop", async (args, vault) => {
+  const { session_id } = args;
+  if (!session_id) return mcpError("session_id required");
+  const result = stopTerminalSession(session_id);
+  if (result.error) return mcpError(`${result.error}: ${result.message}`);
+  return mcpResult(JSON.stringify(result));
+});
+
+registerTool("channel_list", async (args, vault) => {
+  const { since, limit } = args || {};
+  let events = channelEvents.slice();
+  if (since) {
+    const cutoff = new Date(since).getTime();
+    events = events.filter((e) => new Date(e.created_at).getTime() > cutoff);
+  }
+  events = events.slice(-(limit ? Math.min(Number(limit), 100) : 50));
+  return mcpResult(JSON.stringify({ events, count: events.length }));
+});
+
+registerTool("channel_clear", async (args, vault) => {
+  const cleared = channelEvents.length;
+  channelEvents.length = 0;
+  return mcpResult(JSON.stringify({ cleared }));
+});

package/cli/mcp/tool-registry.js

@@ -0,0 +1,48 @@
+// cli/mcp/tool-registry.js
+// The shared interface every MCP tool provider registers against. Extracted
+// out of cli/commands/serve.js so a provider can be its own file, importing
+// this module, rather than every tool having to live inside serve.js itself
+// (the same Dependency Inversion fix as the frontend's ClauthPanelRegistry
+// (cli/dashboard/panels/panel-registry.js): serve.js and every provider now
+// depend on THIS shared abstraction, not on each other directly).
+//
+// mcpResult/mcpError are generic MCP response shapers, not clauth-specific —
+// any provider needs them, so they live here rather than being duplicated
+// per file. registerTool/hasRegisteredTool/callRegisteredTool are the
+// registry itself (register once, dispatch by lookup — Open/Closed: a new
+// tool means one registerTool() call, never editing a central switch).
+// requireMcpWrite is likewise tool-agnostic (checks vault.writeEnabled,
+// nothing else) so it lives here too rather than being re-implemented by
+// every provider that gates a write tool.
+
+const mcpToolHandlers = new Map();
+
+export function mcpResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+export function mcpError(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+export function registerTool(name, handler) {
+  if (mcpToolHandlers.has(name)) {
+    throw new Error(`MCP tool "${name}" already registered`);
+  }
+  mcpToolHandlers.set(name, handler);
+}
+
+export function hasRegisteredTool(name) {
+  return mcpToolHandlers.has(name);
+}
+
+export function callRegisteredTool(name, args, vault) {
+  return mcpToolHandlers.get(name)(args, vault);
+}
+
+// Takes vault explicitly (not a closure) so any provider's handler can call
+// it with whichever vault it was itself given.
+export function requireMcpWrite(vault) {
+  if (vault.writeEnabled) return null;
+  return mcpError("MCP write tools are disabled by default. Launch clauth with CLAUTH_MCP_WRITE=1 for an explicit write-capable session.");
+}