@yugabytedb/meko-mcp 1.1.0 → 2.0.0

package/assets/skills/meko-select-datapack-desktop/references/troubleshooting.md

@@ -0,0 +1,66 @@
+# Troubleshooting — meko-select-datapack-desktop
+
+## Symptom: I pinned a datapack but the next Meko call doesn't use it
+
+**Likely causes**
+
+1. **You forgot the per-turn `memory_search`.** Desktop has no SessionStart hook, so the skill teaches you to read the pin yourself at the top of every Meko-touching turn. If you skip that lookup, you'll send Meko calls with no `datapack_id` and the server resolves the default. Add the lookup; cache the result for the rest of the turn.
+2. **You used `agent_id="meko_agent"` for the pin write or read.** The pin lives under `agent_id="claude_desktop"`, exclusively. Cross-project facts go under `meko_agent`, but the pin is a Desktop-specific preference and should stay scoped.
+3. **The pin write failed silently.** Always verify-after-write — call `memory_search` for `meko_active_datapack` immediately after `memory_add` and confirm the row appears. If it doesn't, the write was lost (latency, server error, wrong scope) and the pin doesn't actually exist.
+
+## Symptom: `memory_search` returns multiple pin memories
+
+You (or an earlier run) created duplicates by using `memory_add` instead of `memory_update` on a switch. Resolution:
+
+1. Pick the most recent (highest `selected_at` in the text body).
+2. `memory_delete_by_id` the others.
+3. From now on, switch via `memory_update` on the surviving id — never `memory_add`.
+
+The cookbook's Flow 2 demonstrates the correct switch path.
+
+## Symptom: A pinned datapack returns "not found" when used
+
+The pin became stale — the datapack was deleted in another client. Tell the user:
+
+```
+The pinned datapack `<name>` (`<id>`) no longer exists on the server.
+Run `meko-select-datapack-desktop` to pick a fresh one, or `clear` to unpin.
+```
+
+Then either re-run the skill or delete the pin memory. Do not silently fall back to the default — the user explicitly asked for a specific datapack.
+
+## Symptom: Substring search matches multiple datapacks
+
+Never auto-pick when there's ambiguity. Re-render just the matching rows numbered from 1, and ask the user to pick a number from the filtered subset. Same as the Claude Code variant.
+
+## Symptom: `datapack_list` returns an empty array
+
+The user has zero datapacks. Print:
+
+```
+You don't have any datapacks yet. Create one with:
+
+  datapack_create(scope="admin", name="<your-datapack-name>")
+
+Or visit the Meko Cloud console (Datapacks → New datapack).
+```
+
+Stop. Don't `memory_add` an empty pin.
+
+## Symptom: User typed `cancel` after the table rendered
+
+Leave the existing pin memory alone. Print:
+
+```
+Cancelled. Active datapack unchanged.
+```
+
+Do NOT delete on `cancel` — that's `clear`'s job.
+
+## Symptom: `memory_search` for the pin times out
+
+Memory tools are slow on prod (search 2-6s observed). If the search exceeds a reasonable budget, fall back to the server default for that single call and tell the user *"Couldn't read the active-datapack pin within budget — using server default for this Meko call."* Don't guess a UUID; don't silently retry indefinitely.
+
+## Symptom: The pin survived a `claude_desktop` profile reset / app reinstall
+
+That's expected — the pin is a server-side memory, not local state. To explicitly forget across reinstalls, run the skill with `clear` BEFORE wiping local state, or `memory_delete_by_id` the pin row directly.

package/bin/create-meko-setup.mjs

