@yugabytedb/meko-mcp 1.0.8 → 1.2.0

package/lib/installer.mjs

@@ -32,11 +32,12 @@ export async function install(options) {
     name = "meko",
     skipSkills = false,
     skipValidation = false,
+    skipCanary = false,
     dryRun = false,
     verbose = false,
     yes = false,
     projectRoot = process.cwd(),
-    cursorHookMode = "hybrid",
+    cursorHookMode = "native",
   } = options;
 
   const adapters = getClientAdapters();
@@ -107,7 +108,7 @@ export async function install(options) {
 
   if (!skipMcpRegistration) {
     try {
-      adapter.registerServer({
+      await adapter.registerServer({
         name,
         url,
         scope,
@@ -116,6 +117,7 @@ export async function install(options) {
         verbose,
         log: LOG,
         projectRoot,
+        yes,
       });
       stepOk(currentStep, totalSteps, dryRun ? "Registering MCP server (dry-run)." : "MCP server registered.");
     } catch (err) {
@@ -151,6 +153,7 @@ export async function install(options) {
   if (!skipSkills) {
     try {
       const result = adapter.installSkills({
+        name,
         scope,
         dryRun,
         verbose,
@@ -176,7 +179,8 @@ export async function install(options) {
       try {
         const results = await runValidation(url, apiKey, name, {
           validateConfig: async ({ serverName }) =>
-            adapter.validateConfig({ serverName, scope, projectRoot }),
+            adapter.validateConfig({ serverName, scope, projectRoot, url, apiKey }),
+          skipCanary,
         });
 
         const checks = [
@@ -184,6 +188,9 @@ export async function install(options) {
           { label: "Connectivity", ...results.connectivity },
           { label: "Tools", ...results.tools },
         ];
+        if (results.canary) {
+          checks.push({ label: "Canary", ...results.canary });
+        }
         for (const check of checks) {
           if (check.ok) success(`${check.label}: ${check.message}`);
           else warn(`${check.label}: ${check.message}`);
@@ -218,7 +225,7 @@ export async function uninstall(options = {}) {
     scope = "user",
     verbose = false,
     projectRoot = process.cwd(),
-    cursorHookMode = "hybrid",
+    cursorHookMode = "native",
   } = options;
 
   const adapters = getClientAdapters();

package/lib/mcp-transport.mjs

@@ -29,9 +29,16 @@ export function jsonRpcRequest(url, payload, apiKey, sessionId, opts = {}) {
     const parsed = new URL(url);
     const transport = parsed.protocol === "https:" ? https : http;
 
+    // MCP Streamable HTTP requires the client to advertise both content
+    // types: a non-streaming JSON response uses application/json, a
+    // streaming response (which is what FastMCP returns for `initialize`
+    // and any other call when stateless_http isn't `json_response=True`)
+    // uses text/event-stream. Sending only `application/json` produces a
+    // 406 Not Acceptable from spec-compliant servers (see meko-mcp-server
+    // PR #97 / MEKO-137 which turned this on for prod).
     const headers = {
       "Content-Type": "application/json",
-      Accept: "application/json",
+      Accept: "application/json, text/event-stream",
     };
     if (apiKey) {
       headers["Authorization"] = `Bearer ${apiKey}`;
@@ -56,10 +63,19 @@ export function jsonRpcRequest(url, payload, apiKey, sessionId, opts = {}) {
         const chunks = [];
         res.on("data", (chunk) => chunks.push(chunk));
         res.on("end", () => {
+          const raw = Buffer.concat(chunks).toString("utf8");
+          // If the server answered with text/event-stream (the MCP spec's
+          // streaming response shape), extract the JSON-RPC payload from
+          // the first SSE `data:` field. Callers downstream want a plain
+          // JSON-RPC body — they don't care which framing the wire used.
+          const contentType = String(res.headers["content-type"] ?? "").toLowerCase();
+          const body = contentType.includes("text/event-stream")
+            ? extractSseData(raw)
+            : raw;
           resolve({
             statusCode: res.statusCode,
             headers: res.headers,
-            body: Buffer.concat(chunks).toString("utf8"),
+            body,
           });
         });
       },
@@ -75,6 +91,49 @@ export function jsonRpcRequest(url, payload, apiKey, sessionId, opts = {}) {
   });
 }
 
+/**
+ * Extract the JSON-RPC payload from an SSE-framed response body.
+ *
+ * MCP servers running Streamable HTTP wrap each JSON-RPC response in an
+ * SSE event of the form:
+ *
+ *   event: message
+ *   data: {"jsonrpc":"2.0","id":1,"result":{...}}
+ *
+ * For a single non-streaming JSON-RPC response (initialize, tools/list,
+ * tools/call) there's exactly one event in the body. SSE allows the
+ * payload to span multiple `data:` lines; per the spec they are joined
+ * with `\n`. We concatenate every `data:` line we see in the first event
+ * and return that. Returns the raw body unchanged if no `data:` line is
+ * found (defensive fallback so a misbehaving server still produces a
+ * useful "non-JSON response" error downstream rather than an empty
+ * string).
+ *
+ * @param {string} raw - Raw response body (already utf8-decoded).
+ * @returns {string}
+ */
+function extractSseData(raw) {
+  const dataLines = [];
+  // Split on all three SSE-permitted line terminators per the WHATWG SSE
+  // spec: LF, CRLF, and bare CR. Most servers (including FastMCP) emit
+  // LF or CRLF, but the spec is explicit about CR-only being valid and
+  // we shouldn't break on a producer that uses it.
+  for (const rawLine of raw.split(/\r\n|\r|\n/)) {
+    if (rawLine === "") {
+      // Blank line terminates the event. We only need the first event for
+      // a JSON-RPC response.
+      if (dataLines.length > 0) break;
+      continue;
+    }
+    // `data:` field — capture the value, stripping the optional single
+    // leading space the spec allows after the colon. Anything else
+    // (`event:`, `id:`, `retry:`, comments starting with `:`) we ignore.
+    const match = /^data: ?(.*)$/.exec(rawLine);
+    if (match) dataLines.push(match[1]);
+  }
+  return dataLines.length > 0 ? dataLines.join("\n") : raw;
+}
+
 /**
  * Produce a human-friendly message from a network error.
  *

package/lib/migrate/adapters/memory-md.mjs

@@ -64,9 +64,9 @@ export async function enumerateMemoryItems(opts) {
         if (!cwd) continue;
         const agentId = agentIdForClaude(cwd);
         const projMd = path.join(cwd, ".claude", "CLAUDE.md");
-        items.push(...readClaudeMd(projMd, agentId, "project"));
+        items.push(...readClaudeMd(projMd, agentId, "project", cwd));
         const memDir = path.join(dir, "memory");
-        items.push(...readMemoryDir(memDir, agentId, "project"));
+        items.push(...readMemoryDir(memDir, agentId, "project", cwd));
       }
     }
   } else {
@@ -74,10 +74,10 @@ export async function enumerateMemoryItems(opts) {
     if (!cwd) return [];
     const agentId = agentIdForClaude(cwd);
     const projMd = path.join(cwd, ".claude", "CLAUDE.md");
-    items.push(...readClaudeMd(projMd, agentId, "project"));
+    items.push(...readClaudeMd(projMd, agentId, "project", cwd));
     const slug = slugifyCwd(cwd);
     const memDir = path.join(home, ".claude", "projects", slug, "memory");
-    items.push(...readMemoryDir(memDir, agentId, "project"));
+    items.push(...readMemoryDir(memDir, agentId, "project", cwd));
   }
 
   return items;
@@ -90,9 +90,13 @@ export async function enumerateMemoryItems(opts) {
  * @param {string} filePath
  * @param {string} agentId
  * @param {"user"|"project"} scope
+ * @param {string|null} [cwd] - Absolute project path. Attached to metadata
+ *   so downstream consumers can correlate even after the agent_id is
+ *   sanitized down to a basename. Null for user-scope items (which use the
+ *   `meko_agent` common bucket).
  * @returns {MemoryItem[]}
  */
-export function readClaudeMd(filePath, agentId, scope) {
+export function readClaudeMd(filePath, agentId, scope, cwd = null) {
   let raw;
   try {
     raw = fs.readFileSync(filePath, "utf8");
@@ -115,6 +119,7 @@ export function readClaudeMd(filePath, agentId, scope) {
         source: path.basename(filePath),
         scope,
         sourcePath: filePath,
+        ...(cwd ? { cwd } : {}),
         ...(heading ? { heading } : {}),
       },
     };
@@ -160,9 +165,10 @@ export function splitTopLevelSections(md) {
  * @param {string} memDir
  * @param {string} agentId
  * @param {"user"|"project"} scope
+ * @param {string|null} [cwd] - Absolute project path; attached to metadata.
  * @returns {MemoryItem[]}
  */
-export function readMemoryDir(memDir, agentId, scope) {
+export function readMemoryDir(memDir, agentId, scope, cwd = null) {
   let entries;
   try {
     entries = fs.readdirSync(memDir);
@@ -193,6 +199,7 @@ export function readMemoryDir(memDir, agentId, scope) {
         source: `memory/${entry}`,
         scope,
         sourcePath: full,
+        ...(cwd ? { cwd } : {}),
         ...(frontmatter.name ? { name: frontmatter.name } : {}),
         ...(frontmatter.description ? { description: frontmatter.description } : {}),
         ...(frontmatter.type ? { type: frontmatter.type } : {}),

package/lib/migrate/datapack.mjs

@@ -0,0 +1,167 @@
+/**
+ * datapack.mjs — Resolve a migration's destination datapack.
+ *
+ * The migrator was historically silent about destination: tools were called
+ * without `datapack_id`, the server filled in `tenant_ctx.default_datapack_id`,
+ * and the user never saw which pack their data actually landed in. With
+ * `--datapack <name-or-id>` we want both an explicit override and a printed
+ * confirmation of the default-fallback case. This module owns the lookup.
+ *
+ * Wire model: the MCP server routes by `datapack_id` parameter, not URL host.
+ * `datapack_list` returns the user's visible packs; we resolve here, then the
+ * orchestrator threads `datapack_id` into every subsequent `tools/call`.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEFAULT_DATAPACK_NAME = "meko_default_datapack";
+
+export function isUuid(value) {
+  return typeof value === "string" && UUID_RE.test(value);
+}
+
+/**
+ * Parse a `datapack_list` response body. Mirrors the shape-validation in
+ * validate.mjs: accepts a JSON array whose elements look like datapack
+ * records (`datapack_id` string present). Returns null on any other shape so
+ * callers can produce a precise error rather than a TypeError on .find().
+ *
+ * Note: response bodies can include connection-string secrets — never log
+ * `text` directly; only the resolved `{id, name}` is safe to surface.
+ *
+ * @param {string|null} text
+ * @returns {Array|null}
+ */
+export function parseDatapackList(text) {
+  if (!text) return null;
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(body)) return null;
+  if (body.length === 0) return body;
+  const allLook = body.every(
+    (e) => e && typeof e === "object" && typeof e.datapack_id === "string",
+  );
+  return allLook ? body : null;
+}
+
+/**
+ * Resolve the destination datapack for a migration.
+ *
+ * @param {object} opts
+ * @param {{callTool: Function}} opts.client    Connected McpClient.
+ * @param {string|null} opts.requested          Raw `--datapack` value (UUID or
+ *                                              name) or null for default.
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   id?: string|null,
+ *   name?: string|null,
+ *   source?: "default"|"flag-id"|"flag-name"|"server-fallback",
+ *   defaultId?: string|null,
+ *   message?: string,
+ * }>}
+ *
+ * `source` describes how the destination was picked:
+ *   - `default`: requested=null and a `meko_default_datapack` row exists.
+ *   - `flag-id` / `flag-name`: explicit override resolved.
+ *   - `server-fallback`: requested=null and no default row found in the list;
+ *     we let the server's own fallback chain handle it (id stays null).
+ *
+ * `defaultId` is the id of the `meko_default_datapack` row if visible — surfaced
+ * even when `requested` is non-null so the caller can detect "user named the
+ * default explicitly" and reuse the same on-disk state file.
+ *
+ * Failure cases (`ok: false`):
+ *   - `datapack_list` call failed (auth, network, server error).
+ *   - response body wasn't a recognizable datapack list.
+ *   - explicit override didn't match any row.
+ */
+export async function resolveDestinationDatapack(opts) {
+  const { client, requested } = opts;
+  const res = await client.callTool("datapack_list", {
+    scope: "read",
+    conversation_id: "00000000-0000-0000-0000-000000000000",
+  });
+  if (!res.ok) {
+    return {
+      ok: false,
+      message:
+        `datapack_list failed: ${res.error?.message ?? "unknown"}. ` +
+        `Cannot resolve --datapack.`,
+    };
+  }
+  const list = parseDatapackList(res.text);
+  if (!list) {
+    return {
+      ok: false,
+      message:
+        "datapack_list returned an unrecognized response shape. " +
+        "Cannot resolve --datapack.",
+    };
+  }
+
+  const defaultRow = list.find((d) => d.datapack_name === DEFAULT_DATAPACK_NAME);
+  const defaultId = defaultRow?.datapack_id ?? null;
+
+  if (!requested) {
+    if (defaultRow) {
+      return {
+        ok: true,
+        id: defaultRow.datapack_id,
+        name: defaultRow.datapack_name,
+        source: "default",
+        defaultId,
+      };
+    }
+    return { ok: true, id: null, name: null, source: "server-fallback", defaultId };
+  }
+
+  if (isUuid(requested)) {
+    const hit = list.find((d) => d.datapack_id?.toLowerCase() === requested.toLowerCase());
+    if (!hit) {
+      return {
+        ok: false,
+        message:
+          `--datapack ${requested}: no datapack with that id is visible to ` +
+          `this API key. ${formatAvailable(list)}`,
+      };
+    }
+    return {
+      ok: true,
+      id: hit.datapack_id,
+      name: hit.datapack_name ?? null,
+      source: "flag-id",
+      defaultId,
+    };
+  }
+
+  const hit = list.find((d) => d.datapack_name === requested);
+  if (!hit) {
+    return {
+      ok: false,
+      message:
+        `--datapack ${JSON.stringify(requested)}: no datapack with that name. ` +
+        formatAvailable(list),
+    };
+  }
+  return {
+    ok: true,
+    id: hit.datapack_id,
+    name: hit.datapack_name,
+    source: "flag-name",
+    defaultId,
+  };
+}
+
+/**
+ * Format a one-line "Available: a, b, c" hint. Names only — never ids,
+ * because the underlying response can carry credentials.
+ */
+function formatAvailable(list) {
+  const names = list
+    .map((d) => d.datapack_name)
+    .filter((n) => typeof n === "string" && n.length > 0);
+  if (names.length === 0) return "(no datapacks visible to this API key.)";
+  return `Available: ${names.join(", ")}.`;
+}

package/lib/migrate/id.mjs

@@ -3,6 +3,7 @@
  */
 
 import { createHash } from "node:crypto";
+import path from "node:path";
 
 /**
  * Slugify an absolute path the way Claude Code stores project sessions:
@@ -34,25 +35,102 @@ export function unslugifyCwd(slug) {
 }
 
 /**
- * @param {string} cwd - Absolute project path.
- * @returns {string} Agent id, e.g. `claude-code:-Users-foo-bar`.
+ * Server-side fallback for empty/missing agent_id. Anything written without
+ * an explicit value lands here. Used as the cross-project common bucket for
+ * genuinely cross-project facts (user identity, global preferences) that any
+ * agent should see without knowing the writer's project.
+ */
+export const COMMON_BUCKET_AGENT_ID = "meko_agent";
+
+const AGENT_ID_MAX_LEN = 64;
+const KNOWN_LOOSE_CLIENTS = new Set(["claude-desktop", "claude_desktop"]);
+const KNOWN_CODING_CLIENTS = new Set(["claude_code", "cursor"]);
+
+/**
+ * Sanitize a project segment: lowercase, collapse non-`[a-z0-9-]` to `-`,
+ * strip leading/trailing `-`, cap at 64 chars. Returns "" if the input
+ * yields nothing usable (caller falls back to the bare client name).
+ *
+ * @param {string} segment
+ * @returns {string}
+ */
+function sanitizeProjectSegment(segment) {
+  if (!segment) return "";
+  const lower = String(segment).toLowerCase();
+  const collapsed = lower.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return collapsed.slice(0, AGENT_ID_MAX_LEN);
+}
+
+/**
+ * Derive an `agent_id` for a Meko write.
+ *
+ * Contract:
+ *   - `envOverride` (typically `MEKO_AGENT_ID`) wins if non-empty.
+ *   - Loose clients (Claude Desktop) → bare `claude_desktop`; no schema.
+ *   - Coding clients (Claude Code, Cursor) → `<client>:<repo-basename>`.
+ *     Outside a repo (basename is empty/`.`/`/`) → bare client name to
+ *     keep coding-agent traffic out of the common bucket.
+ *   - Anything else → `meko_agent` (the common cross-project bucket).
+ *
+ * @param {object} opts
+ * @param {string} [opts.client]       e.g. "claude_code", "cursor", "claude-desktop"
+ * @param {string} [opts.cwd]          Absolute working directory, for coding clients
+ * @param {string} [opts.envOverride]  Raw value of `MEKO_AGENT_ID`, if set
+ * @returns {string}
+ */
+export function deriveAgentId(opts = {}) {
+  const override = (opts.envOverride ?? "").trim();
+  if (override) return override;
+
+  const client = (opts.client ?? "").trim();
+  if (KNOWN_LOOSE_CLIENTS.has(client)) return "claude_desktop";
+  if (!KNOWN_CODING_CLIENTS.has(client)) return COMMON_BUCKET_AGENT_ID;
+
+  const rawBase = opts.cwd ? path.basename(opts.cwd) : "";
+  if (!rawBase || rawBase === "." || rawBase === "/") return client;
+  const project = sanitizeProjectSegment(rawBase);
+  if (!project) return client;
+  return `${client}:${project}`;
+}
+
+/**
+ * Back-compat alias. New code should call `deriveAgentId(...)`.
+ */
+export const AGENT_ID = COMMON_BUCKET_AGENT_ID;
+
+/**
+ * @param {string} [cwd] Absolute project cwd. Required for project-scope
+ *   writes; omit for user-scope writes (returns the common bucket).
+ * @returns {string}
  */
 export function agentIdForClaude(cwd) {
-  return `claude-code:${slugifyCwd(cwd)}`;
+  if (!cwd) return COMMON_BUCKET_AGENT_ID;
+  return deriveAgentId({
+    client: "claude_code",
+    cwd,
+    envOverride: process.env.MEKO_AGENT_ID,
+  });
 }
 
 /**
- * User-scope agent id for artifacts that aren't tied to a specific project
- * (e.g., `~/.claude/CLAUDE.md`).
+ * User-scope agent id for content like `~/.claude/CLAUDE.md` that is genuinely
+ * cross-project. Goes into the `meko_agent` common bucket so any agent can
+ * read it regardless of the writer's project.
  */
-export const CLAUDE_CODE_USER_AGENT_ID = "claude-code:user";
+export const CLAUDE_CODE_USER_AGENT_ID = COMMON_BUCKET_AGENT_ID;
 
 /**
- * @param {string} projectName - Cursor's human-readable project folder name.
+ * @param {string} [cwd] Absolute project cwd (or basename — Cursor's projects
+ *   live under a flat `~/.cursor/projects/<name>/`). Omit for user-scope.
  * @returns {string}
  */
-export function agentIdForCursor(projectName) {
-  return `cursor:${projectName}`;
+export function agentIdForCursor(cwd) {
+  if (!cwd) return COMMON_BUCKET_AGENT_ID;
+  return deriveAgentId({
+    client: "cursor",
+    cwd,
+    envOverride: process.env.MEKO_AGENT_ID,
+  });
 }
 
 /**
@@ -81,3 +159,43 @@ export function seedFor(agentId, sessionUuid, messageUuid) {
 export function memoryHash(text, name = "") {
   return createHash("sha256").update(`${name}\0${text}`).digest("hex");
 }
+
+/**
+ * Derive a stable, filesystem-safe key for the destination datapack so the
+ * migrator can scope its resume state per datapack.
+ *
+ * Strategy:
+ *   - For the canonical cloud URL shape `https://<uuid>.mcp.mekodev.com/mcp`,
+ *     the leading host label is a UUID — use it verbatim. This keeps the
+ *     on-disk file name recognizable at a glance (it matches the datapack
+ *     UUID you'd see in the cloud UI).
+ *   - For anything else (localhost stacks, custom deployments), fall back
+ *     to `sha256(normalizedUrl).slice(0, 16)` — still stable, still short,
+ *     but unambiguously derived from the URL. We strip trailing slashes
+ *     before hashing so `http://localhost:8000/mcp` and
+ *     `http://localhost:8000/mcp/` resolve to the same key; otherwise a
+ *     user copy-pasting the endpoint with or without a trailing slash
+ *     would land on different state files and break resume.
+ *
+ * A bare `null`/empty string yields `"unknown"` so callers don't need a
+ * null-check just to pick a path. Callers that truly want to error on a
+ * missing URL should do so upstream.
+ *
+ * @param {string|null|undefined} url
+ * @returns {string}
+ */
+export function datapackKeyFromUrl(url) {
+  if (!url) return "unknown";
+  const trimmed = String(url).trim();
+  if (!trimmed) return "unknown";
+  // UUID host label, e.g. https://352ded8e-...mcp.mekodev.com/mcp
+  const m = trimmed.match(
+    /^https?:\/\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\./i,
+  );
+  if (m) return m[1].toLowerCase();
+  // Normalize trailing slashes so `.../mcp` and `.../mcp/` (and `.../mcp//`)
+  // all hash to the same key. We keep everything else as-is — paths are
+  // case-sensitive on most targets, so we deliberately don't touch case.
+  const normalized = trimmed.replace(/\/+$/, "");
+  return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}