@yugabytedb/meko-mcp 2.0.0 → 2.2.0

package/lib/clients/claude-desktop.mjs

@@ -18,6 +18,101 @@ import {
   writeInstallerMarker,
 } from "./common.mjs";
 
+/**
+ * Pinned top-level `mcp-remote` version.
+ *
+ * Pinning the top-level package (rather than leaving a bare `mcp-remote` that
+ * floats onto whatever npm's `latest` tag points to) reduces — but does not
+ * eliminate — startup drift: `mcp-remote@0.1.38` still declares transitive
+ * ranges like `open@^10.1.0` and `undici@^7.12.0`, and a fresh `npx` cache
+ * resolves the newest matching version of each with no lockfile consulted, so
+ * a future transitive release can still change startup behavior. The Node
+ * floor enforced below is what keeps today's tree runnable: every *currently
+ * published* undici 7 release declares `engines.node >= 20.18.1`, so rejecting
+ * Node under that floor covers the dependency set that resolves today. It is
+ * not a future-proof guarantee — a later in-range 7.x release could raise its
+ * own engine floor or introduce another incompatibility, which is exactly the
+ * residual drift the paragraph above acknowledges. Bump this pin deliberately
+ * after verifying the new release still starts on the supported Node floor.
+ */
+export const MCP_REMOTE_VERSION = "0.1.38";
+
+/** Pinned npm spec used in the registered command, e.g. `mcp-remote@0.1.38`. */
+export const MCP_REMOTE_PACKAGE = `mcp-remote@${MCP_REMOTE_VERSION}`;
+
+/**
+ * Minimum Node.js version required for the registered mcp-remote bridge to
+ * start. `mcp-remote@0.1.38` depends on `undici@^7.12.0`, and every undici 7
+ * release declares `engines.node >= 20.18.1`. npm's engine check is only a
+ * warning by default, so nothing stops a below-floor Node from resolving the
+ * tree and then crashing the bridge — we hard-fail preflight here instead of
+ * writing a config that cannot start. Bump this in lockstep with the pinned
+ * `mcp-remote` version above (and the advertised floors in package.json,
+ * mcpb/manifest.json, and the docs) after verifying the new dependency tree's
+ * engine requirement.
+ */
+export const MIN_NODE_VERSION = "20.18.1";
+
+/**
+ * Structured form of {@link MIN_NODE_VERSION}, parsed once so the preflight can
+ * compare major/minor/patch without re-parsing on every call.
+ */
+export const MIN_NODE = parseNodeVersion(MIN_NODE_VERSION);
+
+/**
+ * Parse a `process.version`-style string into its numeric {major, minor, patch}
+ * components (e.g. "v20.18.1" -> {major:20, minor:18, patch:1}). A missing
+ * minor/patch defaults to 0. Returns null when unparseable.
+ *
+ * The regex is end-anchored and rejects any trailing characters, including a
+ * semver prerelease/build suffix (`-rc.1`, `-nightly`, `+build`). A prerelease
+ * like `20.18.1-rc.1` sorts *below* the stable `20.18.1` under semver, so we
+ * must not silently discard the suffix and treat it as the stable release —
+ * that would let a below-floor prerelease pass the preflight. Returning null
+ * here routes such versions through `nodeMeetsFloor`'s not-satisfied path.
+ *
+ * @param {string} version
+ * @returns {{major:number, minor:number, patch:number}|null}
+ */
+export function parseNodeVersion(version) {
+  const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(String(version));
+  if (!match) return null;
+  const major = Number(match[1]);
+  const minor = Number(match[2] ?? 0);
+  const patch = Number(match[3] ?? 0);
+  if (![major, minor, patch].every(Number.isFinite)) return null;
+  return { major, minor, patch };
+}
+
+/**
+ * Does `version` meet the {@link MIN_NODE} floor (>= major.minor.patch)?
+ *
+ * Three cases:
+ *  - A clean `X.Y.Z` at/above the floor → true; below → false.
+ *  - A *version-shaped* string that isn't a clean release — a prerelease
+ *    (`20.18.1-rc.1`) or trailing garbage (`20.19.0-night,`) — → false. Under
+ *    semver a prerelease sorts below its release, so it does NOT satisfy
+ *    `>=20.18.1`; we reject rather than accept an ambiguous runtime.
+ *  - Input that isn't version-shaped at all → true. We stay lenient on strings
+ *    we can't read (the same stance the previous major-only check took);
+ *    `process.version` never produces these, so this only guards odd stubs.
+ *
+ * @param {string} version
+ * @returns {boolean}
+ */
+export function nodeMeetsFloor(version) {
+  const parsed = parseNodeVersion(version);
+  if (parsed === null) {
+    // Version-shaped (leading digits, optionally `v`-prefixed) but not a clean
+    // X.Y.Z — i.e. it carried a prerelease/build suffix or trailing chars.
+    // Treat as not satisfying the floor. Truly non-version input is lenient.
+    return !/^v?\d/.test(String(version));
+  }
+  if (parsed.major !== MIN_NODE.major) return parsed.major > MIN_NODE.major;
+  if (parsed.minor !== MIN_NODE.minor) return parsed.minor > MIN_NODE.minor;
+  return parsed.patch >= MIN_NODE.patch;
+}
+
 /**
  * Claude Desktop adapter.
  *
@@ -31,7 +126,7 @@ import {
  *
  *   "meko": {
  *     "command": "npx",
- *     "args": ["-y", "mcp-remote", "<url>", "--transport", "http-only",
+ *     "args": ["-y", "mcp-remote@<pinned>", "<url>", "--transport", "http-only",
  *              "--header", "User-Agent:meko-mcp-installer/1.0 (...)",
  *              "--header", "Authorization:Bearer ${MEKO_API_KEY}"],
  *     "env": { "MEKO_API_KEY": "<key>" }
@@ -53,6 +148,7 @@ export function createClaudeDesktopAdapter(options = {}) {
   const assetRootResolver = options.getAssetRoot ?? getAssetRoot;
   const packageRunner = options.runPackageScript ?? defaultRunPackageScript;
   const npxProber = options.probeNpx ?? defaultProbeNpx;
+  const nodeVersionResolver = options.getNodeVersion ?? (() => process.version);
 
   return {
     id: "claude-desktop",
@@ -61,12 +157,27 @@ export function createClaudeDesktopAdapter(options = {}) {
       return configPathResolver();
     },
     async detectPrerequisites({ log, verbose } = {}) {
+      // The registered mcp-remote bridge pulls in undici@^7, whose every
+      // release declares engines.node >= 20.18.1; below that floor the bridge
+      // crashes at startup and Claude Desktop shows "Server disconnected". A
+      // major-only check would wave through Node 20.0.0–20.18.0, so we parse
+      // the full version and reject anything below the exact floor here,
+      // before writing a config that Claude Desktop cannot start.
+      const nodeVersion = nodeVersionResolver();
+      if (!nodeMeetsFloor(nodeVersion)) {
+        throw new Error(
+          `Node >= ${MIN_NODE_VERSION} is required for the mcp-remote bridge that ` +
+            `Claude Desktop launches (detected ${nodeVersion}). Older Node ` +
+            `versions crash the bridge at startup and Claude Desktop shows ` +
+            `"Server disconnected". Upgrade Node.js and re-run the installer.`,
+        );
+      }
       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.",
+            `mcp-remote stdio bridge. Install Node.js ${MIN_NODE_VERSION}+ (which ` +
+            "includes npx) and re-run the installer.",
         );
       }
       if (verbose && log?.dim) {
@@ -99,9 +210,11 @@ export function createClaudeDesktopAdapter(options = {}) {
       const fromMcpb =
         /\bClaude\b[^ ]*\bExtensions\b/i.test(commandJoined) ||
         /mcp-remote-launcher\.js/.test(commandJoined);
+      const url = getMcpRemoteEntryUrl(entry);
       return {
         found: true,
         status: fromMcpb ? "Configured (via .mcpb extension)" : "Configured",
+        ...(url ? { url } : {}),
       };
     },
     removeRegistration(name) {
@@ -281,7 +394,7 @@ export function createClaudeDesktopAdapter(options = {}) {
 export function buildMcpRemoteEntry({ url, apiKey }) {
   const args = [
     "-y",
-    "mcp-remote",
+    MCP_REMOTE_PACKAGE,
     url,
     "--transport",
     "http-only",
@@ -300,6 +413,22 @@ export function buildMcpRemoteEntry({ url, apiKey }) {
   return entry;
 }
 
+/** Read the remote URL from installer-managed or MCPB Claude Desktop entries. */
+export function getMcpRemoteEntryUrl(entry) {
+  if (typeof entry?.env?.MEKO_MCP_URL === "string") {
+    return entry.env.MEKO_MCP_URL;
+  }
+  if (typeof entry?.url === "string") return entry.url;
+  if (!Array.isArray(entry?.args)) return undefined;
+  // Match both the bare `mcp-remote` (legacy entries) and the pinned
+  // `mcp-remote@<version>` spec the installer now writes.
+  const remoteIndex = entry.args.findIndex(
+    (arg) => arg === "mcp-remote" || (typeof arg === "string" && arg.startsWith("mcp-remote@")),
+  );
+  const candidate = remoteIndex >= 0 ? entry.args[remoteIndex + 1] : undefined;
+  return typeof candidate === "string" ? candidate : undefined;
+}
+
 function defaultRunPackageScript(scriptPath) {
   if (!statSync(scriptPath).isFile()) {
     throw new Error(`Not a file: ${scriptPath}`);

package/lib/clients/codex.mjs

@@ -77,14 +77,19 @@ const RC_FENCE_END = "# <<< meko mcp <<<";
 const SKILLS = [{ name: "meko-mcp-tools" }];
 // Codex hook timeouts are in SECONDS (Duration::from_secs in
 // codex-rs/hooks/src/engine/command_runner.rs), not milliseconds like Claude
-// Code / Cursor. Default is 600s if omitted; we cap SessionStart/SessionEnd
-// at 15s/30s to match the Claude Code values logically.
+// Code / Cursor. Codex hard-caps SessionEnd at three seconds, so its dedicated
+// handler only spools input and launches the actual capture in the background.
 const MEKO_HOOKS = [
   { event: "SessionStart", script: "session-start.sh", timeout: 15 },
   { event: "PreCompact", script: "pre-compact.sh" },
-  { event: "SessionEnd", script: "session-end.sh", timeout: 30 },
+  { event: "SessionEnd", script: "codex-session-end.sh", timeout: 3 },
+];
+// Include the former synchronous Codex SessionEnd handler so reinstall prunes
+// it instead of leaving both old and new handlers active.
+const MEKO_HOOK_SCRIPTS = [
+  ...MEKO_HOOKS.map((hook) => hook.script),
+  "session-end.sh",
 ];
-const MEKO_HOOK_SCRIPTS = MEKO_HOOKS.map((hook) => hook.script);
 
 /**
  * @param {{
@@ -92,6 +97,7 @@ const MEKO_HOOK_SCRIPTS = MEKO_HOOKS.map((hook) => hook.script);
  *   getAgentsMdPath?: () => string,
  *   getHooksPath?: () => string,
  *   getSkillsRoot?: () => string,
+ *   resolveSkillSource?: (name: string) => string,
  *   resolveHooksRoot?: () => string,
  *   getHooksInstallRoot?: () => string,
  *   runCommand?: (cmd: string) => string,
@@ -108,6 +114,8 @@ export function createCodexAdapter(options = {}) {
   const resolveHooksPath = options.getHooksPath ?? getCodexHooksPath;
   const resolveMekoEnvFilePath =
     options.getMekoEnvFilePath ?? getCodexMekoEnvFilePath;
+  const resolveSkillSourcePath =
+    options.resolveSkillSource ?? resolveSkillSource;
   const resolveHooksRootPath = options.resolveHooksRoot ?? resolveHooksRoot;
   const resolveHooksInstallRoot =
     options.getHooksInstallRoot ?? getCodexHooksInstallRoot;
@@ -196,10 +204,11 @@ export function createCodexAdapter(options = {}) {
         surfaces.app = app?.found ? app : null;
       }
 
+      let cliFound = false;
       if (surfaces.cli) {
         try {
           runCommand(`codex mcp get ${shellQuote(name)}`);
-          return { found: true, status: "Configured" };
+          cliFound = true;
         } catch {
           // fall through to TOML grep — `codex mcp get` exits non-zero when
           // the entry isn't present, but might also fail for unrelated
@@ -209,8 +218,17 @@ export function createCodexAdapter(options = {}) {
       }
       const path = settingsPathFor(scope, null);
       const raw = safeReadFile(path);
-      if (raw === null) return { found: false, status: "" };
-      return parseCodexConfigForServer(raw, name).found
+      if (raw !== null) {
+        const parsed = parseCodexConfigForServer(raw, name);
+        if (parsed.found) {
+          return {
+            found: true,
+            status: "Configured",
+            ...(parsed.url ? { url: parsed.url } : {}),
+          };
+        }
+      }
+      return cliFound
         ? { found: true, status: "Configured" }
         : { found: false, status: "" };
     },
@@ -424,7 +442,7 @@ export function createCodexAdapter(options = {}) {
 
       mkdirSync(skillsRoot, { recursive: true });
       for (const skill of SKILLS) {
-        const source = resolveSkillSource(skill.name);
+        const source = resolveSkillSourcePath(skill.name);
         const destination = join(skillsRoot, skill.name);
 
         if (existsSync(destination)) {
@@ -502,7 +520,7 @@ export function createCodexAdapter(options = {}) {
             removePath(dest);
             continue;
           }
-          const expectedSource = resolveSkillSource(skill.name);
+          const expectedSource = resolveSkillSourcePath(skill.name);
           if (isOwnSymlink(dest, expectedSource)) removePath(dest);
         }
         results.push({
@@ -640,7 +658,7 @@ function upsertCodexMekoHooks(hooksPath, hooksRoot, { envFilePath } = {}) {
 function buildCodexHookCommand(scriptPath, { envFilePath } = {}) {
   const parts = [];
   if (envFilePath) parts.push(`. ${shellQuote(envFilePath)}`);
-  parts.push(`bash ${shellQuote(scriptPath)}`);
+  parts.push(`MEKO_HOOK_CLIENT=codex bash ${shellQuote(scriptPath)}`);
   return parts.join(" && ");
 }
 
@@ -1299,7 +1317,7 @@ function renderAgentsMdBlock(version, name) {
     `${AGENTS_MD_START} v${version}`,
     "## Meko memory (auto-managed by meko installer)",
     "",
-    `You have a persistent memory store via the \`${name}\` MCP server. At the start of every conversation, call \`${toolPrefix}memory_search\` for relevant context. When the user shares facts, preferences, or decisions worth remembering, call \`${toolPrefix}memory_add\`. Skill details: ~/.agents/skills/meko-mcp-tools/SKILL.md`,
+    `You have a persistent memory store via the \`${name}\` MCP server. At the start of every conversation, call \`${toolPrefix}memory_search\` for relevant personal context; use \`${toolPrefix}knowledgebase_search\` when the request concerns shared datapack knowledge. When the user shares facts, preferences, or decisions worth remembering, call \`${toolPrefix}memory_add\`. Skill details: ~/.agents/skills/meko-mcp-tools/SKILL.md`,
     "",
     "Cloud auth requires `MEKO_API_KEY` exported in your shell (or, for the desktop app on macOS, set via `launchctl setenv`).",
     AGENTS_MD_END,

package/lib/clients/common.mjs

@@ -16,6 +16,8 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const MEKO_MCP_USER_AGENT = "meko-mcp-installer/1.0";
+export const MEKO_PRODUCTION_MCP_URL = "https://mcp.mekodata.ai/mcp";
+export const MEKO_PRODUCTION_CONSOLE_URL = "https://cloud.mekodata.ai";
 
 /**
  * @returns {string} Absolute repository root path.

package/lib/clients/cursor.mjs

@@ -75,8 +75,13 @@ export function createCursorAdapter(customPaths = {}) {
     detectExisting(name, { scope, projectRoot }) {
       const path = paths.getMcpPath(scope, projectRoot);
       const cfg = readJsonFile(path);
-      const found = Boolean(cfg?.mcpServers?.[name]);
-      return { found, status: found ? "Configured" : "" };
+      const entry = cfg?.mcpServers?.[name];
+      const found = Boolean(entry);
+      return {
+        found,
+        status: found ? "Configured" : "",
+        ...(typeof entry?.url === "string" ? { url: entry.url } : {}),
+      };
     },
     removeRegistration(name, { scope, projectRoot }) {
       const mcpPath = paths.getMcpPath(scope, projectRoot);

package/lib/clients/index.mjs

@@ -2,6 +2,7 @@ import { createClaudeCodeAdapter } from "./claude-code.mjs";
 import { createClaudeDesktopAdapter } from "./claude-desktop.mjs";
 import { createCodexAdapter } from "./codex.mjs";
 import { createCursorAdapter } from "./cursor.mjs";
+import { createKiroAdapter } from "./kiro.mjs";
 
 /**
  * @returns {Record<string, object>}
@@ -12,5 +13,6 @@ export function getClientAdapters() {
     "claude-desktop": createClaudeDesktopAdapter(),
     cursor: createCursorAdapter(),
     codex: createCodexAdapter(),
+    kiro: createKiroAdapter(),
   };
 }