@yugabytedb/meko-mcp 1.0.3

package/lib/clients/claude-code.mjs

@@ -0,0 +1,265 @@
+import { askYesNo } from "../prompt.mjs";
+import {
+  getClaudeCodeSettingsPath,
+  mergeAllowList,
+  mergeSettings,
+  readJsonFile,
+  removeFromAllowList,
+  removeKeys,
+  writeJsonFile,
+} from "../config.mjs";
+import { detectClaude, detectExistingMeko } from "../detect.mjs";
+import { redactKey, run } from "./common.mjs";
+
+const CLAUDE_INSTALL_URL =
+  "https://docs.anthropic.com/en/docs/claude-code/getting-started";
+
+// Hook scripts produced by earlier installer versions that may have had inline
+// MEKO_MCP_URL=... / MEKO_API_KEY=... env assignments baked into the command
+// string. Used by stripLiteralUrlFromHooks to recognize and clean them up.
+const MEKO_HOOK_SCRIPTS = ["session-start.sh", "pre-compact.sh", "session-end.sh"];
+
+// Meko MCP tools to union into `permissions.allow` so Claude Code resolves
+// them without the deferred-tools ToolSearch round-trip (issue #5). The set
+// is intentionally tight — only tools the agent calls proactively per
+// the meko-mcp-tools skill — to avoid bloating every user's settings.
+//
+// NOTE: `permissions.allow` is verified to cover user-prompt bypass. Whether
+// it also bypasses the deferred-tools schema-fetch gate must be re-verified
+// empirically before this flag is considered load-bearing for #5. Tracked
+// as Phase 10.1 in skills/TEST_PLAN.md.
+const MEKO_ALWAYS_AVAILABLE_TOOLS = [
+  "mcp__meko__db_summarize_database",
+  "mcp__meko__memory_add",
+  "mcp__meko__memory_search",
+  "mcp__meko__memory_get_all",
+  "mcp__meko__memory_get_by_id",
+  "mcp__meko__memory_update",
+  "mcp__meko__memory_delete_by_id",
+  "mcp__meko__conversation_create",
+  "mcp__meko__conversation_add_message",
+];
+
+/**
+ * @param {{ getSettingsPath?: () => string }} [options]
+ * @returns {object}
+ */
+export function createClaudeCodeAdapter(options = {}) {
+  const resolveSettingsPath = options.getSettingsPath ?? getClaudeCodeSettingsPath;
+
+  return {
+    id: "claude-code",
+    displayName: "Claude Code",
+    settingsPath(scope, projectRoot) { // eslint-disable-line no-unused-vars
+      return resolveSettingsPath();
+    },
+    async detectPrerequisites({ verbose, log }) {
+      const claude = detectClaude();
+      if (!claude.found) {
+        throw new Error(
+          `Claude Code CLI not found.\nInstall it first: ${CLAUDE_INSTALL_URL}`,
+        );
+      }
+      if (verbose) {
+        log.dim(`  Claude CLI: ${claude.path} (${claude.version})`);
+      }
+    },
+    detectExisting(name) {
+      return detectExistingMeko(name);
+    },
+    removeRegistration(name) {
+      run(`claude mcp remove ${name}`);
+    },
+    registerServer({ name, url, scope, apiKey, dryRun, verbose, log }) {
+      const cmd = this.buildRegisterCommand({ name, url, scope, apiKey });
+      if (dryRun) {
+        log.dim(`  Would run: ${this.buildRegisterDisplayCommand({ name, url, scope, apiKey })}`);
+        return;
+      }
+      const output = this.runRegisterCommand(cmd);
+      if (verbose && output) {
+        const safeOutput = apiKey ? output.replaceAll(apiKey, "<REDACTED>") : output;
+        log.dim(`  ${safeOutput}`);
+      }
+    },
+    buildRegisterCommand({ name, url, scope, apiKey }) {
+      let cmd = `claude mcp add ${name} ${url} --transport http --scope ${scope}`;
+      if (apiKey) {
+        cmd += ` -H "API_KEY: ${apiKey}"`;
+      }
+      return cmd;
+    },
+    buildRegisterDisplayCommand({ name, url, scope, apiKey }) {
+      let displayCmd = `claude mcp add ${name} ${url} --transport http --scope ${scope}`;
+      if (apiKey) {
+        displayCmd += ` -H "API_KEY: ${redactKey(apiKey)}"`;
+      }
+      return displayCmd;
+    },
+    runRegisterCommand(cmd) {
+      return run(cmd);
+    },
+    async maybeConfirmOverwrite({ existingFound, name, yes }) {
+      if (!existingFound) return true;
+      if (yes) return true;
+      return askYesNo(
+        `${name} MCP is already configured. Overwrite?`,
+        false,
+      );
+    },
+    setHookEnvironment({ url, apiKey, dryRun, verbose, log, settingsPath }) {
+      const envPatch = { env: { MEKO_MCP_URL: url } };
+      if (apiKey) envPatch.env.MEKO_API_KEY = apiKey;
+
+      if (dryRun) {
+        log.dim(`  Would set in ${settingsPath}:`);
+        log.dim(`    MEKO_MCP_URL = ${url}`);
+        if (apiKey) {
+          log.dim(`    MEKO_API_KEY = ${redactKey(apiKey)}`);
+        }
+        log.dim(
+          `  Would union ${MEKO_ALWAYS_AVAILABLE_TOOLS.length} Meko tools into permissions.allow`,
+        );
+        return;
+      }
+
+      mergeSettings(settingsPath, envPatch);
+      mergeAllowList(settingsPath, "permissions.allow", MEKO_ALWAYS_AVAILABLE_TOOLS);
+      const migrated = stripLiteralUrlFromHooks(settingsPath);
+      if (verbose) {
+        log.dim(`  Updated ${settingsPath}`);
+        log.dim(`    MEKO_MCP_URL = ${url}`);
+        if (apiKey) {
+          log.dim(`    MEKO_API_KEY = ${redactKey(apiKey)}`);
+        }
+        log.dim(
+          `    permissions.allow += ${MEKO_ALWAYS_AVAILABLE_TOOLS.length} Meko tools`,
+        );
+        if (migrated) {
+          log.dim("    Migrated stale hook command literals to env-based form.");
+        }
+      }
+    },
+    installSkills({ scope, dryRun, verbose, log }) {
+      const marketplaceCmd =
+        `claude plugin marketplace add yugabyte/meko-mcp-server --sparse skills --scope ${scope}`;
+      const pluginCmd = `claude plugin install meko-agent-skills --scope ${scope}`;
+
+      if (dryRun) {
+        log.dim(`  Would run: ${marketplaceCmd}`);
+        log.dim(`  Would run: ${pluginCmd}`);
+        return { marketplace: "dry-run", skills: "dry-run" };
+      }
+
+      let marketplaceStatus = "ok";
+      try {
+        const output = run(marketplaceCmd);
+        if (verbose && output) log.dim(`  ${output}`);
+      } catch (err) {
+        const msg = err.stderr || err.message || "";
+        if (msg.includes("already") || msg.includes("exists")) {
+          marketplaceStatus = "already";
+        } else {
+          marketplaceStatus = "error";
+          log.warn(`Non-critical: ${msg}`);
+        }
+      }
+
+      let skillStatus = "ok";
+      try {
+        const output = run(pluginCmd);
+        if (verbose && output) log.dim(`  ${output}`);
+      } catch (err) {
+        const msg = err.stderr || err.message || "";
+        if (msg.includes("already") || msg.includes("installed")) {
+          skillStatus = "already";
+        } else {
+          skillStatus = "error";
+          log.warn(`Non-critical: ${msg}`);
+        }
+      }
+
+      return { marketplace: marketplaceStatus, skills: skillStatus };
+    },
+    uninstall({ name, settingsPath }) {
+      const results = [];
+      try {
+        run(`claude mcp remove ${name}`);
+        results.push({ key: "mcp", ok: true, message: `MCP server "${name}" removed.` });
+      } catch {
+        results.push({ key: "mcp", ok: false, message: `MCP server "${name}" was not registered (nothing to remove).` });
+      }
+
+      try {
+        removeKeys(settingsPath, ["env.MEKO_MCP_URL", "env.MEKO_API_KEY"]);
+        removeFromAllowList(settingsPath, "permissions.allow", MEKO_ALWAYS_AVAILABLE_TOOLS);
+        results.push({ key: "env", ok: true, message: "Environment variables and Meko allowlist removed from settings." });
+      } catch (err) {
+        results.push({ key: "env", ok: false, message: `Could not update settings: ${err.message}` });
+      }
+
+      try {
+        run("claude plugin uninstall meko-agent-skills");
+        results.push({ key: "skills", ok: true, message: "Skills plugin removed." });
+      } catch {
+        results.push({ key: "skills", ok: false, message: "Skills plugin was not installed (nothing to remove)." });
+      }
+
+      try {
+        run("claude plugin marketplace remove meko-agent-skills");
+        results.push({ key: "marketplace", ok: true, message: "Plugin marketplace entry removed." });
+      } catch {
+        results.push({ key: "marketplace", ok: false, message: "Plugin marketplace entry was not registered (nothing to remove)." });
+      }
+
+      return results;
+    },
+    async validateConfig({ serverName }) {
+      try {
+        const output = run("claude mcp list");
+        const lines = output.split("\n").map((l) => l.trim()).filter(Boolean);
+        const found = lines.some((line) => line.split(":")[0].trim() === serverName);
+        if (found) return { ok: true, message: `Server "${serverName}" is registered.` };
+        return {
+          ok: false,
+          message: `Server "${serverName}" not found in \`claude mcp list\` output. Run the installer again or add it manually.`,
+        };
+      } catch (err) {
+        return { ok: false, message: `Failed to run \`claude mcp list\`: ${err.message}` };
+      }
+    },
+  };
+}
+
+// Rewrites `MEKO_MCP_URL='...' [MEKO_API_KEY='...'] bash "<script>"` hook command
+// strings to `bash "<script>"`, for the three meko hook scripts. Earlier installer
+// versions (cursor.mjs buildScriptCommand) literalized URL+key into the command,
+// which silently shadowed the env block at runtime — see MEKO-20. Runs on every
+// Claude Code install as a one-time migration. Returns true if anything changed.
+export function stripLiteralUrlFromHooks(settingsPath) {
+  const cfg = readJsonFile(settingsPath);
+  if (!cfg?.hooks || typeof cfg.hooks !== "object") return false;
+
+  let changed = false;
+  for (const eventArr of Object.values(cfg.hooks)) {
+    if (!Array.isArray(eventArr)) continue;
+    for (const group of eventArr) {
+      if (!Array.isArray(group?.hooks)) continue;
+      for (const h of group.hooks) {
+        if (typeof h?.command !== "string") continue;
+        if (!MEKO_HOOK_SCRIPTS.some((s) => h.command.includes(s))) continue;
+        const rewritten = h.command.replace(
+          /^\s*(?:MEKO_\w+=(?:'[^']*'|"[^"]*"|\S+)\s+)+/,
+          "",
+        );
+        if (rewritten !== h.command) {
+          h.command = rewritten;
+          changed = true;
+        }
+      }
+    }
+  }
+
+  if (changed) writeJsonFile(settingsPath, cfg);
+  return changed;
+}

package/lib/clients/claude-desktop.mjs

@@ -0,0 +1,256 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  getClaudeDesktopConfigPath,
+  mergeSettings,
+  readJsonFile,
+  removeKeys,
+} from "../config.mjs";
+import { getRepoRoot, run } from "./common.mjs";
+
+/**
+ * Claude Desktop adapter.
+ *
+ * User-scope only. Writes to claude_desktop_config.json via mergeSettings so
+ * existing mcpServers entries (and unrelated preferences) are preserved and a
+ * .bak backup is left behind on every write.
+ *
+ * Claude Desktop does not load MCP servers via HTTP directly — its loader only
+ * spawns stdio subprocesses. We wrap the HTTP URL with the `mcp-remote` stdio
+ * bridge so Desktop treats it as a normal stdio server:
+ *
+ *   "meko": {
+ *     "command": "npx",
+ *     "args": ["-y", "mcp-remote", "<url>", "--transport", "http-only",
+ *              "--header", "API_KEY:${MEKO_API_KEY}"],
+ *     "env": { "MEKO_API_KEY": "<key>" }
+ *   }
+ *
+ * The header uses the `${ENV_VAR}` interpolation form (documented by
+ * mcp-remote) with no space around the colon — some clients mis-parse
+ * space-containing `--header` args.
+ *
+ * installSkills() runs skills/scripts/package-desktop-skill.sh to build the
+ * .skill bundle and prints import instructions. Desktop has no programmatic
+ * skill install API — the user drags the .skill into the app.
+ */
+export function createClaudeDesktopAdapter(options = {}) {
+  const configPathResolver = options.getConfigPath ?? getClaudeDesktopConfigPath;
+  const repoRootResolver = options.getRepoRoot ?? getRepoRoot;
+  const packageRunner = options.runPackageScript ?? defaultRunPackageScript;
+  const npxProber = options.probeNpx ?? defaultProbeNpx;
+
+  return {
+    id: "claude-desktop",
+    displayName: "Claude Desktop",
+    settingsPath() {
+      return configPathResolver();
+    },
+    async detectPrerequisites({ log, verbose } = {}) {
+      const npx = npxProber();
+      if (!npx.found) {
+        throw new Error(
+          "npx (from Node.js) is required so Claude Desktop can launch the " +
+            "mcp-remote stdio bridge. Install Node.js 18+ (which includes npx) " +
+            "and re-run the installer.",
+        );
+      }
+      if (verbose && log?.dim) {
+        log.dim(`  npx: ${npx.path}${npx.version ? ` (${npx.version})` : ""}`);
+      }
+    },
+    detectExisting(name) {
+      const cfg = readJsonFile(configPathResolver());
+      const entry = cfg?.mcpServers?.[name];
+      if (!entry) {
+        return { found: false, status: "" };
+      }
+      // If the existing entry's launcher path looks like a .mcpb extension
+      // install, surface that in the status so the installer prompts more
+      // loudly before overwriting — users who installed via Settings >
+      // Extensions usually don't expect `create-meko-setup` to touch the
+      // same config.
+      const argsJoined = Array.isArray(entry.args) ? entry.args.join(" ") : "";
+      const commandJoined = (entry.command || "") + " " + argsJoined;
+      const fromMcpb =
+        /\bClaude\b[^ ]*\bExtensions\b/i.test(commandJoined) ||
+        /mcp-remote-launcher\.js/.test(commandJoined);
+      return {
+        found: true,
+        status: fromMcpb ? "Configured (via .mcpb extension)" : "Configured",
+      };
+    },
+    removeRegistration(name) {
+      removeKeys(configPathResolver(), [`mcpServers.${name}`]);
+    },
+    registerServer({ name, url, apiKey, dryRun, log }) {
+      const path = configPathResolver();
+      const server = buildMcpRemoteEntry({ url, apiKey });
+
+      if (dryRun) {
+        log.dim(`  Would update ${path}:`);
+        log.dim(`    mcpServers.${name}.command = ${server.command}`);
+        log.dim(`    mcpServers.${name}.args = ${JSON.stringify(server.args)}`);
+        if (apiKey) {
+          log.dim(`    mcpServers.${name}.env.MEKO_API_KEY = <set>`);
+        }
+        return;
+      }
+
+      mergeSettings(path, { mcpServers: { [name]: server } });
+    },
+    setHookEnvironment({ dryRun, log }) {
+      // Claude Desktop has no hook API; the skill carries the proactive-memory
+      // behavior instead. Nothing to write here.
+      if (dryRun) {
+        log.dim("  No hook environment required for Claude Desktop (skill-driven).");
+      }
+    },
+    installSkills({ dryRun, log }) {
+      const repoRoot = repoRootResolver();
+      const script = join(repoRoot, "skills", "scripts", "package-desktop-skill.sh");
+      const output = join(repoRoot, "skills", "meko-mcp-tools-desktop.skill");
+
+      if (dryRun) {
+        log.dim(`  Would run: bash ${script}`);
+        log.dim(`  Would produce: ${output}`);
+        return { marketplace: "skipped", skills: "dry-run", output };
+      }
+
+      if (!existsSync(script)) {
+        log.warn(
+          `Skill packaging script not found at ${script}. ` +
+            "Skipping .skill bundle build; install the skill manually via Claude Desktop settings.",
+        );
+        return { marketplace: "skipped", skills: "script-missing" };
+      }
+
+      try {
+        packageRunner(script);
+      } catch (err) {
+        log.warn(`Skill packaging failed: ${err.message}`);
+        return { marketplace: "skipped", skills: "error", error: err.message };
+      }
+
+      if (!existsSync(output)) {
+        log.warn(`Expected ${output} after packaging but it was not produced.`);
+        return { marketplace: "skipped", skills: "error" };
+      }
+
+      log.info(`Built Meko skill bundle: ${output}`);
+      log.info(
+        "Install it in Claude Desktop: Settings > Extensions > Import skill, " +
+          "or drag the .skill file onto the Claude Desktop window.",
+      );
+      return { marketplace: "skipped", skills: "ok", output };
+    },
+    uninstall({ name }) {
+      const results = [];
+      try {
+        this.removeRegistration(name);
+        results.push({
+          key: "mcp",
+          ok: true,
+          message: `Claude Desktop MCP server "${name}" removed from ${configPathResolver()}.`,
+        });
+      } catch (err) {
+        results.push({
+          key: "mcp",
+          ok: false,
+          message: `Could not remove Claude Desktop MCP server: ${err.message}`,
+        });
+      }
+      results.push({
+        key: "skills",
+        ok: true,
+        message:
+          "Desktop skills are managed via the Desktop UI; " +
+          "remove the Meko skill manually if it was imported.",
+      });
+      return results;
+    },
+    async validateConfig({ serverName }) {
+      const path = configPathResolver();
+      const cfg = readJsonFile(path);
+      const entry = cfg?.mcpServers?.[serverName];
+      if (!entry) {
+        return { ok: false, message: `Server "${serverName}" not found in ${path}.` };
+      }
+
+      // Claude Desktop only accepts stdio entries. A top-level `url` field
+      // (the HTTP shape) is silently rejected by Desktop's loader with a
+      // "not valid MCP server configurations" warning. Reject it here so the
+      // installer catches the regression before the user restarts the app.
+      if (entry.url && !entry.command) {
+        return {
+          ok: false,
+          message:
+            `Server "${serverName}" in ${path} uses the unsupported HTTP shape ` +
+            `({ "url": ... }). Claude Desktop requires a stdio command entry. ` +
+            `Re-run the installer to rewrite it via mcp-remote.`,
+        };
+      }
+      if (typeof entry.command !== "string" || !Array.isArray(entry.args)) {
+        return {
+          ok: false,
+          message:
+            `Server "${serverName}" in ${path} is missing required "command" and "args" fields.`,
+        };
+      }
+
+      return { ok: true, message: `Server "${serverName}" is registered in ${path}.` };
+    },
+  };
+}
+
+/**
+ * Build a Claude Desktop mcpServers entry that wraps an HTTP MCP URL with the
+ * mcp-remote stdio bridge.
+ *
+ * Exported for tests.
+ *
+ * @param {{url: string, apiKey: string|null}} params
+ * @returns {{command: string, args: string[], env?: Record<string,string>}}
+ */
+export function buildMcpRemoteEntry({ url, apiKey }) {
+  const args = ["-y", "mcp-remote", url, "--transport", "http-only"];
+  const entry = { command: "npx", args };
+  if (apiKey) {
+    // `API_KEY:${MEKO_API_KEY}` with no space around the colon — mcp-remote
+    // docs call out a spacing bug in some clients' arg parsing. The header
+    // name matches what the Meko server expects (see capture.js mcpPost).
+    args.push("--header", "API_KEY:${MEKO_API_KEY}");
+    entry.env = { MEKO_API_KEY: apiKey };
+  }
+  return entry;
+}
+
+function defaultRunPackageScript(scriptPath) {
+  if (!statSync(scriptPath).isFile()) {
+    throw new Error(`Not a file: ${scriptPath}`);
+  }
+  execFileSync("bash", [scriptPath], { stdio: ["ignore", "pipe", "pipe"] });
+}
+
+/**
+ * Check whether `npx` is available on PATH.
+ * @returns {{found: boolean, path: string, version: string}}
+ */
+function defaultProbeNpx() {
+  const result = { found: false, path: "", version: "" };
+  try {
+    result.path = run("command -v npx");
+  } catch {
+    return result;
+  }
+  if (!result.path) return result;
+  try {
+    result.version = run("npx --version");
+  } catch {
+    // Path found but version probe failed — still usable.
+  }
+  result.found = true;
+  return result;
+}

