@yugabytedb/meko-mcp 1.0.8 → 1.1.0

package/assets/skills/meko-mcp-tools/references/tools-user-id-conventions.md

@@ -1,93 +1,79 @@
-# user_id Conventions
+# user_id — identity scoping on Cloud Meko
 
-`user_id` identifies the **human** whose data is being stored or retrieved. It is the user-scoping counterpart to `agent_id`.
+On Cloud Meko, every write and every personal read carries a `user_id` that identifies **who** (the cognito account) is calling. The filter tuple for personal memories and conversations is `(datapack_id, user_id, agent_id)` — you only ever see memories your own user_id wrote (or content other team members have explicitly promoted to Shared Knowledge, which is separate — see `tools-agent-id-conventions.md`).
 
-> **Note on `agent_id`.** In the current schema `agent_id` is overloaded — it's used for both isolation/namespacing and agent labeling. Discover it via `db_summarize_database` at session start rather than defaulting to the current tool's name. See the main SKILL.md section "Discover the user's `agent_id` namespace" and issue [#10](https://github.com/amiramm/meko-mcp-server/issues/10). The examples below use `claude_code` for illustration; substitute the discovered value at runtime.
+## The default behavior: automatic user_id from cognito
 
-## Why user_id matters
+On Cloud, the server resolves your `user_id` automatically from the cognito account attached to your MCP session (the API key or OAuth token). You do not need to pass `user_id` on every call — omit it and the server fills in the account owner's id.
 
-Without `user_id`, the server defaults to `{agent_id}_user` — a single undifferentiated bucket. This works for a solo developer in a single session, but breaks the moment:
-
-- A second person uses the same agent
-- An autonomous agent serves multiple end-users
-- You want to retrieve one person's memories without pulling everyone else's
-
-**Always pass `user_id` explicitly.** Relying on the default creates data you can't cleanly separate later.
-
-## The two usage patterns
-
-### Interactive coding agent (e.g., Claude Code)
-
-You are a coding assistant working with one human at a time. You know who they are — use their identity as `user_id`.
+This is the common case for Claude Code / Claude Desktop / Cursor:
 
 ```
-memory_add(scope="write", agent_id="claude_code", user_id="alice",
-    text="Prefers concise responses, no emojis.")
-
-memory_search(scope="read", query="response preferences", agent_id="claude_code", user_id="alice")
-
-conversation_create(scope="write", agent_id="claude_code", user_id="alice",
-    title="Debugging auth middleware")
+memory_add(scope="write",
+           text="User prefers concise responses, no emojis.",
+           agent_id="claude_code:meko-mcp-server",
+           conversation_id="<session conversation_id>")
+# → stored with user_id = your cognito account id (auto)
 ```
 
-**How to determine user_id:**
-- Use the person's first name, lowercase: `"alice"`, `"bob"`, `"kyle"`
-- If the name is ambiguous within the org, append a qualifier: `"alice_eng"`, `"alice_sales"`
-- Use the same value consistently across all calls in a session — and across sessions
-- If you don't know the user's name yet, ask. Don't fall back to the default.
+A second person signing into the same Cloud datapack with their own account gets their own `user_id` automatically — they can never read your un-promoted memories via MCP, and you can never read theirs.
 
-### Autonomous multi-user agent (e.g., support bot, team assistant)
+## When to pass user_id explicitly
 
-The agent serves many users. Each user's data must be isolated so memories, conversations, and preferences don't leak across users.
+Explicit `user_id` is an **optional sub-scope** for agents that serve multiple end-users behind a single Meko account — think a support bot or team assistant where one cognito account is the "operator" but the agent is acting on behalf of different people. Each end-user's memories live in a separate partition under the same cognito account.
 
 ```
 # Serving Alice
-memory_add(scope="write", agent_id="support_bot", user_id="alice_123",
-    text="Alice prefers email communication. Has Pro plan.")
-
-# Serving Bob — completely separate memory space
-memory_add(scope="write", agent_id="support_bot", user_id="bob_456",
-    text="Bob prefers Slack. On Enterprise plan.")
-
-# Searching only returns Alice's memories
-memory_search(scope="read", query="communication preference",
-    agent_id="support_bot", user_id="alice_123")
+memory_add(scope="write",
+           text="Alice prefers email communication. Has Pro plan.",
+           agent_id="support-bot",
+           user_id="alice_123",
+           conversation_id="<conv>")
+
+# Serving Bob — completely separate partition, same cognito account
+memory_add(scope="write",
+           text="Bob prefers Slack. On Enterprise plan.",
+           agent_id="support-bot",
+           user_id="bob_456",
+           conversation_id="<conv>")
+
+# Search only returns Alice's memories
+memory_search(scope="read",
+              query="communication preference",
+              agent_id="support-bot",
+              user_id="alice_123",
+              conversation_id="<conv>")
 ```
 
-**How to determine user_id:**
-- Use a stable identifier from your auth/identity system: username, email prefix, or external ID
-- Must be consistent across sessions — the same person must always map to the same `user_id`
-- Keep it human-readable when possible (debugging is easier with `"alice"` than `"usr_8f3a2b"`)
+This is rarely relevant for Claude Code / Desktop / Cursor — those are single-human clients, and the automatic cognito user_id is the right behavior. It matters for autonomous multi-user agents built on top of the Meko API.
+
+## Gotcha — mixing scoped and unscoped calls
 
-## Scoping behavior
+If you pass `user_id="alice"` on writes but omit it on searches, the search falls back to the auto cognito user_id and **will not find** Alice's memories. They're in a different partition. Pick a convention for a given agent and stick to it:
 
-`user_id` filters data at the Mem0/Langfuse layer:
+- Claude Code / Desktop / Cursor: omit `user_id`, rely on the auto cognito value.
+- Multi-user autonomous agents: pass `user_id` consistently on every write and read.
 
-| Call | What it returns |
-|------|----------------|
-| `memory_search(agent_id="bot", user_id="alice")` | Only Alice's memories for this agent |
-| `memory_search(agent_id="bot")` | Memories stored without a `user_id`, or with the default `bot_user` |
-| `memory_get_all(agent_id="bot", user_id="alice")` | All of Alice's memories |
-| `conversation_list(agent_id="bot", user_id="alice")` | Only Alice's conversations |
+Mixing creates invisible data.
 
-**Mixing scoped and unscoped calls creates invisible data.** If you store with `user_id="alice"` but search without `user_id`, the search won't find those memories — they live in a different partition. Pick a convention and stick to it.
+## How user_id relates to agent_id and the Shared Knowledge split
 
-## Rules summary
+| Layer | Filter | Role of user_id |
+|---|---|---|
+| Personal memories (`memory_add`, `memory_search`, `memory_get_all`) | `(datapack_id, user_id, agent_id)` | Enforced on every read. One user cannot see another's un-promoted memories. |
+| Personal conversations (`conversation_list`, `conversation_get`) | Same tuple | Enforced. Cross-user reads require promotion. |
+| Team Shared Knowledge (`knowledgebase_search`) | `(datapack_id)` only | **Not used** — `user_id` is stripped when a memory is promoted to Knowledge. All team members on the datapack see the same Shared Knowledge. |
 
-1. **Always pass `user_id` explicitly** — never rely on the server default
-2. **Use the human's identity** — first name lowercase, consistent across sessions
-3. **Same `user_id` for store and retrieve** — mismatched scoping creates invisible data
-4. **Ask if you don't know** — it's better to ask the user's name once than to store data you can't find later
-5. **One human = one `user_id`** — don't create separate IDs for the same person across contexts
+The "Promote to Knowledge" action in the Cloud UI is the one way personal content crosses the user_id boundary. There is no MCP tool for promotion (user-initiated via UI only).
 
-## Relationship to other parameters
+## Parameter summary
 
-| Parameter | Identifies | Example |
-|-----------|-----------|---------|
-| `agent_id` | The AI agent | `"claude_code"`, `"support_bot"` |
-| `user_id` | The human being served | `"amiram"`, `"alice_123"` |
-| `app_id` | The application/product (optional) | `"second_brain"`, `"helpdesk"` |
-| `run_id` | A specific execution run (optional) | `"run_20260415_001"` |
-| `datapack_id` | The target database/datapack (optional) | `"dp-uuid-123"` |
+| Parameter | Identifies | Typical value | Required? |
+|---|---|---|---|
+| `datapack_id` | Which datapack's DB/Langfuse project | `"c038ba7b-..."` (UUID) | Optional on most tools (default datapack if omitted). **Required** on `knowledgebase_search`. |
+| `user_id` | The cognito account or end-user (for multi-user agents) | auto from cognito for single-human clients; explicit string for multi-user agents | Optional (server auto-fills from cognito context) |
+| `agent_id` | Which agent wrote / is reading | `"claude_code:<repo>"`, `"claude_desktop"`, `"cursor:<repo>"`, `"meko_agent"` (common bucket) | Optional (empty/missing → `meko_agent` server-side); pass the per-session value verbatim for project-scoped reads/writes. Ignored on `knowledgebase_search`. |
+| `app_id` | Optional application/product sub-scope | `"second_brain"`, `"helpdesk"` | Optional |
+| `run_id` | Optional specific execution run | `"run_20260507_001"` | Optional |
 
-Together, `agent_id` + `user_id` form the primary namespace for memory and conversation isolation. `app_id` and `run_id` provide optional finer-grained grouping within that namespace.
+See `tools-agent-id-conventions.md` for the full `agent_id` model.

package/bin/create-meko-setup.mjs

@@ -7,11 +7,12 @@ import { dirname, join } from 'node:path';
 
 import { install, uninstall } from '../lib/installer.mjs';
 import { askChoice, askMultiChoice, askText, askSecret, askYesNo, close as closePrompts } from '../lib/prompt.mjs';
-import { banner, error, dim } from '../lib/logger.mjs';
+import { banner, error, dim, info } 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';
+import { checkLatest } from '../lib/version-check.mjs';
 
 // ---------------------------------------------------------------------------
 // Flag definitions
@@ -27,7 +28,9 @@ const options = {
   'cursor-hook-mode': { type: 'string',  default: 'hybrid' },
   'skip-skills':      { type: 'boolean', default: false },
   'skip-validation':  { type: 'boolean', default: false },
+  'no-canary':        { type: 'boolean', default: false },
   'dry-run':          { type: 'boolean', default: false },
+  'check-updates':    { type: 'boolean', default: false },
   uninstall:          { type: 'boolean', default: false },
   verbose:            { type: 'boolean', default: false },
   yes:                { type: 'boolean', default: false },
@@ -43,6 +46,7 @@ const options = {
   rate:               { type: 'string' },
   'no-extract':       { type: 'boolean', default: false },
   'run-id':           { type: 'string' },
+  datapack:           { type: 'string' },
   '__migrate-child':  { type: 'boolean', default: false },
 };
 
@@ -59,7 +63,7 @@ function readVersion() {
   return pkg.version;
 }
 
-const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor'];
+const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex'];
 
 function printHelp() {
   const text = `
@@ -86,22 +90,32 @@ Examples:
   # Install on every supported client:
   create-meko-setup --client all --local --yes
 
+  # Install for OpenAI Codex (CLI + Desktop App share the same config):
+  create-meko-setup --client codex --yes
+
   # Local Meko (docker-compose stack, Claude Code):
   create-meko-setup --local --yes
 
 Options:
-  --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor.
+  --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor, codex.
                         "claude" is accepted as an alias for claude-code.
                         Comma-separated, or "all" to target every supported client (default: claude-code)
+                        codex covers BOTH the OpenAI Codex CLI and the Codex Desktop App
+                        (they share ~/.codex/config.toml).
   --url <url>           MCP server URL (from app.mekodev.com > Datapacks > Connect)
   --api-key <key>       API key for Cloud Meko authentication
   --local               Use local Meko at http://localhost:8000/mcp
   --scope <scope>       Config scope: user or project (default: user)
+                        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)
   --skip-skills         Skip plugin and skills installation
   --skip-validation     Skip post-install validation
+  --no-canary           Skip the canary datapack_list call. The
+                        connectivity + tools/list checks still run.
   --dry-run             Show what would be done without making changes
+  --check-updates       Compare installed version against npm registry and exit
   --uninstall           Remove Meko MCP server, skills, and env vars
   --verbose             Show detailed output
   --yes                 Accept all defaults (non-interactive)
@@ -121,6 +135,10 @@ Migrate existing conversations and memories into Meko:
   --rate <n>            Max concurrent MCP calls during migration (default 4).
   --force               Ignore a live lockfile or re-ingest processed items.
   --run-id <id>         Target a specific run-id for --migrate-status.
+  --datapack <name|id>  Migration destination datapack. Accepts a datapack
+                        name or UUID. When omitted, the user's default
+                        datapack is used (resolved at run time and printed
+                        before the run starts).
 `.trimStart();
 
   console.log(text);
@@ -130,6 +148,31 @@ function isCloudUrl(url) {
   return url && !url.includes('localhost') && !url.includes('127.0.0.1');
 }
 
+/**
+ * Sanitize a raw API key from any source (CLI flag, env var, askSecret prompt).
+ *
+ * Strips surrounding whitespace and a single matching pair of surrounding
+ * quotes. The contaminated value would otherwise be concatenated into
+ * `Authorization: Bearer <key>` verbatim and 401 against any server. Common
+ * sources of contamination: a trailing newline from
+ * `export MEKO_API_KEY=$(cat token.txt)`, a literal `"..."` copied out of a
+ * `.env` file, or a stray space at the end of a paste.
+ *
+ * Returns `null` for null/undefined/empty so the existing `!apiKey` checks
+ * still funnel into the "no key supplied" path.
+ */
+function normalizeApiKey(value) {
+  if (value === null || value === undefined) return null;
+  let s = String(value).trim();
+  if (
+    (s.startsWith('"') && s.endsWith('"') && s.length >= 2) ||
+    (s.startsWith("'") && s.endsWith("'") && s.length >= 2)
+  ) {
+    s = s.slice(1, -1).trim();
+  }
+  return s || null;
+}
+
 /**
  * Parse --client into a deduplicated list of client IDs.
  * Accepts a single value, a comma-separated list, or the keyword "all".
@@ -208,9 +251,41 @@ async function main() {
   // --version
   if (flags.version) {
     console.log(readVersion());
+    console.log('(run with --check-updates to compare against npm registry)');
     process.exit(0);
   }
 
+  // --check-updates — synchronous probe of the npm registry. Never fails:
+  // network errors produce "status: network error (<message>)" and exit 0.
+  if (flags['check-updates']) {
+    const current = readVersion();
+    const result = await checkLatest({ currentVersion: current });
+    console.log(`current: ${current}`);
+    if (result.latest) {
+      console.log(`latest:  ${result.latest}`);
+      if (result.isOutdated) {
+        console.log('status:  outdated — run `npx @yugabytedb/meko-mcp@latest` to upgrade');
+      } else {
+        console.log('status:  up to date');
+      }
+    } else {
+      console.log('latest:  unknown');
+      console.log(`status:  network error (${result.error ?? 'unknown'})`);
+    }
+    process.exit(0);
+  }
+
+  // Kick off a background version check on normal runs. We intentionally don't
+  // await — if the registry is slow or unreachable we don't want to delay
+  // (or fail) the install. `background: true` unrefs the underlying socket so
+  // an in-flight probe never keeps Node alive after the install exits; the
+  // result is still consulted (via Promise.race with an already-resolved
+  // sentinel) in time for the post-install banner when it arrives early.
+  const versionCheckPromise = checkLatest({ currentVersion: readVersion(), background: true });
+  versionCheckPromise.catch(() => {
+    /* checkLatest never rejects, but belt-and-suspenders. */
+  });
+
   // --- Migrate subcommand dispatch ---
 
   // Detached child branch: re-entry inside the spawned process.
@@ -230,11 +305,12 @@ async function main() {
       runId: flags['run-id'],
       scope: flags.scope,
       url: flags.url,
-      apiKey: process.env.MEKO_API_KEY ?? null,
+      apiKey: normalizeApiKey(process.env.MEKO_API_KEY),
       projectRoot,
       noExtract: flags['no-extract'],
       force: flags.force,
       rate: childRate,
+      datapack: flags.datapack ?? null,
     });
     process.exit(code);
   }
