@yugabytedb/meko-mcp 2.1.0 → 2.3.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) {
@@ -283,7 +394,7 @@ export function createClaudeDesktopAdapter(options = {}) {
 export function buildMcpRemoteEntry({ url, apiKey }) {
   const args = [
     "-y",
-    "mcp-remote",
+    MCP_REMOTE_PACKAGE,
     url,
     "--transport",
     "http-only",
@@ -309,7 +420,11 @@ export function getMcpRemoteEntryUrl(entry) {
   }
   if (typeof entry?.url === "string") return entry.url;
   if (!Array.isArray(entry?.args)) return undefined;
-  const remoteIndex = entry.args.indexOf("mcp-remote");
+  // 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;
 }

package/lib/clients/codex.mjs

@@ -97,6 +97,7 @@ const MEKO_HOOK_SCRIPTS = [
  *   getAgentsMdPath?: () => string,
  *   getHooksPath?: () => string,
  *   getSkillsRoot?: () => string,
+ *   resolveSkillSource?: (name: string) => string,
  *   resolveHooksRoot?: () => string,
  *   getHooksInstallRoot?: () => string,
  *   runCommand?: (cmd: string) => string,
@@ -113,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;
@@ -251,7 +254,7 @@ export function createCodexAdapter(options = {}) {
       const next = removeCodexConfigBlock(raw, name);
       if (next !== raw) writeWithBackup(path, next);
     },
-    async registerServer({ name, url, apiKey, dryRun, verbose, log, scope, yes }) {
+    async registerServer({ name, url, apiKey, dryRun, verbose, log, scope }) {
       const path = settingsPathFor(scope, log);
       const useApiKey = apiKey ? "MEKO_API_KEY" : null;
       const cliCmd = buildCliRegisterCommand(name, url, useApiKey);
@@ -350,35 +353,6 @@ export function createCodexAdapter(options = {}) {
       // Cloud auth UX: env-var-only model. The key is never written to
       // config.toml; the user's runtime env supplies it. Print actionable
       // instructions and (when interactive) offer to wire things up.
-      if (apiKey) {
-        const platform = surfaces.app?.platform ?? process.platform;
-        const hasApp = Boolean(surfaces.app);
-        const shellRc = detectShellRc();
-        printCloudAuthInstructions({ shellRc, hasApp, platform, log });
-        if (!yes) {
-          await maybeOfferRcAppend({
-            apiKey,
-            shellRc,
-            promptUser,
-            log,
-          });
-          if (hasApp && platform === "darwin") {
-            await maybeOfferLaunchctlSetenv({
-              apiKey,
-              promptUser,
-              runCommand,
-              log,
-            });
-          }
-        } else if (hasApp && platform === "darwin") {
-          setLaunchctlMekoApiKey({
-            apiKey,
-            runCommand,
-            log,
-          });
-        }
-      }
-
       if (surfaces.app) {
         log.dim?.("  Restart Codex.app to attach the new MCP server.");
       }
@@ -424,6 +398,61 @@ export function createCodexAdapter(options = {}) {
         );
       }
     },
+    /**
+     * Cloud auth UX: env-var-only model. The key is never written to
+     * config.toml, so the user's runtime env must supply it. This is a
+     * separate adapter step (not part of registerServer) because an
+     * interactive reinstall where the user declines the overwrite prompt
+     * skips registration entirely - and the launchd env would otherwise
+     * never be refreshed after a key rotation. See
+     * yugabyte/meko-mcp-server#337.
+     */
+    async syncCloudAuthEnvironment({ apiKey, dryRun, log, yes }) {
+      if (!apiKey || dryRun) return;
+      const platform = surfaces.app?.platform ?? process.platform;
+      const hasApp = Boolean(surfaces.app);
+      const shellRc = detectShellRc();
+      printCloudAuthInstructions({ shellRc, hasApp, platform, log });
+      if (!yes) {
+        // Offer launchctl BEFORE rc-append, and isolate the rc-append
+        // failure mode. `maybeOfferRcAppend` throws when the shell rc is
+        // fish and the API key contains a `'` (fish single-quoting can't
+        // escape it). If that threw first, the launchctl offer - the
+        // yugabyte/meko-mcp-server#337 fix - would never run.
+        //
+        // macOS: offer launchctl setenv regardless of whether Codex.app
+        // is present. Spotlight- and Alfred-launched Codex CLI reads the
+        // launchd env too. Login-session inheritance means every
+        // GUI-launched process in this session then sees MEKO_API_KEY
+        // (visible via `launchctl getenv`, `ps e` on descendants,
+        // crash reports); the prompt copy calls that out so the choice
+        // is informed.
+        if (platform === "darwin") {
+          await maybeOfferLaunchctlSetenv({
+            apiKey,
+            promptUser,
+            runCommand,
+            log,
+          });
+        }
+        try {
+          await maybeOfferRcAppend({
+            apiKey,
+            shellRc,
+            promptUser,
+            log,
+          });
+        } catch (err) {
+          log?.warn?.(`  Skipping shell rc append: ${err.message}`);
+        }
+      } else if (platform === "darwin") {
+        setLaunchctlMekoApiKey({
+          apiKey,
+          runCommand,
+          log,
+        });
+      }
+    },
     installSkills({ dryRun, log, scope, name }) {
       void scope; // Codex skills are user-scope only.
       const serverName = name ?? "meko";
@@ -439,7 +468,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)) {
@@ -517,7 +546,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({
@@ -1314,7 +1343,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}context_search\` for relevant context: it returns personal memory, shared datapack knowledge, and past conversations in one call. Use \`${toolPrefix}memory_search\` or \`${toolPrefix}knowledgebase_search\` when you need a single source. 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,
@@ -1347,9 +1376,16 @@ function printCloudAuthInstructions({ shellRc, hasApp, platform, log }) {
     log.dim?.(`    fish:      set -gx MEKO_API_KEY '<your-meko-api-key>'`);
   }
   log.dim?.(`  Then open a new terminal (or run "exec $SHELL" / "exec fish").`);
-  if (hasApp && platform === "darwin") {
+  if (platform === "darwin") {
+    // Explain launchd for both Codex.app and CLI-only macOS installs.
+    // GUI-launched Codex (Finder, Dock, Spotlight, Alfred, `open -a`) reads
+    // launchd's env, not the shell rc, so a fresh install or a rotated key
+    // needs `launchctl setenv` to propagate. Shell-launched CLI still
+    // reads its shell rc.
     log.warn?.(
-      "macOS Codex.app launched from Finder/Dock does NOT inherit shell rc — set it via launchctl too:",
+      hasApp
+        ? "macOS Codex.app launched from Finder/Dock does NOT inherit shell rc - set it via launchctl too:"
+        : "macOS Codex CLI launched from Spotlight/Alfred/`open` does NOT inherit shell rc - set it via launchctl too:",
     );
     log.dim?.(
       `    launchctl setenv MEKO_API_KEY '<your-meko-api-key>'  # current login session`,
@@ -1357,6 +1393,9 @@ function printCloudAuthInstructions({ shellRc, hasApp, platform, log }) {
     log.dim?.(
       "    (For permanence across reboots, add a ~/Library/LaunchAgents/com.meko.env.plist.)",
     );
+    log.warn?.(
+      "  launchctl setenv writes to the login session's env, which every subsequently GUI-launched process inherits (visible via `launchctl getenv`, `ps e` on descendants, and crash reports).",
+    );
   }
 }
 
@@ -1440,9 +1479,15 @@ export async function maybeOfferLaunchctlSetenv({
   runCommand,
   log,
 }) {
+  // Default to Yes: this is the setting that makes GUI-launched Codex on
+  // macOS see the fresh key. Users who habitually hit Enter at the prompt
+  // otherwise leave launchd empty and Codex authenticates with whatever key
+  // it had at first start. See yugabyte/meko-mcp-server#337. The prompt
+  // names both Codex.app and Spotlight-launched CLI so a user without the
+  // desktop app understands why the offer applies to them.
   const accept = await promptUser(
-    "Run `launchctl setenv MEKO_API_KEY ...` so Codex.app sees the key now?",
-    false,
+    "Run `launchctl setenv MEKO_API_KEY ...` so GUI-launched Codex (App, Spotlight, Alfred, `open`) sees the key now? (writes the key into the login session env, inherited by every subsequently GUI-launched process)",
+    true,
   );
   if (!accept) return { set: false };
   return setLaunchctlMekoApiKey({ apiKey, runCommand, log });
@@ -1460,6 +1505,9 @@ export function setLaunchctlMekoApiKey({ apiKey, runCommand, log }) {
   try {
     runCommand(`launchctl setenv MEKO_API_KEY ${shellQuote(apiKey)}`);
     log?.dim?.("  Set MEKO_API_KEY via launchctl (current login session).");
+    log?.warn?.(
+      "  Fully quit any running Codex (Cmd-Q, or `pkill -x codex` for the CLI) and relaunch — a process already running will keep its previous MEKO_API_KEY.",
+    );
     return { set: true };
   } catch (err) {
     log?.warn?.("  launchctl setenv failed; run it manually if Codex.app needs cloud auth.");

package/lib/clients/common.mjs

@@ -88,6 +88,13 @@ export function resolveHooksRoot() {
   return join(getAssetRoot(), "hooks-handlers");
 }
 
+/**
+ * @returns {string} absolute path to the installer-owned OpenCode plugin source
+ */
+export function resolveOpenCodePluginSource() {
+  return join(getAssetRoot(), "opencode-plugin", "meko.js");
+}
+
 /**
  * @returns {string} absolute path to the statusline script source.
  *   Lives under skills/scripts/ in source, mirrored under assets/scripts/ in

package/lib/clients/index.mjs

@@ -2,6 +2,8 @@ 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";
+import { createOpenCodeAdapter } from "./opencode.mjs";
 
 /**
  * @returns {Record<string, object>}
@@ -12,5 +14,7 @@ export function getClientAdapters() {
     "claude-desktop": createClaudeDesktopAdapter(),
     cursor: createCursorAdapter(),
     codex: createCodexAdapter(),
+    kiro: createKiroAdapter(),
+    opencode: createOpenCodeAdapter(),
   };
 }