@yugabytedb/meko-mcp 2.2.0 → 2.5.0

package/lib/clients/codex.mjs

@@ -254,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);
@@ -353,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.");
       }
@@ -427,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";
@@ -1317,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 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`,
+    `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,
@@ -1350,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`,
@@ -1360,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).",
+    );
   }
 }
 
@@ -1443,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 });
@@ -1463,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

@@ -3,6 +3,7 @@ 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>}
@@ -14,5 +15,6 @@ export function getClientAdapters() {
     cursor: createCursorAdapter(),
     codex: createCodexAdapter(),
     kiro: createKiroAdapter(),
+    opencode: createOpenCodeAdapter(),
   };
 }

package/lib/clients/kiro.mjs

@@ -55,10 +55,10 @@ const STANDALONE_HOOKS = [
  * Kiro through the `mcp-remote` stdio bridge never presents the API key at all
  * (the bridge forwards only headers passed explicitly via `--header`), so it
  * connects unauthenticated, takes a 401, and falls through to OAuth dynamic
- * client registration. Both the IDE and `kiro-cli` then die on an opaque HTML
- * 403: each registers a loopback callback, and the Cloud WAF's SSRF ruleset
- * refuses internal hosts (localhost, 127.0.0.1, RFC1918, link-local) in a
- * redirect_uri regardless of scheme. Header auth sidesteps OAuth entirely.
+ * client registration with a loopback callback. The DEV WAF refuses internal
+ * hosts in a redirect_uri with an opaque HTML 403; production accepts them as
+ * of 2026-09-24, but OAuth still needs a browser. Header auth works headless
+ * and sidesteps OAuth entirely.
  *
  * Kiro 2.18.1 contains two hook generations. CLI 2.x reads lowercase inline
  * hooks from the selected custom agent; CLI 3.x and IDE 1.x read standalone
@@ -631,7 +631,7 @@ export function renderSteeringDoc(version, name) {
     "",
     "Follow these rules:",
     "",
-    `- Search before you answer. Call \`${toolPrefix}memory_search\` at the start of a`,
+    `- Search before you answer. Call \`${toolPrefix}context_search\` at the start of a`,
     "  conversation, and again whenever the user asks what you know about something.",
     `- In fallback mode, call \`${toolPrefix}memory_add\` when the user`,
     "  states something worth remembering later: their role, preferences, team",