@@ -25,9 +25,11 @@ const options = {
   scope:              { type: 'string',  default: 'user' },
   name:               { type: 'string',  default: 'meko' },
   client:             { type: 'string',  default: 'claude-code' },
-  'cursor-hook-mode': { type: 'string',  default: 'hybrid' },
+  'cursor-hook-mode': { type: 'string',  default: 'native' },
   'skip-skills':      { type: 'boolean', default: false },
   'skip-validation':  { type: 'boolean', default: false },
+  statusline:         { type: 'boolean', default: false },
+  'no-statusline':    { type: 'boolean', default: false },
   'no-canary':        { type: 'boolean', default: false },
   'dry-run':          { type: 'boolean', default: false },
   'check-updates':    { type: 'boolean', default: false },
@@ -109,8 +111,13 @@ Options:
                         codex always installs at user scope (no project-level
                         config); --scope=project degrades with a warning.
   --name <name>         MCP server name in config (default: meko)
-  --cursor-hook-mode    Cursor hook mode: native, claude-compat, hybrid (default: hybrid)
+  --cursor-hook-mode    Cursor hook mode: native or claude-compat (default: native)
   --skip-skills         Skip plugin and skills installation
+  --statusline          Wire the Meko datapack-pin indicator into Claude Code's
+                        statusline (composes with any existing statusLine).
+                        Default: ON under --yes, prompted otherwise.
+                        Claude Code only.
+  --no-statusline       Skip statusline wiring even under --yes.
   --skip-validation     Skip post-install validation
   --no-canary           Skip the canary datapack_list call. The
                         connectivity + tools/list checks still run.
@@ -218,7 +225,7 @@ function detectInstalledClients() {
 }
 
 function isValidCursorHookMode(mode) {
-  return ['native', 'claude-compat', 'hybrid'].includes(mode);
+  return ['native', 'claude-compat'].includes(mode);
 }
 
 /**
@@ -391,13 +398,18 @@ async function main() {
     process.exit(0);
   }
   if (!isValidCursorHookMode(flags['cursor-hook-mode'])) {
-    error(`Unknown --cursor-hook-mode "${flags['cursor-hook-mode']}". Valid values: native, claude-compat, hybrid.`);
+    error(`Unknown --cursor-hook-mode "${flags['cursor-hook-mode']}". Valid values: native, claude-compat.`);
     process.exit(1);
   }
 
   let url    = flags.url    ?? null;
   let apiKey = normalizeApiKey(flags['api-key']);
   let skipSkills = flags['skip-skills'];
+  // Statusline: --no-statusline always wins. --statusline forces on. Otherwise
+  // default to on under --yes (programmatic), and prompt with Y default
+  // interactively. Resolved later after the interactive prompts since the
+  // flag may flip in the interactive flow.
+  let installStatusline = !flags['no-statusline'] && (flags.statusline || flags.yes);
   // Tracks whether the full interactive flow already prompted for the API
   // key. The Cloud-URL fallback below should only run for the
   // semi-interactive `--url ... --client ...` paste path — otherwise
@@ -498,6 +510,19 @@ async function main() {
     if (!installSkills) {
       skipSkills = true;
     }
+
+    // Step 5 — statusline (Claude Code only). --no-statusline / --statusline
+    // skip the prompt; otherwise ask with Y default. The prompt only matters
+    // when at least one selected client is claude-code; for desktop / cursor /
+    // codex the install() orchestrator simply skips the step (the adapters
+    // don't expose installStatusline()).
+    if (!flags['no-statusline'] && !flags.statusline && clients.includes('claude-code')) {
+      installStatusline = await askYesNo(
+        'Show the active Meko datapack in Claude Code\'s statusline? ' +
+        '(composes with any existing statusLine — non-destructive)',
+        true,
+      );
+    }
   }
 
   // Validation — URL must be set by now
@@ -544,6 +569,10 @@ async function main() {
         skipSkills,
         skipValidation: flags['skip-validation'],
         skipCanary:     flags['no-canary'],
+        // Statusline is Claude Code only. For other clients the orchestrator
+        // skips the step regardless of the flag because the adapter doesn't
+        // expose installStatusline(); explicit guard keeps step counts honest.
+        installStatusline: client === 'claude-code' && installStatusline,
         dryRun:         flags['dry-run'],
         verbose:        flags.verbose,
         yes:            flags.yes,

package/lib/clients/claude-code.mjs

@@ -1,4 +1,4 @@
-import { mkdirSync } from "node:fs";
+import { chmodSync, copyFileSync, mkdirSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -14,8 +14,10 @@ import {
 } from "../config.mjs";
 import { detectClaude, detectExistingMeko, getClaudeCodeConfigPath } from "../detect.mjs";
 import {
+  MEKO_MCP_USER_AGENT,
   redactKey,
   resolveHooksRoot,
+  resolveStatuslineSource,
   run,
   shellQuote,
   writeInstallerMarker,
@@ -44,15 +46,23 @@ const MEKO_MARKETPLACE_NAME = "meko-agent-skills";
 
 // Meko MCP tools to union into `permissions.allow` so Claude Code resolves
 // them without the deferred-tools ToolSearch round-trip (issue #5). The set
-// is intentionally tight — only tools the agent calls proactively per
-// the meko-mcp-tools skill — to avoid bloating every user's settings.
+// is intentionally tight — the memory/conversation tools the agent actually
+// reaches for per the meko-mcp-tools skill — to avoid bloating every user's
+// settings.
+//
+// `memory_add` stays on this list even though the skill no longer tells the
+// agent to fire it proactively (server-side extraction now captures
+// conversationally-stated facts automatically). It's kept because the skill
+// still uses memory_add for the narrow explicit-save cases — "remember this",
+// output-only/tool-derived facts, and overwriting corrections — and pre-
+// allowing it keeps those calls prompt-free. `conversation_add_message` is the
+// tool that now drives capture-plus-extraction, so it must resolve instantly.
 //
 // NOTE: `permissions.allow` is verified to cover user-prompt bypass. Whether
 // it also bypasses the deferred-tools schema-fetch gate must be re-verified
 // empirically before this flag is considered load-bearing for #5. Tracked
 // as Phase 10.1 in skills/TEST_PLAN.md.
 const MEKO_ALWAYS_AVAILABLE_TOOLS = [
-  "mcp__meko__db_summarize_database",
   "mcp__meko__memory_add",
   "mcp__meko__memory_search",
   "mcp__meko__memory_get_all",
@@ -125,7 +135,8 @@ export function createClaudeCodeAdapter(options = {}) {
     buildRegisterCommand({ name, url, scope, apiKey }) {
       let cmd =
         `claude mcp add --transport http --scope ${shellQuote(scope)} ` +
-        `${shellQuote(name)} ${shellQuote(url)}`;
+        `${shellQuote(name)} ${shellQuote(url)} ` +
+        `--header ${shellQuote(`User-Agent: ${MEKO_MCP_USER_AGENT}`)}`;
       if (apiKey) {
         cmd += ` --header ${shellQuote(`Authorization: Bearer ${apiKey}`)}`;
       }
@@ -207,14 +218,85 @@ export function createClaudeCodeAdapter(options = {}) {
         );
       }
     },
+    /**
+     * Wire the Meko datapack-pin statusline contribution into ~/.claude/settings.json.
+     *
+     * Composable: if the user already has a `statusLine.command`, that command
+     * is preserved as the inner command and our wrapper appends `Meko: <name>`
+     * after its output. Idempotent: if our wrapper is already wired, no-op.
+     *
+     * Restore-on-uninstall: the original command is preserved in
+     * settings.json under `_meko.statusLine.previousCommand` so `uninstall()`
+     * can restore it. Absent that key (fresh install), uninstall removes the
+     * whole `statusLine` block.
+     */
+    installStatusline({ dryRun, verbose, log, settingsPath }) {
+      const scriptSource = resolveStatuslineSource();
+      const scriptDest = join(homedir(), ".claude", "meko-statusline.sh");
+
+      const existing = readJsonFile(settingsPath) ?? {};
+      const existingCmd =
+        existing?.statusLine?.type === "command" && typeof existing?.statusLine?.command === "string"
+          ? existing.statusLine.command.trim()
+          : "";
+
+      // Detect prior install of our wrapper. Re-wiring is a no-op for the
+      // command (already points at the wrapper); we still re-copy the script
+      // so a refreshed installer ships an updated copy.
+      const alreadyWired = existingCmd.includes("meko-statusline.sh");
+      const innerCmd =
+        alreadyWired
+          ? (existing?._meko?.statusLine?.previousCommand ?? "")
+          : existingCmd;
+
+      const wrapperCmd = innerCmd
+        ? `${shellQuote(scriptDest)} --inner-cmd ${shellQuote(innerCmd)}`
+        : shellQuote(scriptDest);
+
+      if (dryRun) {
+        log.dim(`  Would copy ${scriptSource} → ${scriptDest}`);
+        log.dim(`  Would set ${settingsPath} statusLine.command = ${wrapperCmd}`);
+        if (innerCmd) log.dim(`    (preserving prior inner command: ${innerCmd})`);
+        return;
+      }
+
+      mkdirSync(join(homedir(), ".claude"), { recursive: true });
+      copyFileSync(scriptSource, scriptDest);
+      chmodSync(scriptDest, 0o755);
+
+      const patch = {
+        statusLine: { type: "command", command: wrapperCmd },
+      };
+      // Stash the inner command so uninstall can restore it. Only write this
+      // namespace on the first install (when alreadyWired is false), so a
+      // re-install never overwrites the genuine original with our wrapper.
+      if (!alreadyWired) {
+        patch._meko = { statusLine: { previousCommand: innerCmd || null } };
+      }
+      mergeSettings(settingsPath, patch);
+
+      if (verbose) {
+        log.dim(`  Statusline script: ${scriptDest}`);
+        log.dim(`  Wrapper command: ${wrapperCmd}`);
+        if (innerCmd) log.dim(`  Inner command preserved: ${innerCmd}`);
+        if (alreadyWired) log.dim(`  (refreshed existing wrapper, no settings change beyond script copy)`);
+      }
+    },
     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.
+      // Marketplace source is normally the upstream GitHub repo. A dev/e2e
+      // override lets a test install the plugin from a LOCAL working-tree
+      // checkout (a directory path) so unreleased skill changes can be
+      // exercised end-to-end before they land on `yugabyte/meko-mcp-server`.
+      // Default is unchanged; only set MEKO_PLUGIN_MARKETPLACE_SOURCE in tests.
+      const marketplaceSource =
+        process.env.MEKO_PLUGIN_MARKETPLACE_SOURCE || "yugabyte/meko-mcp-server";
       const marketplaceCmd =
-        `claude plugin marketplace add yugabyte/meko-mcp-server --scope ${scope}`;
+        `claude plugin marketplace add ${shellQuote(marketplaceSource)} --scope ${shellQuote(scope)}`;
       // `claude plugin list` dropped --scope in CLI 2.1.x; it prints all
       // scopes. The match-by-token regex used below is scope-agnostic by
       // design — `plugin update` failing with "not found" on a
@@ -393,6 +475,44 @@ export function createClaudeCodeAdapter(options = {}) {
         results.push({ key: "hooks", ok: false, message: `Could not prune Meko hook entries: ${err.message}` });
       }
 
+      try {
+        // Restore the user's prior statusLine.command (if any) and remove our
+        // bookkeeping. If no prior command was preserved, remove the whole
+        // statusLine block — installStatusline() only added it on first
+        // install, so we own it cleanly.
+        const cfg = readJsonFile(settingsPath) ?? {};
+        const wrapperWired =
+          cfg?.statusLine?.type === "command" &&
+          typeof cfg?.statusLine?.command === "string" &&
+          cfg.statusLine.command.includes("meko-statusline.sh");
+        if (wrapperWired) {
+          const prev = cfg?._meko?.statusLine?.previousCommand;
+          if (typeof prev === "string" && prev.length > 0) {
+            cfg.statusLine = { type: "command", command: prev };
+            results.push({ key: "statusline", ok: true, message: "Restored prior statusLine.command." });
+          } else {
+            delete cfg.statusLine;
+            results.push({ key: "statusline", ok: true, message: "Removed Meko statusLine wrapper." });
+          }
+          if (cfg?._meko?.statusLine) {
+            delete cfg._meko.statusLine;
+            if (cfg._meko && Object.keys(cfg._meko).length === 0) delete cfg._meko;
+          }
+          writeJsonFile(settingsPath, cfg);
+          // Remove the copied script too — installStatusline() owns it, so
+          // leaving it behind would be a stale orphan after uninstall.
+          try {
+            unlinkSync(join(homedir(), ".claude", "meko-statusline.sh"));
+          } catch {
+            // Best-effort: absent file (ENOENT) or unreadable dir is fine.
+          }
+        } else {
+          results.push({ key: "statusline", ok: false, message: "Statusline wrapper was not installed (nothing to remove)." });
+        }
+      } catch (err) {
+        results.push({ key: "statusline", ok: false, message: `Could not restore statusLine: ${err.message}` });
+      }
+
       try {
         // Qualified plugin@marketplace form — CLI 2.1.x rejects the bare
         // name (issue #63). Before: `catch` swallowed every failure as
@@ -460,6 +580,13 @@ export function createClaudeCodeAdapter(options = {}) {
       }
 
       const authHeader = getHeader(entry.headers, "Authorization");
+      const userAgent = getHeader(entry.headers, "User-Agent");
+      if (!userAgent) {
+        return {
+          ok: false,
+          message: `Server "${serverName}" in ${configPath} is missing the User-Agent header required by the Cloud WAF.`,
+        };
+      }
       if (apiKey) {
         const expected = `Bearer ${apiKey}`;
         if (authHeader !== expected) {

package/lib/clients/claude-desktop.mjs

@@ -9,8 +9,9 @@ import {
   removeKeys,
 } from "../config.mjs";
 import {
+  MEKO_MCP_USER_AGENT,
+  getAssetRoot,
   getInstallerVersion,
-  getRepoRoot,
   markerIsStale,
   readInstallerMarker,
   run,
@@ -31,6 +32,7 @@ import {
  *   "meko": {
  *     "command": "npx",
  *     "args": ["-y", "mcp-remote", "<url>", "--transport", "http-only",
+ *              "--header", "User-Agent:meko-mcp-installer/1.0 (...)",
  *              "--header", "Authorization:Bearer ${MEKO_API_KEY}"],
  *     "env": { "MEKO_API_KEY": "<key>" }
  *   }
@@ -39,13 +41,16 @@ import {
  * 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
- * skill install API — the user drags the .skill into the app.
+ * installSkills() runs scripts/package-desktop-skill.sh under the resolved
+ * asset root to build the .skill bundle and prints import instructions.
+ * Desktop has no programmatic skill install API — the user drags the .skill
+ * into the app. The asset root is `installer/assets/` for packaged installs
+ * (npx) and `<repo>/skills/` for source checkouts; both layouts share the
+ * same shape so the script can be invoked the same way.
  */
 export function createClaudeDesktopAdapter(options = {}) {
   const configPathResolver = options.getConfigPath ?? getClaudeDesktopConfigPath;
-  const repoRootResolver = options.getRepoRoot ?? getRepoRoot;
+  const assetRootResolver = options.getAssetRoot ?? getAssetRoot;
   const packageRunner = options.runPackageScript ?? defaultRunPackageScript;
   const npxProber = options.probeNpx ?? defaultProbeNpx;
 
@@ -119,16 +124,20 @@ export function createClaudeDesktopAdapter(options = {}) {
       mergeSettings(path, { mcpServers: { [name]: server } });
     },
     setHookEnvironment({ dryRun, log }) {
-      // Claude Desktop has no hook API; the skill carries the proactive-memory
-      // behavior instead. Nothing to write here.
+      // Claude Desktop has no hook API, so the skill mandates per-turn
+      // conversation_add_message posting (the server extracts memories from
+      // those posts); proactive memory_add is no longer the model. Nothing to
+      // write here.
       if (dryRun) {
         log.dim("  No hook environment required for Claude Desktop (skill-driven).");
       }
     },
     installSkills({ dryRun, log }) {
-      const repoRoot = repoRootResolver();
-      const script = join(repoRoot, "skills", "scripts", "package-desktop-skill.sh");
-      const output = join(repoRoot, "skills", "meko-mcp-tools-desktop.skill");
+      const assetRoot = assetRootResolver();
+      const script = join(assetRoot, "scripts", "package-desktop-skill.sh");
+      const output = join(assetRoot, "meko-mcp-tools-desktop.skill");
+      const selectOutput = join(assetRoot, "meko-select-datapack-desktop.skill");
+      const outputs = [output, selectOutput];
       // The .skill output is a ZIP file, so we can't drop a marker inside it.
       // Stamp the marker in the parent dir instead — it signals which
       // installer version produced the bundle sitting alongside it, so a
@@ -138,9 +147,11 @@ export function createClaudeDesktopAdapter(options = {}) {
 
       if (dryRun) {
         log.dim(`  Would run: bash ${script}`);
-        log.dim(`  Would produce: ${output}`);
+        for (const skillOutput of outputs) {
+          log.dim(`  Would produce: ${skillOutput}`);
+        }
         log.dim(`  Would write .meko-installer marker (version=${currentVersion}) in ${markerDir}`);
-        return { marketplace: "skipped", skills: "dry-run", output };
+        return { marketplace: "skipped", skills: "dry-run", output, outputs };
       }
 
       if (!existsSync(script)) {
@@ -155,7 +166,7 @@ export function createClaudeDesktopAdapter(options = {}) {
       // re-drag the .skill into Claude Desktop's Extensions panel; we can't do
       // that step for them. Keep rebuilding either way.
       const existingMarker = readInstallerMarker(markerDir);
-      if (existsSync(output) && existingMarker && markerIsStale(markerDir, currentVersion)) {
+      if (outputs.some((skillOutput) => existsSync(skillOutput)) && existingMarker && markerIsStale(markerDir, currentVersion)) {
         log.warn(
           `Claude Desktop .skill bundle was produced by installer ${existingMarker.version}. ` +
             `Rebuilding — you will need to re-drag it into Claude Desktop > Settings > Extensions.`,
@@ -169,8 +180,9 @@ export function createClaudeDesktopAdapter(options = {}) {
         return { marketplace: "skipped", skills: "error", error: err.message };
       }
 
-      if (!existsSync(output)) {
-        log.warn(`Expected ${output} after packaging but it was not produced.`);
+      const missingOutputs = outputs.filter((skillOutput) => !existsSync(skillOutput));
+      if (missingOutputs.length) {
+        log.warn(`Expected skill bundle(s) were not produced: ${missingOutputs.join(", ")}`);
         return { marketplace: "skipped", skills: "error" };
       }
 
@@ -183,12 +195,14 @@ export function createClaudeDesktopAdapter(options = {}) {
         log.warn(`Could not write .skill installer marker: ${err.message}`);
       }
 
-      log.info(`Built Meko skill bundle: ${output}`);
+      for (const skillOutput of outputs) {
+        log.info(`Built Meko skill bundle: ${skillOutput}`);
+      }
       log.info(
-        "Install it in Claude Desktop: Settings > Extensions > Import skill, " +
-          "or drag the .skill file onto the Claude Desktop window.",
+        "Install both in Claude Desktop: Settings > Extensions > Import skill, " +
+          "or drag each .skill file onto the Claude Desktop window.",
       );
-      return { marketplace: "skipped", skills: "ok", output };
+      return { marketplace: "skipped", skills: "ok", output, outputs };
     },
     uninstall({ name }) {
       const results = [];
@@ -243,6 +257,12 @@ export function createClaudeDesktopAdapter(options = {}) {
             `Server "${serverName}" in ${path} is missing required "command" and "args" fields.`,
         };
       }
+      if (!entry.args.includes(`User-Agent:${MEKO_MCP_USER_AGENT}`)) {
+        return {
+          ok: false,
+          message: `Server "${serverName}" in ${path} is missing the User-Agent header required by the Cloud WAF.`,
+        };
+      }
 
       return { ok: true, message: `Server "${serverName}" is registered in ${path}.` };
     },
@@ -259,7 +279,15 @@ export function createClaudeDesktopAdapter(options = {}) {
  * @returns {{command: string, args: string[], env?: Record<string,string>}}
  */
 export function buildMcpRemoteEntry({ url, apiKey }) {
-  const args = ["-y", "mcp-remote", url, "--transport", "http-only"];
+  const args = [
+    "-y",
+    "mcp-remote",
+    url,
+    "--transport",
+    "http-only",
+    "--header",
+    `User-Agent:${MEKO_MCP_USER_AGENT}`,
+  ];
   const entry = { command: "npx", args };
   if (apiKey) {
     // `Authorization:Bearer ${MEKO_API_KEY}` with no space around the colon