@yugabytedb/meko-mcp 1.0.5 → 1.0.8

package/README.md

@@ -4,6 +4,10 @@ A zero-dependency Node.js CLI that configures [Meko MCP Server](https://mekodata
 
 Reduces manual setup to a single command.
 
+## Prerequisites
+
+- **Node.js 18 or newer** on your PATH. Get it from [nodejs.org](https://nodejs.org/) or via a version manager (`nvm`, `fnm`, `asdf`). `npx`, which comes bundled with Node, is how you invoke the installer.
+
 ## Quick Start
 
 The installer is path-agnostic — the three forms below are equivalent. Pick the one that matches how you obtained the code:
@@ -77,9 +81,9 @@ The installer performs up to 5 steps (some are skippable via flags):
 
 | Step | Action | Command / File Modified |
 |------|--------|------------------------|
-| 1 | Register MCP server | `claude mcp add meko <url> --transport http --scope user` (with `-H "API_KEY: <key>"` for cloud) |
+| 1 | Register MCP server | `claude mcp add meko <url> --transport http --scope user` (with `-H "Authorization: Bearer <key>"` for cloud) |
 | 2 | Set hook environment vars | Writes `MEKO_MCP_URL` and `MEKO_API_KEY` into `~/.claude/settings.json` under the `env` key |
-| 3 | Register plugin marketplace | `claude plugin marketplace add yugabyte/meko-mcp-server --sparse .claude-plugin,skills --scope user` |
+| 3 | Register plugin marketplace | `claude plugin marketplace add yugabyte/meko-mcp-server --scope user` |
 | 4 | Install skills plugin | `claude plugin install meko-agent-skills --scope user` |
 | 5 | Validate setup | Config check via `claude mcp list`, MCP `initialize` handshake, `tools/list` verification |
 
@@ -288,7 +292,7 @@ memory errs:  0                (failed memory_add calls; re-run with --force to
 |---|-----------|-----------|
 | **URL** | Provided by app.mekodev.com > Datapacks > Connect | `http://localhost:8000/mcp` |
 | **Authentication** | Requires `--api-key` or `$MEKO_API_KEY` env var | None |
-| **MCP registration** | Includes `-H "API_KEY: <key>"` header | No auth header |
+| **MCP registration** | Includes `-H "Authorization: Bearer <key>"` header | No auth header |
 | **Hook env vars** | Both `MEKO_MCP_URL` and `MEKO_API_KEY` written to settings | Only `MEKO_MCP_URL` written |
 | **Infrastructure** | Hosted, no local setup needed | Requires `docker compose up -d` running the Meko stack |
 | **Use case** | Production, team collaboration | Development, testing |
@@ -457,7 +461,7 @@ node installer/bin/create-meko-setup.mjs --uninstall --verbose
 | # | Scenario | Steps | Expected Result |
 |---|----------|-------|-----------------|
 | M1 | Fresh local install | `node installer/bin/create-meko-setup.mjs --local --yes` with docker stack running | All 5 steps pass, validation shows 3 green checks |
-| M2 | Fresh cloud install | Run interactively, provide Cloud Meko URL + API key | MCP registered with API_KEY header, env vars set, validation passes |
+| M2 | Fresh cloud install | Run interactively, provide Cloud Meko URL + API key | MCP registered with `Authorization: Bearer` header, env vars set, validation passes |
 | M3 | Existing config | Run installer when `meko` MCP is already registered | Prompts to overwrite; answering No keeps existing config |
 | M4 | No claude CLI | Run on a machine without `claude` in PATH | Exits with error message and install link |
 | M5 | Server unreachable | Install with `--skip-validation`, then re-run without it | Install succeeds; validation warns about connectivity |

package/assets/hooks-handlers/lib/capture.js

@@ -274,7 +274,7 @@ function mcpPost(jsonBody) {
       "Content-Length": Buffer.byteLength(body),
     };
     if (MEKO_API_KEY) {
-      headers["API_KEY"] = MEKO_API_KEY;
+      headers["Authorization"] = `Bearer ${MEKO_API_KEY}`;
     }
     if (mcpSessionId) {
       headers["Mcp-Session-Id"] = mcpSessionId;

package/bin/create-meko-setup.mjs

@@ -10,6 +10,7 @@ import { askChoice, askMultiChoice, askText, askSecret, askYesNo, close as close
 import { banner, error, dim } from '../lib/logger.mjs';
 import { isPackagedInstall, selfInvocation } from '../lib/clients/common.mjs';
 import { getClientAdapters } from '../lib/clients/index.mjs';
+import { parseClientList } from '../lib/clients/aliases.mjs';
 import { startMigration, runChildMigration, readStatus, stopMigration } from '../lib/migrate.mjs';
 
 // ---------------------------------------------------------------------------
@@ -90,6 +91,7 @@ Examples:
 
 Options:
   --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor.
+                        "claude" is accepted as an alias for claude-code.
                         Comma-separated, or "all" to target every supported client (default: claude-code)
   --url <url>           MCP server URL (from app.mekodev.com > Datapacks > Connect)
   --api-key <key>       API key for Cloud Meko authentication
@@ -131,17 +133,12 @@ function isCloudUrl(url) {
 /**
  * Parse --client into a deduplicated list of client IDs.
  * Accepts a single value, a comma-separated list, or the keyword "all".
+ * Aliases (see CLIENT_ALIASES in ../lib/clients.mjs) are resolved before the
+ * validity check so the cloud UI snippet (`--client claude`) works verbatim.
  * Returns { clients, invalid } where invalid lists any unknown tokens.
  */
 function parseClients(raw) {
-  const trimmed = (raw ?? '').trim();
-  if (!trimmed) return { clients: ['claude-code'], invalid: [] };
-  if (trimmed.toLowerCase() === 'all') return { clients: [...ALL_CLIENTS], invalid: [] };
-
-  const tokens = trimmed.split(',').map((t) => t.trim()).filter(Boolean);
-  const invalid = tokens.filter((t) => !ALL_CLIENTS.includes(t));
-  const clients = [...new Set(tokens.filter((t) => ALL_CLIENTS.includes(t)))];
-  return { clients, invalid };
+  return parseClientList(raw, ALL_CLIENTS);
 }
 
 function isValidScope(scope) {
@@ -374,6 +371,8 @@ async function main() {
     // Step 1 — connection type. Local Meko only makes sense for users who
     // have the server repo cloned locally (docker-compose stack on :8000);
     // npm/npx users have no way to run it, so hide the option for them.
+    // When only Cloud is available, skip the prompt entirely — asking to
+    // pick between one option is pointless UX.
     const connectionOptions = [
       { label: 'Cloud Meko', description: 'Hosted at mekodev.com (requires URL + API key)' },
     ];
@@ -383,7 +382,10 @@ async function main() {
         description: 'Local stack at localhost:8000',
       });
     }
-    const connectionType = await askChoice('Connection type:', connectionOptions);
+    const connectionType =
+      connectionOptions.length === 1
+        ? connectionOptions[0].label
+        : await askChoice('Connection type:', connectionOptions);
 
     if (connectionType === 'Cloud Meko') {
       // Step 2 — MCP URL

package/lib/clients/aliases.mjs

@@ -0,0 +1,30 @@
+// Tokens the cloud UI or older docs pass on `--client` that should map to a
+// canonical adapter ID. Kept in a tiny, side-effect-free module so tests can
+// import it without booting the bin entry point.
+export const CLIENT_ALIASES = Object.freeze({
+  claude: "claude-code",
+});
+
+/**
+ * Parse a `--client` argument into a deduplicated list of client IDs.
+ *
+ * @param {string|null|undefined} raw - Raw CLI argument value.
+ * @param {string[]} allClients - Canonical IDs accepted by the installer.
+ * @returns {{clients: string[], invalid: string[]}}
+ */
+export function parseClientList(raw, allClients) {
+  const trimmed = (raw ?? "").trim();
+  if (!trimmed) return { clients: ["claude-code"], invalid: [] };
+  if (trimmed.toLowerCase() === "all") {
+    return { clients: [...allClients], invalid: [] };
+  }
+
+  const tokens = trimmed
+    .split(",")
+    .map((t) => t.trim())
+    .filter(Boolean)
+    .map((t) => CLIENT_ALIASES[t] ?? t);
+  const invalid = tokens.filter((t) => !allClients.includes(t));
+  const clients = [...new Set(tokens.filter((t) => allClients.includes(t)))];
+  return { clients, invalid };
+}

package/lib/clients/claude-code.mjs

@@ -89,14 +89,14 @@ export function createClaudeCodeAdapter(options = {}) {
     buildRegisterCommand({ name, url, scope, apiKey }) {
       let cmd = `claude mcp add ${name} ${url} --transport http --scope ${scope}`;
       if (apiKey) {
-        cmd += ` -H "API_KEY: ${apiKey}"`;
+        cmd += ` -H "Authorization: Bearer ${apiKey}"`;
       }
       return cmd;
     },
     buildRegisterDisplayCommand({ name, url, scope, apiKey }) {
       let displayCmd = `claude mcp add ${name} ${url} --transport http --scope ${scope}`;
       if (apiKey) {
-        displayCmd += ` -H "API_KEY: ${redactKey(apiKey)}"`;
+        displayCmd += ` -H "Authorization: Bearer ${redactKey(apiKey)}"`;
       }
       return displayCmd;
     },
@@ -145,8 +145,13 @@ export function createClaudeCodeAdapter(options = {}) {
       }
     },
     installSkills({ scope, dryRun, verbose, log }) {
+      // NB: we deliberately do NOT pass --sparse. Claude CLI's sparse
+      // path filter silently produces an empty clone for our layout,
+      // leaving the marketplace.json missing. Full clone is small
+      // (~few MB, mostly markdown) and is the only way that reliably
+      // succeeds today.
       const marketplaceCmd =
-        `claude plugin marketplace add yugabyte/meko-mcp-server --sparse .claude-plugin,skills --scope ${scope}`;
+        `claude plugin marketplace add yugabyte/meko-mcp-server --scope ${scope}`;
       const pluginCmd = `claude plugin install meko-agent-skills --scope ${scope}`;
 
       if (dryRun) {

package/lib/clients/claude-desktop.mjs

@@ -24,13 +24,13 @@ import { getRepoRoot, run } from "./common.mjs";
  *   "meko": {
  *     "command": "npx",
  *     "args": ["-y", "mcp-remote", "<url>", "--transport", "http-only",
- *              "--header", "API_KEY:${MEKO_API_KEY}"],
+ *              "--header", "Authorization:Bearer ${MEKO_API_KEY}"],
  *     "env": { "MEKO_API_KEY": "<key>" }
  *   }
  *
  * The header uses the `${ENV_VAR}` interpolation form (documented by
- * mcp-remote) with no space around the colon — some clients mis-parse
- * space-containing `--header` args.
+ * mcp-remote) with no space around the colon after the header name —
+ * some clients mis-parse space-containing `--header` args.
  *
  * installSkills() runs skills/scripts/package-desktop-skill.sh to build the
  * .skill bundle and prints import instructions. Desktop has no programmatic
@@ -228,10 +228,11 @@ export function buildMcpRemoteEntry({ url, apiKey }) {
   const args = ["-y", "mcp-remote", url, "--transport", "http-only"];
   const entry = { command: "npx", args };
   if (apiKey) {
-    // `API_KEY:${MEKO_API_KEY}` with no space around the colon — mcp-remote
-    // docs call out a spacing bug in some clients' arg parsing. The header
-    // name matches what the Meko server expects (see capture.js mcpPost).
-    args.push("--header", "API_KEY:${MEKO_API_KEY}");
+    // `Authorization:Bearer ${MEKO_API_KEY}` with no space around the colon
+    // after the header name — mcp-remote docs call out a spacing bug in some
+    // clients' arg parsing. The space between `Bearer` and the token value
+    // is part of the header value and is required by RFC 6750.
+    args.push("--header", "Authorization:Bearer ${MEKO_API_KEY}");
     entry.env = { MEKO_API_KEY: apiKey };
   }
   return entry;

package/lib/clients/cursor.mjs

@@ -81,7 +81,7 @@ export function createCursorAdapter(customPaths = {}) {
         log.dim(`  Would update ${mcpPath}:`);
         log.dim(`    mcpServers.${name}.url = ${url}`);
         if (apiKey) {
-          log.dim("    mcpServers.<name>.headers.API_KEY = <set>");
+          log.dim("    mcpServers.<name>.headers.Authorization = <set>");
         }
         return;
       }
@@ -92,7 +92,7 @@ export function createCursorAdapter(customPaths = {}) {
       }
       const server = { url };
       if (apiKey) {
-        server.headers = { API_KEY: apiKey };
+        server.headers = { Authorization: `Bearer ${apiKey}` };
       }
       cfg.mcpServers[name] = server;
       writeJsonFile(mcpPath, cfg);

package/lib/mcp-transport.mjs

@@ -17,7 +17,7 @@ export const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
  *
  * @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} apiKey - Optional API key, sent as `Authorization: Bearer <key>`.
  * @param {string|null} sessionId - Optional `Mcp-Session-Id` to include.
  * @param {object} [opts]
  * @param {number} [opts.timeoutMs] - Override per-request timeout.
@@ -34,7 +34,7 @@ export function jsonRpcRequest(url, payload, apiKey, sessionId, opts = {}) {
       Accept: "application/json",
     };
     if (apiKey) {
-      headers["API_KEY"] = apiKey;
+      headers["Authorization"] = `Bearer ${apiKey}`;
     }
     if (sessionId) {
       headers["Mcp-Session-Id"] = sessionId;

package/lib/migrate/mcp-client.mjs

@@ -140,7 +140,7 @@ export class McpClient {
 
     if (res.statusCode === 401 || res.statusCode === 403) {
       const e = new Error(
-        `Auth rejected by server (HTTP ${res.statusCode}). Check API_KEY.`,
+        `Auth rejected by server (HTTP ${res.statusCode}). Check Authorization header / API key.`,
       );
       e.statusCode = res.statusCode;
       throw e;

package/lib/migrate/orchestrator.mjs

@@ -283,11 +283,17 @@ export async function runMigration(opts) {
       const [, memRes] = await Promise.all([addMsgPromise, memPromise]);
       messagesSent++;
       if (!opts.noExtract) {
-        if (memRes && memRes.ok) {
+        if (memRes && memRes.ok && !isErrorText(memRes.text)) {
           memoryPairsSent++;
           prog.counts.memoryPairsSent++;
         } else if (memRes) {
           prog.counts.memoryErrors++;
+          log.warn("memory_add_failed", {
+            agentId: ref.agentId,
+            sessionUuid: ref.sessionUuid,
+            userUuid: ex.user_uuid,
+            detail: errorDetail(memRes),
+          });
         }
       }
       lastUuid = ex.user_uuid;
@@ -361,7 +367,7 @@ export async function runMigration(opts) {
       metadata: JSON.stringify(item.metadata),
     }, { fireAndForget: true });
 
-    if (res.ok) {
+    if (res.ok && !isErrorText(res.text)) {
       state.markMemory(st, item.agentId, item.hash, {
         memoryId: extractId(res.text) || "",
         name: item.name,
@@ -370,7 +376,12 @@ export async function runMigration(opts) {
       prog.counts.memoriesFromMD++;
     } else {
       prog.counts.memoryErrors++;
-      log.warn("memory_md_failed", { agentId: item.agentId, name: item.name, error: res.error?.message });
+      log.warn("memory_md_failed", {
+        agentId: item.agentId,
+        name: item.name,
+        error: res.error?.message,
+        detail: errorDetail(res),
+      });
     }
     if (++opsSinceFlush >= FLUSH_EVERY) flushState();
     writeProgress();
@@ -441,3 +452,34 @@ function extractId(text) {
     return null;
   }
 }
+
+/**
+ * The MCP transport returns `{ok:true}` whenever the HTTP call itself
+ * succeeded, even if the tool's body encoded a failure. memory_add in
+ * older server builds returned plain "Error adding memory: ..." strings
+ * on exception; newer builds return JSON `{"error":"memory_add_failed",...}`.
+ * Either way, the text content is the authoritative success signal.
+ */
+function isErrorText(text) {
+  if (!text) return false;
+  const trimmed = text.trim();
+  if (trimmed.startsWith("Error adding memory")) return true;
+  if (trimmed.startsWith("{")) {
+    try {
+      const obj = JSON.parse(trimmed);
+      if (obj && typeof obj === "object" && obj.error) return true;
+    } catch { /* not JSON; fall through */ }
+  }
+  return false;
+}
+
+function errorDetail(res) {
+  if (!res) return null;
+  if (res.error?.message) return res.error.message;
+  if (!res.text) return null;
+  try {
+    const obj = JSON.parse(res.text);
+    if (obj?.error) return obj.detail || obj.error;
+  } catch { /* not JSON */ }
+  return res.text.slice(0, 200);
+}

package/lib/prompt.mjs

@@ -7,6 +7,7 @@
  */
 
 import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
 
 // ---------------------------------------------------------------------------
 // Lazy readline singleton
@@ -155,93 +156,52 @@ export async function askText(questionText, defaultValue) {
 // ---------------------------------------------------------------------------
 
 /**
- * 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).
+ * Hidden input — uses a muted Writable so readline never echoes typed
+ * characters. Matches the behavior of `sudo`, `ssh`, `git`, and `npm login`:
+ * the cursor sits in place while you type or paste, then a newline appears
+ * on submit. No `*` masking (we tried that for four releases and shipped a
+ * security bug each time — readline already handles ANSI sequences,
+ * bracketed paste, backspace, arrows, and UTF-8 correctly).
  *
  * @param {string} questionText
  * @returns {Promise<string>}
  */
 export async function askSecret(questionText) {
-  // Print the prompt without a trailing newline.
-  process.stdout.write(`  ${questionText} `);
-
-  // Pause the singleton readline so its data listener doesn't echo each
-  // keystroke in parallel with our manual "*" write. Without this, users
-  // see `d*j*f*k*...` (raw char + mask interleaved) and backspace fights
-  // with readline over cursor position.
-  const pausedRL = rl;
-  if (pausedRL) pausedRL.pause();
+  // Close the visible singleton so the muted readline gets exclusive stdin.
+  // getRL() recreates it cleanly on the next askText/askYesNo call.
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
 
-  return new Promise((resolve, reject) => {
-    let secret = "";
-    const stdin = process.stdin;
+  // Print the prompt through the real stdout so the user sees it.
+  process.stdout.write(`  ${questionText} `);
 
-    // 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();
-        if (pausedRL) pausedRL.resume();
-        resolve(answer.trim());
-      });
-      return;
-    }
+  // Muted Writable: swallows every byte readline tries to echo. The prompt
+  // has already been written above; from here on, silence until we print
+  // our own newline after Enter.
+  const muted = new Writable({
+    write(_chunk, _enc, cb) { cb(); },
+  });
 
-    const wasRaw = stdin.isRaw;
-    stdin.setRawMode(true);
-    stdin.resume();
-    stdin.setEncoding("utf8");
+  const secretRL = createInterface({
+    input: process.stdin,
+    output: muted,
+    terminal: true,
+  });
 
-    /** Restore stdin state and print a newline after the masked input. */
-    function cleanup() {
-      stdin.setRawMode(wasRaw);
-      stdin.removeListener("data", onData);
+  return new Promise((resolve, reject) => {
+    secretRL.once("SIGINT", () => {
+      secretRL.close();
       process.stdout.write("\n");
-      if (pausedRL) pausedRL.resume();
-    }
-
-    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("*");
-    }
+      reject(new Error("User cancelled"));
+    });
 
-    stdin.on("data", onData);
+    secretRL.question("", (answer) => {
+      secretRL.close();
+      process.stdout.write("\n");
+      resolve(answer);
+    });
   });
 }
 

package/lib/validate.mjs

@@ -74,7 +74,7 @@ export async function validateConfig(serverName) {
  * 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).
+ * @param {string|null} apiKey - Optional API key (sent as `Authorization: Bearer <key>`).
  * @returns {Promise<{ok: boolean, message: string, sessionId?: string}>}
  */
 export async function validateConnectivity(url, apiKey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yugabytedb/meko-mcp",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "Single-line installer for Meko MCP Server across Claude and Cursor clients",
   "type": "module",
   "bin": {