@yugabytedb/meko-mcp 1.0.3

package/lib/prompt.mjs

@@ -0,0 +1,212 @@
+/**
+ * prompt.mjs - Interactive terminal prompts using Node.js readline.
+ *
+ * Lazy-initializes the readline interface on first use so that importing
+ * this module has no side-effects (no stdin/stdout hijacking until needed).
+ * Zero external dependencies - Node.js built-ins only.
+ */
+
+import { createInterface } from "node:readline";
+
+// ---------------------------------------------------------------------------
+// Lazy readline singleton
+// ---------------------------------------------------------------------------
+
+/** @type {import('node:readline').Interface | null} */
+let rl = null;
+
+function getRL() {
+  if (!rl) {
+    rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+  }
+  return rl;
+}
+
+/**
+ * Thin promise wrapper around `rl.question`.
+ * @param {string} query - The prompt text shown to the user.
+ * @returns {Promise<string>}
+ */
+function question(query) {
+  return new Promise((resolve) => {
+    getRL().question(query, (answer) => resolve(answer));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// askChoice
+// ---------------------------------------------------------------------------
+
+/**
+ * Display a numbered list and return the selected option's label.
+ *
+ * @param {string} questionText
+ * @param {{ label: string, description?: string }[]} options
+ * @returns {Promise<string>} The `label` of the chosen option.
+ *
+ * @example
+ *   const choice = await askChoice('Connection type:', [
+ *     { label: 'Cloud Meko', description: 'Hosted at mekodev.com' },
+ *     { label: 'Local Meko', description: 'docker-compose stack' },
+ *   ]);
+ */
+export async function askChoice(questionText, options) {
+  console.log(`\n  ${questionText}`);
+  for (let i = 0; i < options.length; i++) {
+    const opt = options[i];
+    const desc = opt.description ? `  - ${opt.description}` : "";
+    console.log(`    ${i + 1}) ${opt.label}${desc}`);
+  }
+
+  while (true) {
+    const raw = await question(`  Choice [1-${options.length}]: `);
+    const idx = parseInt(raw.trim(), 10);
+    if (idx >= 1 && idx <= options.length) {
+      return options[idx - 1].label;
+    }
+    console.log(`  Please enter a number between 1 and ${options.length}.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// askText
+// ---------------------------------------------------------------------------
+
+/**
+ * Free-text input with an optional default shown in brackets.
+ *
+ * @param {string} questionText
+ * @param {string} [defaultValue]
+ * @returns {Promise<string>}
+ */
+export async function askText(questionText, defaultValue) {
+  const suffix = defaultValue != null ? ` [${defaultValue}]` : "";
+  const raw = await question(`  ${questionText}${suffix} `);
+  const trimmed = raw.trim();
+  return trimmed || defaultValue || "";
+}
+
+// ---------------------------------------------------------------------------
+// askSecret
+// ---------------------------------------------------------------------------
+
+/**
+ * Masked input that echoes `*` for each character typed.
+ *
+ * Puts stdin into raw mode so we can intercept individual keystrokes.
+ * Handles backspace, Ctrl-C (abort), and Enter (submit).
+ *
+ * @param {string} questionText
+ * @returns {Promise<string>}
+ */
+export async function askSecret(questionText) {
+  // Print the prompt without a trailing newline.
+  process.stdout.write(`  ${questionText} `);
+
+  return new Promise((resolve, reject) => {
+    let secret = "";
+    const stdin = process.stdin;
+
+    // We need raw mode to capture keystrokes individually.
+    // Guard: raw mode is only available on TTY streams.
+    if (!stdin.isTTY) {
+      // Fallback: non-TTY environments (piped input) - read a plain line.
+      const fallbackRL = createInterface({ input: stdin, output: process.stdout });
+      fallbackRL.question("", (answer) => {
+        fallbackRL.close();
+        resolve(answer.trim());
+      });
+      return;
+    }
+
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+
+    /** Restore stdin state and print a newline after the masked input. */
+    function cleanup() {
+      stdin.setRawMode(wasRaw);
+      stdin.removeListener("data", onData);
+      process.stdout.write("\n");
+    }
+
+    function onData(ch) {
+      const code = ch.charCodeAt(0);
+
+      // Ctrl-C - abort gracefully
+      if (ch === "\u0003") {
+        cleanup();
+        reject(new Error("User cancelled"));
+        return;
+      }
+
+      // Enter / Return
+      if (ch === "\r" || ch === "\n") {
+        cleanup();
+        resolve(secret);
+        return;
+      }
+
+      // Backspace / Delete (char code 127 or 8)
+      if (code === 127 || code === 8) {
+        if (secret.length > 0) {
+          secret = secret.slice(0, -1);
+          // Erase the last asterisk: move cursor back, overwrite, move back.
+          process.stdout.write("\b \b");
+        }
+        return;
+      }
+
+      // Ignore other control characters (arrows, etc.)
+      if (code < 32) {
+        return;
+      }
+
+      // Normal printable character
+      secret += ch;
+      process.stdout.write("*");
+    }
+
+    stdin.on("data", onData);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// askYesNo
+// ---------------------------------------------------------------------------
+
+/**
+ * Y/n confirmation prompt. Returns a boolean.
+ *
+ * @param {string} questionText
+ * @param {boolean} [defaultYes=true] - When true the prompt shows `[Y/n]`,
+ *   otherwise `[y/N]`. Pressing Enter without input uses the default.
+ * @returns {Promise<boolean>}
+ */
+export async function askYesNo(questionText, defaultYes = true) {
+  const hint = defaultYes ? "Y/n" : "y/N";
+  const raw = await question(`  ${questionText} [${hint}] `);
+  const trimmed = raw.trim().toLowerCase();
+
+  if (trimmed === "") return defaultYes;
+  return trimmed === "y" || trimmed === "yes";
+}
+
+// ---------------------------------------------------------------------------
+// close
+// ---------------------------------------------------------------------------
+
+/**
+ * Tear down the readline interface so the process can exit cleanly.
+ * Safe to call multiple times or before any prompt was used.
+ */
+export function close() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}

package/lib/validate.mjs

@@ -0,0 +1,259 @@
+/**
+ * validate.mjs - Post-install validation for Meko MCP Server.
+ *
+ * Runs three checks in sequence:
+ *   1. Config check   - Is the server registered in `claude mcp list`?
+ *   2. Connectivity    - Can we complete an MCP `initialize` handshake?
+ *   3. Tools           - Does `tools/list` return the expected core tools?
+ *
+ * HTTP transport lives in ./mcp-transport.mjs and is shared with the
+ * migrate subcommand.
+ */
+
+import { execFile } from "node:child_process";
+import {
+  jsonRpcRequest,
+  classifyError,
+  mcpInitialize,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+} from "./mcp-transport.mjs";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Core tools that must appear in tools/list for validation to pass. */
+const CORE_TOOLS = [
+  "memory_search",
+  "conversation_create",
+  "db_summarize_database",
+];
+
+// ---------------------------------------------------------------------------
+// 1. Config validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify that a named MCP server appears in `claude mcp list` output.
+ *
+ * @param {string} serverName - The server name to look for (e.g. "meko").
+ * @returns {Promise<{ok: boolean, message: string}>}
+ */
+export async function validateConfig(serverName) {
+  try {
+    const stdout = await execAsync("claude", ["mcp", "list"]);
+    // `claude mcp list` outputs one server per line, name as the first token.
+    const lines = stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+    const found = lines.some((line) => {
+      const name = line.split(":")[0].trim();
+      return name === 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}`,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Connectivity validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt an MCP `initialize` handshake against the server URL.
+ *
+ * @param {string} url - Full MCP endpoint URL (e.g. http://localhost:8000/mcp).
+ * @param {string|null} apiKey - Optional API key (sent as `API_KEY` header).
+ * @returns {Promise<{ok: boolean, message: string, sessionId?: string}>}
+ */
+export async function validateConnectivity(url, apiKey) {
+  const result = await mcpInitialize(url, apiKey);
+  if (!result.ok) {
+    return { ok: false, message: result.message };
+  }
+  return {
+    ok: true,
+    message: `MCP server reachable at ${url}`,
+    sessionId: result.sessionId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 3. Tools validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Send `tools/list` and verify that core Meko tools are present.
+ *
+ * Performs its own initialize handshake first to establish a session,
+ * then sends tools/list within that session.
+ *
+ * @param {string} url - Full MCP endpoint URL.
+ * @param {string|null} apiKey - Optional API key.
+ * @returns {Promise<{ok: boolean, tools: string[], message: string}>}
+ */
+export async function validateTools(url, apiKey) {
+  // Establish a session first.
+  const connResult = await validateConnectivity(url, apiKey);
+  if (!connResult.ok) {
+    return {
+      ok: false,
+      tools: [],
+      message: `Cannot list tools: ${connResult.message}`,
+    };
+  }
+
+  return sendToolsList(url, apiKey, connResult.sessionId);
+}
+
+// ---------------------------------------------------------------------------
+// 4. Combined runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Run all validation checks in sequence and return a summary.
+ *
+ * When the connectivity check succeeds, the tools check reuses the same
+ * MCP session rather than performing a redundant second initialize.
+ *
+ * @param {string} url - Full MCP endpoint URL.
+ * @param {string|null} apiKey - Optional API key.
+ * @param {string} serverName - Server name for config check (default "meko").
+ * @param {object} [options]
+ * @param {(params: {serverName: string}) => Promise<{ok: boolean, message: string}>} [options.validateConfig]
+ * @returns {Promise<{config: object, connectivity: object, tools: object, allPassed: boolean}>}
+ */
+export async function runValidation(url, apiKey, serverName = "meko", options = {}) {
+  const configValidator = options.validateConfig ?? (async ({ serverName: value }) => validateConfig(value));
+  const config = await configValidator({ serverName });
+  const connectivity = await validateConnectivity(url, apiKey);
+
+  let tools;
+  if (connectivity.ok) {
+    // Reuse the session from the connectivity check.
+    tools = await sendToolsList(url, apiKey, connectivity.sessionId);
+  } else {
+    tools = { ok: false, tools: [], message: `Skipped: ${connectivity.message}` };
+  }
+
+  return {
+    config,
+    connectivity,
+    tools,
+    allPassed: config.ok && connectivity.ok && tools.ok,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal: tools/list over an existing session
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a tools/list request using an existing (or null) session ID.
+ *
+ * @param {string} url
+ * @param {string|null} apiKey
+ * @param {string|null} sessionId
+ * @returns {Promise<{ok: boolean, tools: string[], message: string}>}
+ */
+async function sendToolsList(url, apiKey, sessionId) {
+  const payload = {
+    jsonrpc: "2.0",
+    id: 2,
+    method: "tools/list",
+    params: {},
+  };
+
+  let res;
+  try {
+    res = await jsonRpcRequest(url, payload, apiKey, sessionId);
+  } catch (err) {
+    return {
+      ok: false,
+      tools: [],
+      message: `tools/list request failed: ${classifyError(err)}`,
+    };
+  }
+
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    return {
+      ok: false,
+      tools: [],
+      message: `tools/list returned HTTP ${res.statusCode}: ${res.body}`,
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    return {
+      ok: false,
+      tools: [],
+      message: `tools/list returned non-JSON: ${res.body.slice(0, 200)}`,
+    };
+  }
+
+  if (parsed.error) {
+    return {
+      ok: false,
+      tools: [],
+      message: `tools/list error: ${parsed.error.message ?? JSON.stringify(parsed.error)}`,
+    };
+  }
+
+  const toolList = parsed.result?.tools ?? [];
+  const toolNames = toolList.map((t) => t.name);
+  const missing = CORE_TOOLS.filter((name) => !toolNames.includes(name));
+
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      tools: toolNames,
+      message:
+        `Missing core tools: ${missing.join(", ")}. ` +
+        `Found ${toolNames.length} tool(s) total.`,
+    };
+  }
+
+  return {
+    ok: true,
+    tools: toolNames,
+    message: `All ${CORE_TOOLS.length} core tools present (${toolNames.length} total).`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal: child process helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Promisified child_process.execFile.
+ *
+ * @param {string} cmd - Executable name or path.
+ * @param {string[]} args - Arguments.
+ * @returns {Promise<string>} stdout
+ */
+function execAsync(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: DEFAULT_REQUEST_TIMEOUT_MS }, (err, stdout, stderr) => {
+      if (err) {
+        const msg = stderr?.trim() || err.message;
+        reject(new Error(msg));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@yugabytedb/meko-mcp",
+  "version": "1.0.3",
+  "description": "Single-line installer for Meko MCP Server across Claude and Cursor clients",
+  "type": "module",
+  "bin": {
+    "create-meko-setup": "bin/create-meko-setup.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "assets/",
+    "scripts/bundle-assets.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node scripts/bundle-assets.mjs",
+    "postpack": "node scripts/bundle-assets.mjs --clean",
+    "bundle-assets": "node scripts/bundle-assets.mjs",
+    "test": "node --test \"test/*.mjs\"",
+    "test:unit": "node --test test/config.test.mjs test/validate.test.mjs test/clients.test.mjs",
+    "test:integration": "RUN_INSTALLER_INTEGRATION=1 node --test test/installer.test.mjs",
+    "test:integration:cloud": "RUN_INSTALLER_INTEGRATION=1 node --test test/installer.test.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "meko",
+    "mcp",
+    "claude-code",
+    "yugabytedb",
+    "installer",
+    "ai-memory",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yugabyte/meko-mcp-server.git",
+    "directory": "installer"
+  },
+  "homepage": "https://mekodata.netlify.app/",
+  "license": "Apache-2.0",
+  "author": "YugaByte <info@yugabyte.com>",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/scripts/bundle-assets.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Copy skill/hook assets from the repo into installer/assets/ so the npm
+ * tarball can be installed without a repo checkout. Invoked by `prepack`;
+ * `postpack` re-runs this with --clean.
+ */
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const installerRoot = resolve(scriptDir, "..");
+const repoRoot = resolve(installerRoot, "..");
+const assetsDir = join(installerRoot, "assets");
+
+const PAYLOAD = [
+  {
+    from: join(repoRoot, "skills", "skills", "meko-mcp-tools"),
+    to: join(assetsDir, "skills", "meko-mcp-tools"),
+  },
+  {
+    from: join(repoRoot, "skills", "hooks-handlers"),
+    to: join(assetsDir, "hooks-handlers"),
+  },
+];
+
+const cleaning = process.argv.includes("--clean");
+
+if (cleaning) {
+  if (existsSync(assetsDir)) {
+    rmSync(assetsDir, { recursive: true, force: true });
+  }
+  process.exit(0);
+}
+
+if (existsSync(assetsDir)) {
+  rmSync(assetsDir, { recursive: true, force: true });
+}
+mkdirSync(assetsDir, { recursive: true });
+
+for (const { from, to } of PAYLOAD) {
+  if (!existsSync(from)) {
+    console.error(`bundle-assets: missing source ${from}`);
+    process.exit(1);
+  }
+  cpSync(from, to, { recursive: true });
+}
+
+console.log(`bundle-assets: wrote ${PAYLOAD.length} paths under ${assetsDir}`);