@yugabytedb/meko-mcp 1.0.3

package/lib/detect.mjs

@@ -0,0 +1,125 @@
+/**
+ * detect.mjs - Detection helpers for Claude CLI and existing Meko config.
+ *
+ * Uses child_process.execSync so the installer can fail fast if
+ * prerequisites are missing. Every function is safe to call on any
+ * platform - failures are caught and returned as structured results.
+ * Zero external dependencies - Node.js built-ins only.
+ */
+
+import { execSync } from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a shell command and return its trimmed stdout.
+ * Returns `null` if the command fails for any reason.
+ *
+ * @param {string} cmd
+ * @returns {string | null}
+ */
+function run(cmd) {
+  try {
+    return execSync(cmd, {
+      encoding: "utf8",
+      // Suppress stderr so failed commands don't litter the terminal.
+      stdio: ["pipe", "pipe", "pipe"],
+      // Short timeout to avoid hanging on unexpected interactive prompts.
+      timeout: 10_000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// detectClaude
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether the Claude CLI is installed and reachable on the PATH.
+ *
+ * @returns {{ found: boolean, version: string, path: string }}
+ *   `found`   - true when the `claude` binary exists and responds to --version.
+ *   `version` - the version string reported by `claude --version`, or "".
+ *   `path`    - the absolute path to the binary, or "".
+ */
+export function detectClaude() {
+  const result = { found: false, version: "", path: "" };
+
+  // Locate the binary.
+  const binPath = run("which claude");
+  if (!binPath) return result;
+
+  result.path = binPath;
+
+  // Retrieve version - `claude --version` typically outputs something like
+  // "1.0.12 (Claude Code)" or just a semver string.
+  const versionOutput = run("claude --version");
+  if (!versionOutput) return result;
+
+  result.version = versionOutput;
+  result.found = true;
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// detectExistingMeko
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if a Meko MCP server is already registered in Claude Code.
+ *
+ * Runs `claude mcp list` and scans the output for the given server name.
+ * The output format may vary between Claude CLI versions; we look for a
+ * line that starts with `<serverName>:` (e.g. "meko: http://... - Connected")
+ * and extract a status keyword from it.
+ *
+ * @param {string} [serverName="meko"] - The MCP server name to look for.
+ * @returns {{ found: boolean, status: string }}
+ *   `found`  - true if a line matching `serverName` was found.
+ *   `status` - the status value from that line (e.g. "Connected", "Failed"),
+ *              or "" if not found.
+ */
+export function detectExistingMeko(serverName = "meko") {
+  const result = { found: false, status: "" };
+
+  const output = run("claude mcp list");
+  if (!output) return result;
+
+  // Scan each line for one that begins with the server name.
+  const lines = output.split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Match "serverName:" prefix (colon-delimited format) or a table row
+    // where the first whitespace-separated token equals the server name.
+    const isMatch =
+      trimmed.startsWith(`${serverName}:`) ||
+      trimmed.split(/\s+/)[0] === serverName;
+
+    if (!isMatch) continue;
+
+    result.found = true;
+
+    // Extract status from known keywords anywhere on the line.
+    if (/\bConnected\b/i.test(trimmed)) {
+      result.status = "Connected";
+    } else if (/\bFailed\b/i.test(trimmed)) {
+      result.status = "Failed";
+    } else if (/\bError\b/i.test(trimmed)) {
+      result.status = "Error";
+    } else if (/\bDisconnected\b/i.test(trimmed)) {
+      result.status = "Disconnected";
+    } else {
+      result.status = "Unknown";
+    }
+
+    return result;
+  }
+
+  return result;
+}

package/lib/installer.mjs

@@ -0,0 +1,255 @@
+import { askYesNo } from "./prompt.mjs";
+import {
+  banner,
+  dim,
+  error,
+  info,
+  step,
+  stepFail,
+  stepOk,
+  success,
+  warn,
+} from "./logger.mjs";
+import { getClientAdapters } from "./clients/index.mjs";
+import { redactKey } from "./clients/common.mjs";
+import { runValidation } from "./validate.mjs";
+
+const LOG = {
+  dim,
+  warn,
+  info,
+};
+
+/**
+ * Install and configure Meko MCP server for a selected client.
+ * @param {object} options
+ */
+export async function install(options) {
+  const {
+    client = "claude-code",
+    url,
+    apiKey = null,
+    scope = "user",
+    name = "meko",
+    skipSkills = false,
+    skipValidation = false,
+    dryRun = false,
+    verbose = false,
+    yes = false,
+    projectRoot = process.cwd(),
+    cursorHookMode = "hybrid",
+  } = options;
+
+  const adapters = getClientAdapters();
+  const adapter = adapters[client];
+  if (!adapter) {
+    throw new Error(`Unsupported client "${client}".`);
+  }
+
+  const settingsPath = adapter.settingsPath(scope, projectRoot);
+
+  let totalSteps = 3; // register + env/hooks + validate
+  if (!skipSkills) totalSteps += 1;
+  if (skipValidation) totalSteps -= 1;
+
+  banner(`Meko Setup for ${adapter.displayName}`);
+  if (dryRun) warn("Dry-run mode - no changes will be made.");
+  if (verbose) {
+    dim(`  client: ${client}`);
+    dim(`  url:    ${url}`);
+    dim(`  apiKey: ${redactKey(apiKey)}`);
+    dim(`  scope:  ${scope}`);
+    dim(`  name:   ${name}`);
+    if (settingsPath) dim(`  config: ${settingsPath}`);
+  }
+
+  info("Checking prerequisites...");
+  try {
+    await adapter.detectPrerequisites({ verbose, log: LOG, scope, projectRoot });
+  } catch (err) {
+    error(err.message);
+    throw err;
+  }
+  success(`${adapter.displayName} prerequisites detected.`);
+
+  const existing = adapter.detectExisting(name, { scope, projectRoot });
+  let skipMcpRegistration = false;
+  if (existing.found) {
+    let overwrite = true;
+    if (typeof adapter.maybeConfirmOverwrite === "function") {
+      overwrite = await adapter.maybeConfirmOverwrite({
+        existingFound: existing.found,
+        name,
+        yes,
+      });
+    } else if (!yes) {
+      overwrite = await askYesNo(
+        `Meko MCP is already configured for ${adapter.displayName}. Overwrite?`,
+        false,
+      );
+    }
+
+    if (!overwrite) {
+      warn("Skipping MCP registration (keeping existing config).");
+      skipMcpRegistration = true;
+    } else if (!dryRun) {
+      try {
+        adapter.removeRegistration(name, { scope, projectRoot });
+        if (verbose) dim(`  Removed existing "${name}" MCP entry.`);
+      } catch {
+        // best effort
+      }
+    } else {
+      info(`Existing "${name}" MCP configuration found - overwriting.`);
+    }
+  }
+
+  let currentStep = 1;
+
+  if (!skipMcpRegistration) {
+    step(currentStep, totalSteps, "Registering MCP server...");
+    try {
+      adapter.registerServer({
+        name,
+        url,
+        scope,
+        apiKey,
+        dryRun,
+        verbose,
+        log: LOG,
+        projectRoot,
+      });
+      stepOk(currentStep, totalSteps, dryRun ? "Registering MCP server (dry-run)" : "MCP server registered.");
+    } catch (err) {
+      stepFail(currentStep, totalSteps, "Failed to register MCP server.");
+      error(err.stderr || err.message);
+      throw new Error("MCP server registration failed.");
+    }
+  } else {
+    step(currentStep, totalSteps, "Registering MCP server... skipped (existing config kept).");
+  }
+  currentStep++;
+
+  step(currentStep, totalSteps, "Configuring hook environment...");
+  try {
+    adapter.setHookEnvironment({
+      url,
+      apiKey,
+      scope,
+      dryRun,
+      verbose,
+      log: LOG,
+      settingsPath,
+      projectRoot,
+      cursorHookMode,
+    });
+    stepOk(currentStep, totalSteps, dryRun ? "Configuring hook environment (dry-run)" : "Hook environment configured.");
+  } catch (err) {
+    stepFail(currentStep, totalSteps, "Failed to configure hook environment.");
+    error(err.message);
+    throw new Error("Hook environment configuration failed.");
+  }
+  currentStep++;
+
+  if (!skipSkills) {
+    step(currentStep, totalSteps, "Installing skills support...");
+    try {
+      const result = adapter.installSkills({
+        scope,
+        dryRun,
+        verbose,
+        log: LOG,
+        projectRoot,
+      });
+      if (!dryRun && result?.marketplace === "manual") {
+        warn("Skills installation requires manual action for this client.");
+      }
+      stepOk(currentStep, totalSteps, dryRun ? "Installing skills support (dry-run)" : "Skills support configured.");
+    } catch (err) {
+      stepFail(currentStep, totalSteps, "Failed to configure skills support.");
+      warn(`Non-critical: ${err.message}`);
+    }
+    currentStep++;
+  }
+
+  if (!skipValidation) {
+    step(currentStep, totalSteps, "Validating setup...");
+    if (dryRun) {
+      dim("  Would validate config, MCP connectivity, and tool availability.");
+      stepOk(currentStep, totalSteps, "Validating setup (dry-run)");
+    } else {
+      try {
+        const results = await runValidation(url, apiKey, name, {
+          validateConfig: async ({ serverName }) =>
+            adapter.validateConfig({ serverName, scope, projectRoot }),
+        });
+
+        const checks = [
+          { label: "Config", ...results.config },
+          { label: "Connectivity", ...results.connectivity },
+          { label: "Tools", ...results.tools },
+        ];
+        for (const check of checks) {
+          if (check.ok) success(`  ${check.label}: ${check.message}`);
+          else warn(`  ${check.label}: ${check.message}`);
+        }
+
+        if (results.allPassed) {
+          stepOk(currentStep, totalSteps, "All validation checks passed.");
+        } else {
+          stepFail(currentStep, totalSteps, "Some validation checks failed.");
+          warn("Setup completed but some checks did not pass. See details above.");
+        }
+      } catch (err) {
+        stepFail(currentStep, totalSteps, "Validation error.");
+        warn(`Validation failed: ${err.message}`);
+      }
+    }
+  }
+
+  console.log("");
+  success("Meko MCP Server setup complete.");
+  info(`Restart ${adapter.displayName} to activate the updated configuration.`);
+}
+
+/**
+ * Remove installer-managed Meko configuration for selected client.
+ * @param {object} options
+ */
+export async function uninstall(options = {}) {
+  const {
+    client = "claude-code",
+    name = "meko",
+    scope = "user",
+    verbose = false,
+    projectRoot = process.cwd(),
+    cursorHookMode = "hybrid",
+  } = options;
+
+  const adapters = getClientAdapters();
+  const adapter = adapters[client];
+  if (!adapter) {
+    throw new Error(`Unsupported client "${client}".`);
+  }
+
+  banner(`Meko Uninstall (${adapter.displayName})`);
+  const settingsPath = adapter.settingsPath(scope, projectRoot);
+  const results = adapter.uninstall({
+    name,
+    scope,
+    projectRoot,
+    settingsPath,
+    cursorHookMode,
+  });
+
+  for (const result of results) {
+    if (result.ok) success(result.message);
+    else warn(result.message);
+  }
+
+  console.log("");
+  success(`Meko has been uninstalled for ${adapter.displayName}.`);
+  if (verbose && settingsPath) {
+    dim(`Config path: ${settingsPath}`);
+  }
+}

package/lib/logger.mjs

@@ -0,0 +1,97 @@
+/**
+ * logger.mjs - Console output helpers with ANSI colors.
+ *
+ * Respects the NO_COLOR convention (https://no-color.org/).
+ * Zero external dependencies - Node.js built-ins only.
+ */
+
+const useColor = !process.env.NO_COLOR;
+
+// ANSI codes, collapsed to empty strings when color is suppressed.
+const RESET = useColor ? "\x1b[0m" : "";
+const BLUE = useColor ? "\x1b[34m" : "";
+const GREEN = useColor ? "\x1b[32m" : "";
+const YELLOW = useColor ? "\x1b[33m" : "";
+const RED = useColor ? "\x1b[31m" : "";
+const GRAY = useColor ? "\x1b[90m" : "";
+const BOLD = useColor ? "\x1b[1m" : "";
+
+// Unicode symbols with plain-text fallbacks when color is off.
+const CHECK = useColor ? "\u2713" : "OK";
+const CROSS = useColor ? "\u2717" : "FAIL";
+const BULLET = useColor ? "\u2022" : "*";
+
+/**
+ * Print an informational message.
+ * Example: ℹ  Checking prerequisites...
+ */
+export function info(msg) {
+  console.log(`${BLUE}${BULLET}${RESET} ${msg}`);
+}
+
+/**
+ * Print a success message.
+ * Example: ✓ Server registered
+ */
+export function success(msg) {
+  console.log(`${GREEN}${CHECK}${RESET} ${msg}`);
+}
+
+/**
+ * Print a warning message.
+ * Example: ⚠ Config already exists
+ */
+export function warn(msg) {
+  console.log(`${YELLOW}!${RESET} ${msg}`);
+}
+
+/**
+ * Print an error message.
+ * Example: ✗ Connection failed
+ */
+export function error(msg) {
+  console.error(`${RED}${CROSS}${RESET} ${msg}`);
+}
+
+/**
+ * Print a numbered step that is in progress.
+ * Example:   [1/5] Registering MCP server...
+ */
+export function step(n, total, msg) {
+  console.log(`  ${BLUE}[${n}/${total}]${RESET} ${msg}`);
+}
+
+/**
+ * Print a numbered step that succeeded.
+ * Example:   [1/5] Registering MCP server...          ✓
+ */
+export function stepOk(n, total, msg) {
+  console.log(`  ${GREEN}${CHECK}${RESET} ${BLUE}[${n}/${total}]${RESET} ${msg}`);
+}
+
+/**
+ * Print a numbered step that failed.
+ * Example:   [3/5] Registering plugin marketplace...   ✗ Failed: ...
+ */
+export function stepFail(n, total, msg) {
+  console.log(`  ${RED}${CROSS}${RESET} ${BLUE}[${n}/${total}]${RESET} ${msg}`);
+}
+
+/**
+ * Print a prominent banner / header line.
+ * Example:
+ *   ━━━ Meko Setup for Claude Code ━━━
+ */
+export function banner(title) {
+  const rule = useColor ? "\u2501".repeat(3) : "---";
+  console.log("");
+  console.log(`${BOLD}${BLUE}${rule} ${title} ${rule}${RESET}`);
+  console.log("");
+}
+
+/**
+ * Print dimmed / secondary text (e.g. URLs, paths, hints).
+ */
+export function dim(msg) {
+  console.log(`${GRAY}${msg}${RESET}`);
+}

package/lib/mcp-transport.mjs

@@ -0,0 +1,204 @@
+/**
+ * mcp-transport.mjs — Shared Streamable-HTTP JSON-RPC client for Meko MCP.
+ *
+ * Used by validate.mjs (post-install validation) and migrate/mcp-client.mjs
+ * (background migration). Tracks the `Mcp-Session-Id` response header across
+ * requests within a session. Zero external dependencies.
+ */
+
+import http from "node:http";
+import https from "node:https";
+
+/** Default per-request timeout in milliseconds. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+
+/**
+ * Send a JSON-RPC payload over HTTP(S).
+ *
+ * @param {string} url - Target URL.
+ * @param {object} payload - JSON-RPC body.
+ * @param {string|null} apiKey - Optional API key, sent as `API_KEY` header.
+ * @param {string|null} sessionId - Optional `Mcp-Session-Id` to include.
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs] - Override per-request timeout.
+ * @returns {Promise<{statusCode: number, headers: object, body: string}>}
+ */
+export function jsonRpcRequest(url, payload, apiKey, sessionId, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const transport = parsed.protocol === "https:" ? https : http;
+
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    };
+    if (apiKey) {
+      headers["API_KEY"] = apiKey;
+    }
+    if (sessionId) {
+      headers["Mcp-Session-Id"] = sessionId;
+    }
+
+    const body = JSON.stringify(payload);
+    headers["Content-Length"] = Buffer.byteLength(body);
+
+    const req = transport.request(
+      {
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === "https:" ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        method: "POST",
+        headers,
+        timeout: timeoutMs,
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => {
+          resolve({
+            statusCode: res.statusCode,
+            headers: res.headers,
+            body: Buffer.concat(chunks).toString("utf8"),
+          });
+        });
+      },
+    );
+
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error("TIMEOUT"));
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Produce a human-friendly message from a network error.
+ *
+ * @param {Error} err
+ * @param {number} [timeoutMs] - Included in timeout message.
+ * @returns {string}
+ */
+export function classifyError(err, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  if (err.message === "TIMEOUT") {
+    return (
+      "Request timed out after " +
+      timeoutMs / 1000 +
+      "s. Is the server running and reachable?"
+    );
+  }
+  if (err.code === "ECONNREFUSED") {
+    return (
+      "Connection refused. Is the MCP server running? " +
+      "For local Meko, ensure `docker compose up -d` has started the stack."
+    );
+  }
+  if (err.code === "ENOTFOUND") {
+    return "DNS lookup failed for host. Check the URL is correct.";
+  }
+  if (err.code === "ECONNRESET") {
+    return "Connection was reset by the server.";
+  }
+  return err.message;
+}
+
+/**
+ * Perform the MCP `initialize` + `notifications/initialized` handshake.
+ * Returns the session id assigned by the server (or null if none).
+ *
+ * @param {string} url
+ * @param {string|null} apiKey
+ * @param {object} [opts]
+ * @param {string} [opts.clientName]
+ * @param {string} [opts.clientVersion]
+ * @param {string} [opts.protocolVersion]
+ * @param {number} [opts.timeoutMs]
+ * @returns {Promise<{ok: boolean, sessionId: string|null, statusCode?: number, message?: string, raw?: object}>}
+ */
+export async function mcpInitialize(url, apiKey, opts = {}) {
+  const initPayload = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: opts.protocolVersion ?? "2025-03-26",
+      capabilities: {},
+      clientInfo: {
+        name: opts.clientName ?? "meko-installer",
+        version: opts.clientVersion ?? "1.0.0",
+      },
+    },
+  };
+
+  let res;
+  try {
+    res = await jsonRpcRequest(url, initPayload, apiKey, null, opts);
+  } catch (err) {
+    return {
+      ok: false,
+      sessionId: null,
+      message: classifyError(err, opts.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS),
+    };
+  }
+
+  if (res.statusCode === 401 || res.statusCode === 403) {
+    return {
+      ok: false,
+      sessionId: null,
+      statusCode: res.statusCode,
+      message:
+        `Server returned ${res.statusCode}. ` +
+        "Verify your API key is correct and has not expired.",
+    };
+  }
+
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    return {
+      ok: false,
+      sessionId: null,
+      statusCode: res.statusCode,
+      message: `Server returned HTTP ${res.statusCode}: ${res.body}`,
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    return {
+      ok: false,
+      sessionId: null,
+      statusCode: res.statusCode,
+      message: `Server returned non-JSON response: ${res.body.slice(0, 200)}`,
+    };
+  }
+
+  if (parsed.error) {
+    return {
+      ok: false,
+      sessionId: null,
+      statusCode: res.statusCode,
+      message: `Server error: ${parsed.error.message ?? JSON.stringify(parsed.error)}`,
+    };
+  }
+
+  const sessionId = res.headers["mcp-session-id"] ?? null;
+
+  // Fire-and-forget initialized notification.
+  try {
+    await jsonRpcRequest(
+      url,
+      { jsonrpc: "2.0", method: "notifications/initialized" },
+      apiKey,
+      sessionId,
+      opts,
+    );
+  } catch {
+    // Non-fatal: some transports accept this silently.
+  }
+
+  return { ok: true, sessionId, statusCode: res.statusCode, raw: parsed };
+}