@yugabytedb/meko-mcp 2.1.0 → 2.2.0

package/bin/create-meko-setup.mjs

@@ -18,6 +18,7 @@ import { resolveSuggestedMcpUrl } from '../lib/url-selection.mjs';
 import { parseClientList } from '../lib/clients/aliases.mjs';
 import { startMigration, runChildMigration, readStatus, stopMigration } from '../lib/migrate.mjs';
 import { checkLatest } from '../lib/version-check.mjs';
+import { runCaptureStatus } from '../lib/capture-status.mjs';
 
 // ---------------------------------------------------------------------------
 // Flag definitions
@@ -44,6 +45,10 @@ const options = {
   help:               { type: 'boolean', short: 'h', default: false },
   version:            { type: 'boolean', short: 'v', default: false },
 
+  // --- Capture health (Capture V2 Workstream D) ---
+  'capture-status':   { type: 'boolean', default: false },
+  json:               { type: 'boolean', default: false },
+
   // --- Migrate subcommand ---
   migrate:            { type: 'boolean', default: false },
   'migrate-status':   { type: 'boolean', default: false },
@@ -70,11 +75,11 @@ function readVersion() {
   return pkg.version;
 }
 
-const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex'];
+const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex', 'kiro'];
 
 function printHelp() {
   const text = `
-Meko Setup for Claude Clients and Cursor
+Meko Setup for Claude Code, Claude Desktop, Cursor, Codex, and Kiro
 
 Install and configure Meko MCP Server in one command.
 
@@ -100,15 +105,23 @@ Examples:
   # Install for OpenAI Codex (CLI + Desktop App share the same config):
   create-meko-setup --client codex --yes
 
+  # Install for Kiro (IDE and kiro-cli share the same config):
+  create-meko-setup --client kiro --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, codex.
-                        "claude" is accepted as an alias for claude-code.
+  --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor, codex, kiro.
+                        "claude" is accepted as an alias for claude-code;
+                        "kiro-cli" and "kiro-ide" for kiro.
                         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).
+                        kiro covers BOTH the Kiro IDE and kiro-cli. It installs
+                        inline CLI 2.x and standalone CLI 3.x/IDE capture hooks;
+                        untrusted IDE workspaces and non-managed CLI agents fall
+                        back to agent-driven persistence.
   --url <url>           MCP server URL (from cloud.mekodata.ai > Datapacks > Connect)
   --api-key <key>       API key for Cloud Meko authentication
   --local               Use local Meko at http://localhost:8000/mcp
@@ -134,6 +147,14 @@ Options:
   -h, --help            Show this help message
   -v, --version         Show version
 
+Capture health (durable outbox / recovery):
+  --capture-status      Report aggregate conversation-capture health from
+                        ~/.claude/meko-capture (or MEKO_WATERMARK_DIR).
+                        Exit 0 = healthy|catching_up, 2 = degraded_retrying,
+                        3 = blocked_action_required.
+  --json                With --capture-status, print machine-readable JSON
+                        matching the capture-health cache shape.
+
 Migrate existing conversations and memories into Meko:
   --migrate             Start a detached migration of existing Claude Code
                         and Cursor conversations + CLAUDE.md memories.
@@ -267,6 +288,20 @@ async function main() {
     process.exit(0);
   }
 
+  // --capture-status — aggregate outbox health (Capture V2). Combine with
+  // --json for machine-readable output. Exit codes: 0 healthy|catching_up,
+  // 2 degraded_retrying, 3 blocked_action_required.
+  if (flags['capture-status']) {
+    const out = runCaptureStatus({ json: Boolean(flags.json) });
+    if (out.stdout) process.stdout.write(out.stdout);
+    if (out.stderr) process.stderr.write(out.stderr);
+    process.exit(out.code);
+  }
+  if (flags.json) {
+    error('--json requires --capture-status');
+    process.exit(1);
+  }
+
   // --check-updates — synchronous probe of the npm registry. Never fails:
   // network errors produce "status: network error (<message>)" and exit 0.
   if (flags['check-updates']) {
@@ -442,6 +477,7 @@ async function main() {
         'claude-desktop': 'Claude Desktop',
         cursor: 'Cursor',
         codex: 'OpenAI Codex (CLI + App)',
+        kiro: 'Kiro (IDE + kiro-cli)',
       }[id];
       return {
         label: id,
@@ -542,12 +578,14 @@ async function main() {
     }
 
     // Step 4 — skills
-    const installSkills = await askYesNo(
-      'Install Meko agent skills plugin? (behavioral guides for MCP tools)',
-      true,
-    );
-    if (!installSkills) {
-      skipSkills = true;
+    if (!skipSkills) {
+      const installSkills = await askYesNo(
+        'Install Meko agent skills plugin? (behavioral guides for MCP tools)',
+        true,
+      );
+      if (!installSkills) {
+        skipSkills = true;
+      }
     }
 
     // Step 5 — statusline (Claude Code only). --no-statusline / --statusline

package/lib/capture-status.mjs

@@ -0,0 +1,67 @@
+/**
+ * capture-status.mjs — Installer helper that invokes capture-status-cli.js.
+ *
+ * Resolves the CLI next to bundled/source hooks (same root as capture.js).
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { resolveHooksRoot } from "./clients/common.mjs";
+
+/**
+ * Absolute path to capture-status-cli.js under the active asset root.
+ * @returns {string}
+ */
+export function resolveCaptureStatusCli() {
+  // Prefer the stable source-tree path in a checkout. Bundle tests create and
+  // remove installer/assets concurrently, so probing that transient directory
+  // first can race between existsSync and spawnSync. Published packages do not
+  // contain the repository skills tree and therefore fall back to assets.
+  const here = dirname(fileURLToPath(import.meta.url));
+  const sourceCli = resolve(
+    here,
+    "..",
+    "..",
+    "skills",
+    "hooks-handlers",
+    "lib",
+    "capture-status-cli.js",
+  );
+  if (existsSync(sourceCli)) return sourceCli;
+  return join(resolveHooksRoot(), "lib", "capture-status-cli.js");
+}
+
+/**
+ * Run the capture-status CLI and return its result.
+ *
+ * @param {{ json?: boolean, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ code: number, stdout: string, stderr: string, cliPath: string }}
+ */
+export function runCaptureStatus(opts = {}) {
+  const cliPath = resolveCaptureStatusCli();
+  if (!existsSync(cliPath)) {
+    return {
+      code: 1,
+      stdout: "",
+      stderr: `capture-status CLI not found at ${cliPath}`,
+      cliPath,
+    };
+  }
+  const args = [cliPath];
+  if (opts.json) args.push("--json");
+  const result = spawnSync(process.execPath, args, {
+    encoding: "utf8",
+    env: opts.env ? { ...process.env, ...opts.env } : process.env,
+  });
+  const code =
+    typeof result.status === "number" && result.status >= 0 ? result.status : 1;
+  return {
+    code,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    cliPath,
+  };
+}

package/lib/clients/aliases.mjs

@@ -3,6 +3,11 @@
 // import it without booting the bin entry point.
 export const CLIENT_ALIASES = Object.freeze({
   claude: "claude-code",
+  // The Kiro IDE and `kiro-cli` share one adapter: same mcp.json paths, same
+  // skills directories. Users reach for whichever name matches the surface
+  // they're installing for, so both resolve to the single `kiro` adapter.
+  "kiro-cli": "kiro",
+  "kiro-ide": "kiro",
 });
 
 /**

package/lib/clients/claude-desktop.mjs

@@ -18,6 +18,101 @@ import {
   writeInstallerMarker,
 } from "./common.mjs";
 
+/**
+ * Pinned top-level `mcp-remote` version.
+ *
+ * Pinning the top-level package (rather than leaving a bare `mcp-remote` that
+ * floats onto whatever npm's `latest` tag points to) reduces — but does not
+ * eliminate — startup drift: `mcp-remote@0.1.38` still declares transitive
+ * ranges like `open@^10.1.0` and `undici@^7.12.0`, and a fresh `npx` cache
+ * resolves the newest matching version of each with no lockfile consulted, so
+ * a future transitive release can still change startup behavior. The Node
+ * floor enforced below is what keeps today's tree runnable: every *currently
+ * published* undici 7 release declares `engines.node >= 20.18.1`, so rejecting
+ * Node under that floor covers the dependency set that resolves today. It is
+ * not a future-proof guarantee — a later in-range 7.x release could raise its
+ * own engine floor or introduce another incompatibility, which is exactly the
+ * residual drift the paragraph above acknowledges. Bump this pin deliberately
+ * after verifying the new release still starts on the supported Node floor.
+ */
+export const MCP_REMOTE_VERSION = "0.1.38";
+
+/** Pinned npm spec used in the registered command, e.g. `mcp-remote@0.1.38`. */
+export const MCP_REMOTE_PACKAGE = `mcp-remote@${MCP_REMOTE_VERSION}`;
+
+/**
+ * Minimum Node.js version required for the registered mcp-remote bridge to
+ * start. `mcp-remote@0.1.38` depends on `undici@^7.12.0`, and every undici 7
+ * release declares `engines.node >= 20.18.1`. npm's engine check is only a
+ * warning by default, so nothing stops a below-floor Node from resolving the
+ * tree and then crashing the bridge — we hard-fail preflight here instead of
+ * writing a config that cannot start. Bump this in lockstep with the pinned
+ * `mcp-remote` version above (and the advertised floors in package.json,
+ * mcpb/manifest.json, and the docs) after verifying the new dependency tree's
+ * engine requirement.
+ */
+export const MIN_NODE_VERSION = "20.18.1";
+
+/**
+ * Structured form of {@link MIN_NODE_VERSION}, parsed once so the preflight can
+ * compare major/minor/patch without re-parsing on every call.
+ */
+export const MIN_NODE = parseNodeVersion(MIN_NODE_VERSION);
+
+/**
+ * Parse a `process.version`-style string into its numeric {major, minor, patch}
+ * components (e.g. "v20.18.1" -> {major:20, minor:18, patch:1}). A missing
+ * minor/patch defaults to 0. Returns null when unparseable.
+ *
+ * The regex is end-anchored and rejects any trailing characters, including a
+ * semver prerelease/build suffix (`-rc.1`, `-nightly`, `+build`). A prerelease
+ * like `20.18.1-rc.1` sorts *below* the stable `20.18.1` under semver, so we
+ * must not silently discard the suffix and treat it as the stable release —
+ * that would let a below-floor prerelease pass the preflight. Returning null
+ * here routes such versions through `nodeMeetsFloor`'s not-satisfied path.
+ *
+ * @param {string} version
+ * @returns {{major:number, minor:number, patch:number}|null}
+ */
+export function parseNodeVersion(version) {
+  const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(String(version));
+  if (!match) return null;
+  const major = Number(match[1]);
+  const minor = Number(match[2] ?? 0);
+  const patch = Number(match[3] ?? 0);
+  if (![major, minor, patch].every(Number.isFinite)) return null;
+  return { major, minor, patch };
+}
+
+/**
+ * Does `version` meet the {@link MIN_NODE} floor (>= major.minor.patch)?
+ *
+ * Three cases:
+ *  - A clean `X.Y.Z` at/above the floor → true; below → false.
+ *  - A *version-shaped* string that isn't a clean release — a prerelease
+ *    (`20.18.1-rc.1`) or trailing garbage (`20.19.0-night,`) — → false. Under
+ *    semver a prerelease sorts below its release, so it does NOT satisfy
+ *    `>=20.18.1`; we reject rather than accept an ambiguous runtime.
+ *  - Input that isn't version-shaped at all → true. We stay lenient on strings
+ *    we can't read (the same stance the previous major-only check took);
+ *    `process.version` never produces these, so this only guards odd stubs.
+ *
+ * @param {string} version
+ * @returns {boolean}
+ */
+export function nodeMeetsFloor(version) {
+  const parsed = parseNodeVersion(version);
+  if (parsed === null) {
+    // Version-shaped (leading digits, optionally `v`-prefixed) but not a clean
+    // X.Y.Z — i.e. it carried a prerelease/build suffix or trailing chars.
+    // Treat as not satisfying the floor. Truly non-version input is lenient.
+    return !/^v?\d/.test(String(version));
+  }
+  if (parsed.major !== MIN_NODE.major) return parsed.major > MIN_NODE.major;
+  if (parsed.minor !== MIN_NODE.minor) return parsed.minor > MIN_NODE.minor;
+  return parsed.patch >= MIN_NODE.patch;
+}
+
 /**
  * Claude Desktop adapter.
  *
@@ -31,7 +126,7 @@ import {
  *
  *   "meko": {
  *     "command": "npx",
- *     "args": ["-y", "mcp-remote", "<url>", "--transport", "http-only",
+ *     "args": ["-y", "mcp-remote@<pinned>", "<url>", "--transport", "http-only",
  *              "--header", "User-Agent:meko-mcp-installer/1.0 (...)",
  *              "--header", "Authorization:Bearer ${MEKO_API_KEY}"],
  *     "env": { "MEKO_API_KEY": "<key>" }
@@ -53,6 +148,7 @@ export function createClaudeDesktopAdapter(options = {}) {
   const assetRootResolver = options.getAssetRoot ?? getAssetRoot;
   const packageRunner = options.runPackageScript ?? defaultRunPackageScript;
   const npxProber = options.probeNpx ?? defaultProbeNpx;
+  const nodeVersionResolver = options.getNodeVersion ?? (() => process.version);
 
   return {
     id: "claude-desktop",
@@ -61,12 +157,27 @@ export function createClaudeDesktopAdapter(options = {}) {
       return configPathResolver();
     },
     async detectPrerequisites({ log, verbose } = {}) {
+      // The registered mcp-remote bridge pulls in undici@^7, whose every
+      // release declares engines.node >= 20.18.1; below that floor the bridge
+      // crashes at startup and Claude Desktop shows "Server disconnected". A
+      // major-only check would wave through Node 20.0.0–20.18.0, so we parse
+      // the full version and reject anything below the exact floor here,
+      // before writing a config that Claude Desktop cannot start.
+      const nodeVersion = nodeVersionResolver();
+      if (!nodeMeetsFloor(nodeVersion)) {
+        throw new Error(
+          `Node >= ${MIN_NODE_VERSION} is required for the mcp-remote bridge that ` +
+            `Claude Desktop launches (detected ${nodeVersion}). Older Node ` +
+            `versions crash the bridge at startup and Claude Desktop shows ` +
+            `"Server disconnected". Upgrade Node.js and re-run the installer.`,
+        );
+      }
       const npx = npxProber();
       if (!npx.found) {
         throw new Error(
           "npx (from Node.js) is required so Claude Desktop can launch the " +
-            "mcp-remote stdio bridge. Install Node.js 18+ (which includes npx) " +
-            "and re-run the installer.",
+            `mcp-remote stdio bridge. Install Node.js ${MIN_NODE_VERSION}+ (which ` +
+            "includes npx) and re-run the installer.",
         );
       }
       if (verbose && log?.dim) {
@@ -283,7 +394,7 @@ export function createClaudeDesktopAdapter(options = {}) {
 export function buildMcpRemoteEntry({ url, apiKey }) {
   const args = [
     "-y",
-    "mcp-remote",
+    MCP_REMOTE_PACKAGE,
     url,
     "--transport",
     "http-only",
@@ -309,7 +420,11 @@ export function getMcpRemoteEntryUrl(entry) {
   }
   if (typeof entry?.url === "string") return entry.url;
   if (!Array.isArray(entry?.args)) return undefined;
-  const remoteIndex = entry.args.indexOf("mcp-remote");
+  // Match both the bare `mcp-remote` (legacy entries) and the pinned
+  // `mcp-remote@<version>` spec the installer now writes.
+  const remoteIndex = entry.args.findIndex(
+    (arg) => arg === "mcp-remote" || (typeof arg === "string" && arg.startsWith("mcp-remote@")),
+  );
   const candidate = remoteIndex >= 0 ? entry.args[remoteIndex + 1] : undefined;
   return typeof candidate === "string" ? candidate : undefined;
 }

package/lib/clients/codex.mjs

@@ -97,6 +97,7 @@ const MEKO_HOOK_SCRIPTS = [
  *   getAgentsMdPath?: () => string,
  *   getHooksPath?: () => string,
  *   getSkillsRoot?: () => string,
+ *   resolveSkillSource?: (name: string) => string,
  *   resolveHooksRoot?: () => string,
  *   getHooksInstallRoot?: () => string,
  *   runCommand?: (cmd: string) => string,
@@ -113,6 +114,8 @@ export function createCodexAdapter(options = {}) {
   const resolveHooksPath = options.getHooksPath ?? getCodexHooksPath;
   const resolveMekoEnvFilePath =
     options.getMekoEnvFilePath ?? getCodexMekoEnvFilePath;
+  const resolveSkillSourcePath =
+    options.resolveSkillSource ?? resolveSkillSource;
   const resolveHooksRootPath = options.resolveHooksRoot ?? resolveHooksRoot;
   const resolveHooksInstallRoot =
     options.getHooksInstallRoot ?? getCodexHooksInstallRoot;
@@ -439,7 +442,7 @@ export function createCodexAdapter(options = {}) {
 
       mkdirSync(skillsRoot, { recursive: true });
       for (const skill of SKILLS) {
-        const source = resolveSkillSource(skill.name);
+        const source = resolveSkillSourcePath(skill.name);
         const destination = join(skillsRoot, skill.name);
 
         if (existsSync(destination)) {
@@ -517,7 +520,7 @@ export function createCodexAdapter(options = {}) {
             removePath(dest);
             continue;
           }
-          const expectedSource = resolveSkillSource(skill.name);
+          const expectedSource = resolveSkillSourcePath(skill.name);
           if (isOwnSymlink(dest, expectedSource)) removePath(dest);
         }
         results.push({
@@ -1314,7 +1317,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 context. 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}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`,
     "",
     "Cloud auth requires `MEKO_API_KEY` exported in your shell (or, for the desktop app on macOS, set via `launchctl setenv`).",
     AGENTS_MD_END,

package/lib/clients/index.mjs

@@ -2,6 +2,7 @@ import { createClaudeCodeAdapter } from "./claude-code.mjs";
 import { createClaudeDesktopAdapter } from "./claude-desktop.mjs";
 import { createCodexAdapter } from "./codex.mjs";
 import { createCursorAdapter } from "./cursor.mjs";
+import { createKiroAdapter } from "./kiro.mjs";
 
 /**
  * @returns {Record<string, object>}
@@ -12,5 +13,6 @@ export function getClientAdapters() {
     "claude-desktop": createClaudeDesktopAdapter(),
     cursor: createCursorAdapter(),
     codex: createCodexAdapter(),
+    kiro: createKiroAdapter(),
   };
 }