@yugabytedb/meko-mcp 2.0.0 → 2.2.0

package/lib/migrate/orchestrator.mjs

@@ -17,6 +17,7 @@ import { seedFor } from "./id.mjs";
 import { resolveDestinationDatapack } from "./datapack.mjs";
 import * as claudeCodeAdapter from "./adapters/claude-code.mjs";
 import * as cursorAdapter from "./adapters/cursor.mjs";
+import * as codexAdapter from "./adapters/codex.mjs";
 import * as memoryMdAdapter from "./adapters/memory-md.mjs";
 
 /**
@@ -46,7 +47,9 @@ import * as memoryMdAdapter from "./adapters/memory-md.mjs";
  * @returns {Promise<{ok: boolean, summary: object, counts: object}>}
  */
 export async function runMigration(opts) {
-  fs.mkdirSync(opts.runDir, { recursive: true });
+  // A planning pass is intentionally read-only. In particular, don't create
+  // a run directory that `--migrate-status` can mistake for an active run.
+  if (!opts.dryRun) fs.mkdirSync(opts.runDir, { recursive: true });
 
   const log = opts.dryRun
     ? nullLogger()
@@ -55,6 +58,7 @@ export async function runMigration(opts) {
   const prog = progress.initial(opts.runId, opts.scope);
   const progressPath = path.join(opts.runDir, "progress.json");
   const writeProgress = () => {
+    if (opts.dryRun) return;
     try { progress.write(progressPath, prog); } catch { /* best effort */ }
   };
 
@@ -91,19 +95,26 @@ export async function runMigration(opts) {
     projectCwd: opts.projectCwd,
     home: opts.home,
   });
+  const codexSessions = codexAdapter.listSessions({
+    scope: opts.scope,
+    projectCwd: opts.projectCwd,
+    home: opts.home,
+  });
   const memoryItems = await memoryMdAdapter.enumerateMemoryItems({
     scope: opts.scope,
     projectCwd: opts.projectCwd,
     home: opts.home,
   });
 
-  prog.counts.sessionsPlanned = claudeSessions.length + cursorSessions.length;
+  prog.counts.sessionsPlanned =
+    claudeSessions.length + cursorSessions.length + codexSessions.length;
   writeProgress();
 
   log.info("plan", {
     scope: opts.scope,
     claudeSessions: claudeSessions.length,
     cursorSessions: cursorSessions.length,
+    codexSessions: codexSessions.length,
     memoryItems: memoryItems.length,
     dryRun: !!opts.dryRun,
     noExtract: !!opts.noExtract,
@@ -122,7 +133,12 @@ export async function runMigration(opts) {
       const parsed = cursorAdapter.parseSession(ref.path);
       pairedTurns += parsed.exchanges.length;
     }
-    const plannedConversationCreates = claudeSessions.length + cursorSessions.length
+    for (const ref of codexSessions) {
+      const parsed = codexAdapter.parseSession(ref.path);
+      pairedTurns += parsed.exchanges.length;
+    }
+    const plannedConversationCreates =
+      claudeSessions.length + cursorSessions.length + codexSessions.length
       + (memoryItems.length > 0 ? countDistinctMemoryAgents(memoryItems) : 0);
     const plannedConversationAddMessage = pairedTurns;
     const plannedMemoryAddExtract = opts.noExtract ? 0 : pairedTurns;
@@ -132,6 +148,7 @@ export async function runMigration(opts) {
       scope: opts.scope,
       claudeSessions: claudeSessions.length,
       cursorSessions: cursorSessions.length,
+      codexSessions: codexSessions.length,
       memoryItems: memoryItems.length,
       pairedTurns,
       plannedCalls: {
@@ -218,7 +235,15 @@ export async function runMigration(opts) {
   const withDp = (args) => (datapackId ? { ...args, datapack_id: datapackId } : args);
 
   // -- Conversations --
-  for (const ref of [...claudeSessions, ...cursorSessions]) {
+  // Tag each ref with its source so the parse dispatch below is explicit.
+  // Claude Code and Codex both store rollouts as `.jsonl`, so an
+  // extension check alone can't tell them apart.
+  const taggedSessions = [
+    ...claudeSessions.map((ref) => ({ ref, source: "claude-code" })),
+    ...cursorSessions.map((ref) => ({ ref, source: "cursor" })),
+    ...codexSessions.map((ref) => ({ ref, source: "codex" })),
+  ];
+  for (const { ref, source } of taggedSessions) {
     let existing = state.getSession(st, ref.agentId, ref.sessionUuid);
     if (existing?.status === "done" && !opts.force) {
       log.info("session_skip_done", { agentId: ref.agentId, sessionUuid: ref.sessionUuid });
@@ -243,9 +268,11 @@ export async function runMigration(opts) {
     prog.currentSession = ref.sessionUuid;
     writeProgress();
 
-    const parsed = (ref.path && ref.path.endsWith(".jsonl"))
+    const parsed = source === "claude-code"
       ? await claudeCodeAdapter.parseSession(ref.path)
-      : cursorAdapter.parseSession(ref.path);
+      : source === "codex"
+        ? codexAdapter.parseSession(ref.path)
+        : cursorAdapter.parseSession(ref.path);
 
     if (parsed.partial) {
       log.warn("session_partial", { path: ref.path });
@@ -260,7 +287,7 @@ export async function runMigration(opts) {
         session_id: ref.sessionUuid,
         title: (parsed.firstUserText || ref.sessionUuid).slice(0, 120),
         metadata: JSON.stringify({
-          source: ref.path.endsWith(".jsonl") ? "claude-code" : "cursor",
+          source,
           cwd: ref.cwd || null,
           gitBranch: ref.slug ? (parsed.gitBranch || null) : null,
           startedAt: parsed.startedAt || null,

package/lib/migrate.mjs

@@ -212,10 +212,10 @@ export async function startMigration(opts) {
   // don't move when the state key changes.
   const urlDatapackKey = datapackKeyFromUrl(opts.url);
   let P = paths({ datapackKey: urlDatapackKey });
-  fs.mkdirSync(P.root, { recursive: true });
 
   // Dry-run is a local-only planning pass: no HTTP, no lock, no fork.
-  // Don't gate it on URL/apiKey.
+  // Don't gate it on URL/apiKey, and don't create the migration root: a
+  // planning pass must not appear as a phantom active run in --migrate-status.
   if (opts.dryRun) {
     const runId = generateRunId();
     const runDir = P.runDir(runId);
@@ -260,6 +260,8 @@ export async function startMigration(opts) {
     };
   }
 
+  fs.mkdirSync(P.root, { recursive: true });
+
   // Real run — now URL/apiKey are required (dry-run branch already returned).
   if (!opts.url) {
     return { ok: false, message: "--url (or MEKO_MCP_URL) is required for --migrate." };

package/lib/prompt.mjs

@@ -37,6 +37,21 @@ function question(query) {
   });
 }
 
+/**
+ * Apply terminal erase bytes that survive readline's muted-output path.
+ * Some PTYs leave DEL/BS in the answer when readline is attached to a
+ * non-TTY Writable, even with terminal mode enabled. Treat them exactly as
+ * interactive backspace so a corrected secret never persists control bytes.
+ */
+function applyEraseCharacters(value) {
+  const chars = [];
+  for (const char of value) {
+    if (char === "\x7f" || char === "\b") chars.pop();
+    else chars.push(char);
+  }
+  return chars.join("");
+}
+
 // ---------------------------------------------------------------------------
 // askChoice
 // ---------------------------------------------------------------------------
@@ -50,7 +65,7 @@ function question(query) {
  *
  * @example
  *   const choice = await askChoice('Connection type:', [
- *     { label: 'Cloud Meko', description: 'Hosted at mekodev.com' },
+ *     { label: 'Cloud Meko', description: 'Hosted at mekodata.ai' },
  *     { label: 'Local Meko', description: 'docker-compose stack' },
  *   ]);
  */
@@ -218,7 +233,7 @@ export async function askSecret(questionText) {
 
     secretRL.question("", (answer) => {
       finish();
-      resolve(answer);
+      resolve(applyEraseCharacters(answer));
     });
   });
 }

package/lib/url-selection.mjs

@@ -0,0 +1,55 @@
+import { MEKO_PRODUCTION_MCP_URL } from "./clients/common.mjs";
+
+function validHttpUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const candidate = value.trim();
+  try {
+    const parsed = new URL(candidate);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+    return { value: candidate, comparisonKey: parsed.toString() };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Select the URL offered by interactive/non-interactive setup.
+ * Explicit CLI URLs are resolved before this helper is called.
+ */
+export function resolveSuggestedMcpUrl({
+  adapters,
+  clients,
+  name = "meko",
+  scope = "user",
+  projectRoot = process.cwd(),
+}) {
+  const existingUrlsByKey = new Map();
+  for (const client of clients) {
+    const adapter = adapters[client];
+    if (!adapter?.detectExisting) continue;
+    try {
+      const existing = adapter.detectExisting(name, { scope, projectRoot });
+      const url = existing?.found ? validHttpUrl(existing.url) : null;
+      if (url && !existingUrlsByKey.has(url.comparisonKey)) {
+        existingUrlsByKey.set(url.comparisonKey, url.value);
+      }
+    } catch {
+      // Existing-config discovery is advisory. Installation performs its own
+      // prerequisite and config checks later with actionable errors.
+    }
+  }
+
+  const uniqueUrls = [...existingUrlsByKey.values()];
+  if (uniqueUrls.length === 1) {
+    return { url: uniqueUrls[0], source: "existing", existingUrls: uniqueUrls };
+  }
+  if (uniqueUrls.length > 1) {
+    return { url: null, source: "conflict", existingUrls: uniqueUrls };
+  }
+  return {
+    url: MEKO_PRODUCTION_MCP_URL,
+    source: "production-default",
+    existingUrls: [],
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yugabytedb/meko-mcp",
-  "version": "2.0.0",
-  "description": "Single-line installer for Meko MCP Server across Claude and Cursor clients",
+  "version": "2.2.0",
+  "description": "Installer for Meko across Claude, Cursor, Codex, and Kiro clients",
   "type": "module",
   "bin": {
     "create-meko-setup": "bin/create-meko-setup.mjs",
@@ -18,14 +18,14 @@
     "prepack": "node scripts/bundle-assets.mjs",
     "postpack": "node scripts/bundle-assets.mjs --clean",
     "bundle-assets": "node scripts/bundle-assets.mjs",
-    "test": "node --test \"test/*.mjs\"",
+    "test": "node --test \"test/*.mjs\" && node --test \"test/serial/*.mjs\"",
     "smoke": "./scripts/prepublish-smoke.sh",
     "test:unit": "node --test test/config.test.mjs test/validate.test.mjs test/clients.test.mjs",
     "test:integration": "RUN_INSTALLER_INTEGRATION=1 node --test test/installer.test.mjs",
     "test:integration:cloud": "RUN_INSTALLER_INTEGRATION=1 node --test test/installer.test.mjs"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.18.1"
   },
   "keywords": [
     "meko",

package/assets/skills/meko-mcp-tools/references/tools-scope-permissions.md

@@ -1,71 +0,0 @@
-# Scope Permission Hierarchy and Per-Tool Requirements
-
-**WRONG:** `memory_add(scope="read", ...)` → PermissionError: requires 'write' or higher.
-**WRONG:** `memory_delete_all(scope="write", ...)` → PermissionError: requires 'admin'.
-
-## Scope Hierarchy
-
-```
-admin  (level 2)  -- can do everything
-  ↓
-write  (level 1)  -- can read + write, not admin-only
-  ↓
-read   (level 0)  -- can only read
-```
-
-Higher scopes include lower scopes. An unrecognized scope string always fails.
-
-## Per-Tool Requirements
-
-### read scope (9 tools)
-
-| Tool | Group |
-|------|-------|
-| `knowledgebase_search` | RAG |
-| `memory_search` | Memory |
-| `memory_get_by_id` | Memory |
-| `memory_get_all` | Memory |
-| `flush_pending_memory_candidates` | Memory |
-| `conversation_get` | Conversation |
-| `conversation_list` | Conversation |
-| `datapack_list` | Datapack |
-| `datapack_describe` | Datapack |
-
-### write scope (9 tools)
-
-| Tool | Group |
-|------|-------|
-| `memory_add` | Memory |
-| `memory_update` | Memory |
-| `memory_delete_by_id` | Memory |
-| `conversation_create` | Conversation |
-| `conversation_add_message` | Conversation |
-| `conversation_update` | Conversation |
-| `datapack_create` | Datapack |
-| `datapack_update` | Datapack |
-| `track_token_usage` | Observability |
-
-### admin scope (3 tools — destructive, irreversible)
-
-| Tool | Group |
-|------|-------|
-| `memory_delete_all` | Memory |
-| `conversation_delete` | Conversation |
-| `datapack_delete` | Datapack |
-
-Agent and knowledge-base lifecycle tools are not MCP-exposed — see "Platform capabilities NOT exposed via MCP" in `tools-overview.md`.
-
-## Best Practices
-
-1. **Use the minimum scope needed.** `scope="read"` for reads documents intent and prevents accidental writes.
-2. **The scope is a parameter, not an auth token.** When OAuth is enabled, the actual permission check happens against the OAuth token's claims. Both `scope` parameter and OAuth permissions must be satisfied.
-
-## Common Mistakes
-
-**WRONG:** `scope="all"` — there is no "all" scope. Valid values are exactly: `"read"`, `"write"`, `"admin"`. Nothing else.
-
-Other invalid values that will fail: `"readwrite"`, `"rw"`, `"full"`, `"any"`.
-
-The error `Insufficient scope: 'all'. This tool requires 'read' or higher.` means the scope string was not recognized as a valid value. Always use one of the three valid strings.
-
-**Default choice:** Start with `scope="read"` unless you specifically need to write or delete.

package/assets/skills/meko-mcp-tools-desktop/references/tools-scope-permissions.md

@@ -1,71 +0,0 @@
-# Scope Permission Hierarchy and Per-Tool Requirements
-
-**WRONG:** `memory_add(scope="read", ...)` → PermissionError: requires 'write' or higher.
-**WRONG:** `memory_delete_all(scope="write", ...)` → PermissionError: requires 'admin'.
-
-## Scope Hierarchy
-
-```
-admin  (level 2)  -- can do everything
-  ↓
-write  (level 1)  -- can read + write, not admin-only
-  ↓
-read   (level 0)  -- can only read
-```
-
-Higher scopes include lower scopes. An unrecognized scope string always fails.
-
-## Per-Tool Requirements
-
-### read scope (9 tools)
-
-| Tool | Group |
-|------|-------|
-| `knowledgebase_search` | RAG |
-| `memory_search` | Memory |
-| `memory_get_by_id` | Memory |
-| `memory_get_all` | Memory |
-| `flush_pending_memory_candidates` | Memory |
-| `conversation_get` | Conversation |
-| `conversation_list` | Conversation |
-| `datapack_list` | Datapack |
-| `datapack_describe` | Datapack |
-
-### write scope (9 tools)
-
-| Tool | Group |
-|------|-------|
-| `memory_add` | Memory |
-| `memory_update` | Memory |
-| `memory_delete_by_id` | Memory |
-| `conversation_create` | Conversation |
-| `conversation_add_message` | Conversation |
-| `conversation_update` | Conversation |
-| `datapack_create` | Datapack |
-| `datapack_update` | Datapack |
-| `track_token_usage` | Observability |
-
-### admin scope (3 tools — destructive, irreversible)
-
-| Tool | Group |
-|------|-------|
-| `memory_delete_all` | Memory |
-| `conversation_delete` | Conversation |
-| `datapack_delete` | Datapack |
-
-Agent and knowledge-base lifecycle tools are not MCP-exposed — see "Platform capabilities NOT exposed via MCP" in `tools-overview.md`.
-
-## Best Practices
-
-1. **Use the minimum scope needed.** `scope="read"` for reads documents intent and prevents accidental writes.
-2. **The scope is a parameter, not an auth token.** When OAuth is enabled, the actual permission check happens against the OAuth token's claims. Both `scope` parameter and OAuth permissions must be satisfied.
-
-## Common Mistakes
-
-**WRONG:** `scope="all"` — there is no "all" scope. Valid values are exactly: `"read"`, `"write"`, `"admin"`. Nothing else.
-
-Other invalid values that will fail: `"readwrite"`, `"rw"`, `"full"`, `"any"`.
-
-The error `Insufficient scope: 'all'. This tool requires 'read' or higher.` means the scope string was not recognized as a valid value. Always use one of the three valid strings.
-
-**Default choice:** Start with `scope="read"` unless you specifically need to write or delete.