package/lib/clients/common.mjs

@@ -0,0 +1,107 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, symlinkSync, cpSync, lstatSync, unlinkSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * @returns {string} Absolute repository root path.
+ */
+export function getRepoRoot() {
+  const libDir = dirname(fileURLToPath(import.meta.url));
+  return resolve(libDir, "..", "..", "..");
+}
+
+/**
+ * Locate the root of installable assets (skills, hook handlers).
+ *
+ * When the installer is published to npm, `prepack` copies the assets into
+ * `installer/assets/`; that path wins because it guarantees the shipped
+ * version of each skill/hook. When running from a source checkout without a
+ * packed `assets/` dir, fall back to the repo's `skills/` directory.
+ *
+ * Layout under both roots mirrors the source tree — callers use
+ * `resolveSkillSource`/`resolveHooksRoot` rather than building paths manually.
+ *
+ * @returns {string} Absolute path to the asset root.
+ */
+export function getAssetRoot() {
+  const libDir = dirname(fileURLToPath(import.meta.url));
+  const packed = resolve(libDir, "..", "..", "assets");
+  if (existsSync(packed)) return packed;
+  return join(getRepoRoot(), "skills");
+}
+
+/**
+ * @param {string} name - skill directory name (e.g. "meko-mcp-tools")
+ * @returns {string} absolute path to the skill source directory
+ */
+export function resolveSkillSource(name) {
+  return join(getAssetRoot(), "skills", name);
+}
+
+/**
+ * @returns {string} absolute path to the hooks-handlers directory
+ */
+export function resolveHooksRoot() {
+  return join(getAssetRoot(), "hooks-handlers");
+}
+
+/**
+ * Run a shell command and return stdout.
+ * @param {string} cmd
+ * @returns {string}
+ */
+export function run(cmd) {
+  return execSync(cmd, { encoding: "utf8", stdio: "pipe" }).trim();
+}
+
+/**
+ * @param {string|null|undefined} apiKey
+ * @returns {string}
+ */
+export function redactKey(apiKey) {
+  return apiKey ? "<set>" : "<not set>";
+}
+
+/**
+ * Safely quote a string for shell usage.
+ * @param {string} value
+ * @returns {string}
+ */
+export function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Create symlink when possible; fallback to copy.
+ * @param {string} source
+ * @param {string} destination
+ * @returns {"symlink"|"copy"}
+ */
+export function symlinkOrCopy(source, destination) {
+  mkdirSync(dirname(destination), { recursive: true });
+  try {
+    symlinkSync(source, destination, "junction");
+    return "symlink";
+  } catch {
+    cpSync(source, destination, { recursive: true });
+    return "copy";
+  }
+}
+
+/**
+ * Remove path if it is a symlink or directory/file.
+ * @param {string} targetPath
+ */
+export function removePath(targetPath) {
+  try {
+    const stat = lstatSync(targetPath);
+    if (stat.isSymbolicLink()) {
+      unlinkSync(targetPath);
+      return;
+    }
+    rmSync(targetPath, { recursive: true, force: true });
+  } catch {
+    // no-op
+  }
+}