@@ -257,7 +333,7 @@ async function main() {
       process.exit(1);
     }
     let url = flags.url ?? process.env.MEKO_MCP_URL ?? null;
-    let apiKey = flags['api-key'] ?? process.env.MEKO_API_KEY ?? null;
+    let apiKey = normalizeApiKey(flags['api-key'] ?? process.env.MEKO_API_KEY);
     if (flags.local) { url = 'http://localhost:8000/mcp'; apiKey = null; }
 
     let parentRate;
@@ -274,6 +350,8 @@ async function main() {
       noExtract: flags['no-extract'],
       force: flags.force,
       rate: parentRate,
+      nonInteractive: flags.yes,
+      datapack: flags.datapack ?? null,
     });
     console.log(out.message);
     process.exit(out.ok ? 0 : 1);
@@ -289,6 +367,15 @@ async function main() {
     process.exit(1);
   }
 
+  // Validate --scope BEFORE any branch that interpolates it into a shell
+  // command. The --uninstall path now forwards --scope to
+  // `claude plugin uninstall --scope <X>`, so an invalid value must be
+  // caught here, not after it's already been handed to the shell.
+  if (!isValidScope(flags.scope)) {
+    error(`Unknown scope "${flags.scope}". Valid values: user, project.`);
+    process.exit(1);
+  }
+
   // --uninstall
   if (flags.uninstall) {
     for (const client of clients) {
@@ -303,19 +390,20 @@ async function main() {
     }
     process.exit(0);
   }
-
-  if (!isValidScope(flags.scope)) {
-    error(`Unknown scope "${flags.scope}". Valid values: user, project.`);
-    process.exit(1);
-  }
   if (!isValidCursorHookMode(flags['cursor-hook-mode'])) {
     error(`Unknown --cursor-hook-mode "${flags['cursor-hook-mode']}". Valid values: native, claude-compat, hybrid.`);
     process.exit(1);
   }
 
   let url    = flags.url    ?? null;
-  let apiKey = flags['api-key'] ?? null;
+  let apiKey = normalizeApiKey(flags['api-key']);
   let skipSkills = flags['skip-skills'];
+  // 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
+  // submitting an empty value at the full-flow prompt would re-ask the
+  // same question.
+  let promptedForApiKey = false;
 
   // --local shortcut
   if (flags.local) {
@@ -336,6 +424,7 @@ async function main() {
         'claude-code': 'Claude Code',
         'claude-desktop': 'Claude Desktop',
         cursor: 'Cursor',
+        codex: 'OpenAI Codex (CLI + App)',
       }[id];
       return {
         label: id,
@@ -391,8 +480,11 @@ async function main() {
       // Step 2 — MCP URL
       url = await askText('MCP server URL (from app.mekodev.com > Datapacks > Connect):');
 
-      // Step 3 — API key
-      apiKey = await askSecret('API key:');
+      // Step 3 — API key. Normalize: terminal paste can drag in trailing
+      // whitespace/CR or accidental surrounding quotes, all of which would
+      // sail straight into `Authorization: Bearer ...` and 401.
+      apiKey = normalizeApiKey(await askSecret('API key:'));
+      promptedForApiKey = true;
     } else {
       url    = 'http://localhost:8000/mcp';
       apiKey = null;
@@ -414,9 +506,22 @@ async function main() {
     process.exit(1);
   }
 
-  // Validation — Cloud URL requires an API key
+  // Validation — Cloud URL requires an API key.
+  // Resolution order: --api-key (already in `apiKey`) → $MEKO_API_KEY →
+  // interactive prompt (only on a TTY, not under --yes, and only if the
+  // full interactive flow above didn't already ask). The prompt fallback
+  // exists so a user who pastes the cloud one-liner from the UI (which
+  // only shows --url and --client) isn't dead-ended on a hard error when
+  // they forgot to supply the key. Skipping it after a full-flow prompt
+  // avoids re-asking the same question when the user submitted empty.
   if (isCloudUrl(url) && !apiKey) {
-    apiKey = process.env.MEKO_API_KEY ?? null;
+    apiKey = normalizeApiKey(process.env.MEKO_API_KEY);
+    if (apiKey) {
+      dim('Using API key from MEKO_API_KEY environment variable.');
+    } else if (!flags.yes && !promptedForApiKey && process.stdin.isTTY) {
+      dim('No --api-key or MEKO_API_KEY env var found; prompting for API key.');
+      apiKey = normalizeApiKey(await askSecret('API key:'));
+    }
     if (!apiKey) {
       error(
         'API key is required for Cloud Meko. ' +
@@ -424,7 +529,6 @@ async function main() {
       );
       process.exit(1);
     }
-    dim('Using API key from MEKO_API_KEY environment variable.');
   }
 
   // Install — loop through each selected client sequentially so failures
@@ -439,6 +543,7 @@ async function main() {
         name:           flags.name,
         skipSkills,
         skipValidation: flags['skip-validation'],
+        skipCanary:     flags['no-canary'],
         dryRun:         flags['dry-run'],
         verbose:        flags.verbose,
         yes:            flags.yes,
@@ -472,6 +577,7 @@ async function main() {
         apiKey,
         scope: flags.scope,
         projectRoot,
+        datapack: flags.datapack ?? null,
       });
     } else if (flags.yes) {
       console.log('');
@@ -482,16 +588,35 @@ async function main() {
         apiKey,
         scope: flags.scope,
         projectRoot,
+        datapack: flags.datapack ?? null,
       });
     }
   }
+
+  // Upgrade hint — only print if the background probe finished in time.
+  // We race the check against a pre-resolved sentinel so an in-flight
+  // probe (slow network) is silently dropped instead of delaying exit.
+  try {
+    const raced = await Promise.race([
+      versionCheckPromise,
+      Promise.resolve({ timedOut: true }),
+    ]);
+    if (raced && raced.isOutdated === true && raced.latest && raced.current) {
+      info(
+        `A newer version is available (${raced.latest}, you have ${raced.current}). ` +
+        'Re-run with `npx @yugabytedb/meko-mcp@latest`.',
+      );
+    }
+  } catch {
+    /* never reached — checkLatest doesn't reject — but don't block exit. */
+  }
 }
 
 /**
  * Unattended migration — used by --yes --with-migrate.
  * No prompts; errors are surfaced but do not fail the install.
  */
-async function runUnattendedMigration({ url, apiKey, scope, projectRoot }) {
+async function runUnattendedMigration({ url, apiKey, scope, projectRoot, datapack }) {
   try {
     const out = await startMigration({
       url,
@@ -499,6 +624,8 @@ async function runUnattendedMigration({ url, apiKey, scope, projectRoot }) {
       scope,
       projectRoot,
       scriptPath: __filename,
+      nonInteractive: true,
+      datapack: datapack ?? null,
     });
     console.log('');
     console.log(out.message);
@@ -516,7 +643,7 @@ async function runUnattendedMigration({ url, apiKey, scope, projectRoot }) {
  * whether to kick off the detached migration. Any error here is non-fatal —
  * install has already succeeded.
  */
-async function maybeOfferMigration({ url, apiKey, scope, projectRoot }) {
+async function maybeOfferMigration({ url, apiKey, scope, projectRoot, datapack }) {
   try {
     const dry = await startMigration({
       url,
@@ -525,6 +652,7 @@ async function maybeOfferMigration({ url, apiKey, scope, projectRoot }) {
       projectRoot,
       scriptPath: __filename,
       dryRun: true,
+      datapack: datapack ?? null,
     });
     const s = dry?.message?.match(/Claude Code sessions: *(\d+)/);
     const c = dry?.message?.match(/Cursor sessions: *(\d+)/);
@@ -559,6 +687,7 @@ async function maybeOfferMigration({ url, apiKey, scope, projectRoot }) {
       scope,
       projectRoot,
       scriptPath: __filename,
+      datapack: datapack ?? null,
     });
     console.log(out.message);
   } catch (err) {