@yugabytedb/meko-mcp 1.0.8 → 1.2.0

package/lib/validate.mjs

@@ -1,10 +1,15 @@
 /**
  * validate.mjs - Post-install validation for Meko MCP Server.
  *
- * Runs three checks in sequence:
+ * Runs four checks in sequence:
  *   1. Config check   - Is the server registered in `claude mcp list`?
- *   2. Connectivity    - Can we complete an MCP `initialize` handshake?
- *   3. Tools           - Does `tools/list` return the expected core tools?
+ *   2. Connectivity   - Can we complete an MCP `initialize` handshake?
+ *   3. Tools          - Does `tools/list` return the expected core tools?
+ *   4. Canary         - Does a deterministic read-only Meko tool call return
+ *                       a sane response? Proves auth → tenant → datapack
+ *                       routing end-to-end without depending on mem0's
+ *                       LLM fact-extractor (which historically failed the
+ *                       canary non-deterministically).
  *
  * HTTP transport lives in ./mcp-transport.mjs and is shared with the
  * migrate subcommand.
@@ -25,10 +30,18 @@ import {
 /** Core tools that must appear in tools/list for validation to pass. */
 const CORE_TOOLS = [
   "memory_search",
+  "memory_get_by_id",
   "conversation_create",
   "db_summarize_database",
+  "datapack_list",
 ];
 
+/** Nil UUID used as the conversation_id placeholder for the canary call. */
+const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+
+/** Tool the canary invokes. */
+const CANARY_TOOL = "datapack_list";
+
 // ---------------------------------------------------------------------------
 // 1. Config validation
 // ---------------------------------------------------------------------------
@@ -118,21 +131,149 @@ export async function validateTools(url, apiKey) {
 }
 
 // ---------------------------------------------------------------------------
-// 4. Combined runner
+// 4. Canary validation (deterministic, read-only)
+// ---------------------------------------------------------------------------
+
+/**
+ * Call a deterministic, read-only Meko tool and verify the response shape.
+ *
+ * The canary's job is to prove the part of the stack that connectivity +
+ * tools/list don't cover: auth was accepted as a real Meko identity, the
+ * tenant resolver mapped it to an account, and the datapack routing wired
+ * up the user's actual workspace. We invoke `datapack_list` for this — it
+ * is a single read-only call, runs a short SQL query against the system
+ * schema, and returns deterministically (every authenticated user has at
+ * least one datapack: their default).
+ *
+ * Why not memory_add? The previous canary did a write/read/delete round-trip
+ * via `memory_add`/`memory_get_by_id`/`memory_delete_by_id`. mem0's LLM
+ * fact-extractor decides per-call whether the input contains facts worth
+ * indexing; for the canary text it returned `results: []` *some of the time*
+ * even though the graph extractor did add entities. The installer's id
+ * extraction then reported "no memory id" and failed validation despite the
+ * server being healthy. A non-LLM read-only tool removes that whole class
+ * of false negative.
+ *
+ * Security note: `datapack_list` returns each datapack's
+ * `datapack_ysql_connection_string`, which contains a database password.
+ * This function MUST NOT echo the raw response into a user-facing message.
+ * Failure messages reference the tool name, the JSON-RPC error code, or a
+ * server-emitted `error` discriminator — never the body.
+ *
+ * @param {string} url - Full MCP endpoint URL.
+ * @param {string|null} apiKey - Optional API key.
+ * @param {object} [options]
+ * @param {string} [options.sessionId] - Existing MCP session id. If omitted, a new
+ *                                       initialize handshake is performed.
+ * @param {number} [options.timeoutMs] - Override the canary call's transport timeout.
+ *                                       Defaults to DEFAULT_REQUEST_TIMEOUT_MS.
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   message: string,
+ *   datapack_count: number|null,
+ *   step?: "initialize"|"datapack_list",
+ * }>}
+ */
+export async function validateCanary(url, apiKey, options = {}) {
+  const timeoutMs = options.timeoutMs;
+
+  let sessionId = options.sessionId ?? null;
+  if (!sessionId) {
+    const init = await mcpInitialize(url, apiKey);
+    if (!init.ok) {
+      return {
+        ok: false,
+        datapack_count: null,
+        step: "initialize",
+        message: `Canary: could not initialize MCP session (${init.message}).`,
+      };
+    }
+    sessionId = init.sessionId;
+  }
+
+  const callRes = await mcpCallTool(
+    url,
+    apiKey,
+    sessionId,
+    CANARY_TOOL,
+    {
+      scope: "read",
+      conversation_id: NIL_UUID,
+    },
+    { timeoutMs },
+  );
+
+  if (!callRes.ok) {
+    // mcpCallTool already produces a sanitized message (tool name + reason
+    // or JSON-RPC error code); it never includes the raw text body when
+    // the server emits a structured `{error: ...}` envelope. Pass it
+    // through verbatim.
+    return {
+      ok: false,
+      datapack_count: null,
+      step: CANARY_TOOL,
+      message: `Canary: ${callRes.message}`,
+    };
+  }
+
+  const datapacks = parseDatapackList(callRes.text);
+  if (!datapacks) {
+    // The tool returned a 2xx but the body wasn't a recognizable list.
+    // Don't dump it — list_datapacks responses include connection-string
+    // secrets when they parse correctly, and we have no way to know whether
+    // the unparseable body has the same.
+    return {
+      ok: false,
+      datapack_count: null,
+      step: CANARY_TOOL,
+      message:
+        `Canary: ${CANARY_TOOL} returned an unexpected response shape ` +
+        `(expected a JSON array of datapack objects). Check the server logs.`,
+    };
+  }
+
+  if (datapacks.length === 0) {
+    return {
+      ok: false,
+      datapack_count: 0,
+      step: CANARY_TOOL,
+      message:
+        `Canary: ${CANARY_TOOL} returned zero datapacks. Every authenticated ` +
+        `Meko user should have at least their default datapack — this likely ` +
+        `means the API token authenticated but resolved to the wrong tenant. ` +
+        `Verify the API key matches the tenant the URL points at.`,
+    };
+  }
+
+  return {
+    ok: true,
+    datapack_count: datapacks.length,
+    message: `Canary OK — ${CANARY_TOOL} returned ${datapacks.length} datapack(s).`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 5. Combined runner
 // ---------------------------------------------------------------------------
 
 /**
  * Run all validation checks in sequence and return a summary.
  *
  * When the connectivity check succeeds, the tools check reuses the same
- * MCP session rather than performing a redundant second initialize.
+ * MCP session rather than performing a redundant second initialize. The
+ * canary reuses that same session too.
+ *
+ * The canary is skipped (not failed) when tools/list didn't pass — the
+ * canary depends on `datapack_list` being present, and a tools failure
+ * already surfaces that.
  *
  * @param {string} url - Full MCP endpoint URL.
  * @param {string|null} apiKey - Optional API key.
  * @param {string} serverName - Server name for config check (default "meko").
  * @param {object} [options]
  * @param {(params: {serverName: string}) => Promise<{ok: boolean, message: string}>} [options.validateConfig]
- * @returns {Promise<{config: object, connectivity: object, tools: object, allPassed: boolean}>}
+ * @param {boolean} [options.skipCanary] - Skip the canary entirely.
+ * @returns {Promise<{config: object, connectivity: object, tools: object, canary: object|null, allPassed: boolean}>}
  */
 export async function runValidation(url, apiKey, serverName = "meko", options = {}) {
   const configValidator = options.validateConfig ?? (async ({ serverName: value }) => validateConfig(value));
@@ -147,11 +288,34 @@ export async function runValidation(url, apiKey, serverName = "meko", options =
     tools = { ok: false, tools: [], message: `Skipped: ${connectivity.message}` };
   }
 
+  let canary = null;
+  if (!options.skipCanary) {
+    if (tools.ok && connectivity.ok) {
+      canary = await validateCanary(url, apiKey, {
+        sessionId: connectivity.sessionId,
+      });
+    } else {
+      canary = {
+        ok: false,
+        datapack_count: null,
+        message: `Skipped: tools/list did not pass (${tools.message}).`,
+        skipped: true,
+      };
+    }
+  }
+
+  const allPassed =
+    config.ok &&
+    connectivity.ok &&
+    tools.ok &&
+    (!canary || canary.ok);
+
   return {
     config,
     connectivity,
     tools,
-    allPassed: config.ok && connectivity.ok && tools.ok,
+    canary,
+    allPassed,
   };
 }
 
@@ -190,7 +354,7 @@ async function sendToolsList(url, apiKey, sessionId) {
     return {
       ok: false,
       tools: [],
-      message: `tools/list returned HTTP ${res.statusCode}: ${res.body}`,
+      message: `tools/list returned HTTP ${res.statusCode}: ${String(res.body ?? "").slice(0, 300)}`,
     };
   }
 
@@ -201,7 +365,7 @@ async function sendToolsList(url, apiKey, sessionId) {
     return {
       ok: false,
       tools: [],
-      message: `tools/list returned non-JSON: ${res.body.slice(0, 200)}`,
+      message: `tools/list returned non-JSON: ${String(res.body ?? "").slice(0, 200)}`,
     };
   }
 
@@ -234,6 +398,146 @@ async function sendToolsList(url, apiKey, sessionId) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Internal: tools/call for the canary
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a `tools/call` request and unwrap the MCP content envelope.
+ *
+ * Returns `{ok, text, message}` where `text` is the first text block (what
+ * Meko tools return as a JSON-encoded string) and `message` is only
+ * populated on the non-ok path. On the non-ok path the message is sanitized
+ * — for tool-level errors emitted as `{"error": "...", "detail": "..."}`,
+ * the discriminator and detail are surfaced; the raw body is never
+ * echoed because it can contain secrets (e.g. `datapack_list` returns
+ * connection strings).
+ *
+ * @param {string} url
+ * @param {string|null} apiKey
+ * @param {string|null} sessionId
+ * @param {string} name - Tool name, e.g. "datapack_list".
+ * @param {object} args - Tool arguments.
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<{ok: boolean, text: string|null, message?: string}>}
+ */
+async function mcpCallTool(url, apiKey, sessionId, name, args, opts = {}) {
+  const payload = {
+    jsonrpc: "2.0",
+    id: Date.now() + Math.floor(Math.random() * 1000),
+    method: "tools/call",
+    params: { name, arguments: args },
+  };
+
+  const timeoutMs = opts.timeoutMs;
+  let res;
+  try {
+    res = await jsonRpcRequest(url, payload, apiKey, sessionId, { timeoutMs });
+  } catch (err) {
+    return {
+      ok: false,
+      text: null,
+      message: `${name} request failed: ${classifyError(err, timeoutMs)}`,
+    };
+  }
+
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    return {
+      ok: false,
+      text: null,
+      message: `${name} returned HTTP ${res.statusCode}: ${String(res.body ?? "").slice(0, 300)}`,
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    return {
+      ok: false,
+      text: null,
+      message: `${name} returned non-JSON at the JSON-RPC envelope.`,
+    };
+  }
+
+  if (parsed.error) {
+    return {
+      ok: false,
+      text: null,
+      message: `${name} error: ${parsed.error.message ?? JSON.stringify(parsed.error)}`,
+    };
+  }
+
+  const text = extractFirstText(parsed.result);
+
+  // Meko tools sometimes encode a tool-level failure inside the text body
+  // (e.g. memory_add returning `{"error": "memory_add_failed", ...}`,
+  // datapack_list returning `{"error": "list_failed", "detail": ...}`).
+  // Surface the discriminator and detail — never the full body, since the
+  // success body of datapack_list contains connection-string secrets and we
+  // can't distinguish before parsing.
+  if (text) {
+    try {
+      const body = JSON.parse(text);
+      if (body && typeof body === "object" && !Array.isArray(body) && typeof body.error === "string") {
+        const detail = typeof body.detail === "string" ? ` (${body.detail})` : "";
+        return {
+          ok: false,
+          text,
+          message: `${name} server error: ${body.error}${detail}`,
+        };
+      }
+    } catch {
+      // Non-JSON bodies are fine — many tools return plain text.
+    }
+  }
+
+  return { ok: true, text };
+}
+
+/**
+ * Meko tool results come back as `{content: [{type:"text", text: "..."}]}`.
+ */
+function extractFirstText(result) {
+  const content = result?.content;
+  if (!Array.isArray(content)) return null;
+  for (const block of content) {
+    if (block && block.type === "text" && typeof block.text === "string") {
+      return block.text;
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse a `datapack_list` response body and return the array of datapacks,
+ * or `null` if the body is not a recognizable datapack list.
+ *
+ * Successful `datapack_list` returns a JSON array; each element has at
+ * minimum a `datapack_id` and `datapack_name`. We accept any array whose
+ * elements look like datapack records — we deliberately don't enumerate or
+ * log the elements since they include credentials.
+ *
+ * @param {string|null} text
+ * @returns {Array|null}
+ */
+function parseDatapackList(text) {
+  if (!text) return null;
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(body)) return null;
+  // Empty array is a meaningful answer (caller treats it as "wrong tenant").
+  if (body.length === 0) return body;
+  const allLookLikeDatapacks = body.every(
+    (entry) => entry && typeof entry === "object" && typeof entry.datapack_id === "string",
+  );
+  return allLookLikeDatapacks ? body : null;
+}
+
 // ---------------------------------------------------------------------------
 // Internal: child process helper
 // ---------------------------------------------------------------------------

package/lib/version-check.mjs

@@ -0,0 +1,178 @@
+/**
+ * version-check.mjs — Optional npm-registry version probe.
+ *
+ * Never throws, never rejects, never blocks the install. Used by the installer
+ * to surface an upgrade hint when a newer @yugabytedb/meko-mcp is available.
+ *
+ * Zero external dependencies (node:https + node:url only), matching the
+ * Design Principles documented in installer/README.md.
+ */
+
+import https from "node:https";
+import { URL } from "node:url";
+
+const REGISTRY_URL =
+  "https://registry.npmjs.org/@yugabytedb/meko-mcp/latest";
+
+/**
+ * Semver-ish comparator. Returns -1 if a<b, 0 if equal, 1 if a>b, or `null`
+ * when the comparison cannot be ordered (e.g. a side contains non-numeric
+ * pre-release tags).
+ *
+ * Deliberately minimal: splits on ".", maps to Number, and compares
+ * lexicographically over the resulting tuple. Does NOT order pre-release
+ * tags (`1.0.0-alpha.1`) — for the installer we only care about stable
+ * releases like 1.0.8 vs 1.0.9. The `null` sentinel lets callers
+ * distinguish "equal" (0) from "incomparable" and fall back to strict
+ * string equality only when actually needed, so identical-but-formatted-
+ * differently versions like `1.0` vs `1.0.0` are NOT flagged as outdated.
+ */
+export function compareSemver(a, b) {
+  const partsA = String(a).split(".").map((x) => Number(x));
+  const partsB = String(b).split(".").map((x) => Number(x));
+  const hasNaN = partsA.some((n) => Number.isNaN(n)) || partsB.some((n) => Number.isNaN(n));
+  if (hasNaN) {
+    return a === b ? 0 : null;
+  }
+  const len = Math.max(partsA.length, partsB.length);
+  for (let i = 0; i < len; i++) {
+    const x = partsA[i] ?? 0;
+    const y = partsB[i] ?? 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Fetch the latest published version of @yugabytedb/meko-mcp from the npm
+ * registry and compare against `currentVersion`.
+ *
+ * Never throws. On any network error, timeout, or parse failure, returns
+ * `{ current, latest: null, isOutdated: false, error: <string> }`.
+ *
+ * @param {object} opts
+ * @param {string} opts.currentVersion — the installed version to compare against.
+ * @param {number} [opts.timeoutMs=2000] — hard cap on the registry request.
+ * @param {boolean} [opts.background=false] — when true, unref the request's
+ *   underlying socket so an in-flight probe does not keep the Node process
+ *   alive after the main install completes. Callers who `await` the result
+ *   (e.g. the `--check-updates` handler) should leave this false.
+ * @returns {Promise<{current: string, latest: string|null, isOutdated: boolean, error?: string}>}
+ */
+export async function checkLatest({ currentVersion, timeoutMs = 2000, background = false, _requestImpl } = {}) {
+  const requestImpl = _requestImpl ?? https.request;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve({ current: currentVersion, ...result });
+    };
+
+    let url;
+    try {
+      url = new URL(REGISTRY_URL);
+    } catch (err) {
+      return done({ latest: null, isOutdated: false, error: `bad-url: ${err.message}` });
+    }
+
+    let req;
+    try {
+      req = requestImpl(
+        {
+          method: "GET",
+          hostname: url.hostname,
+          port: url.port || 443,
+          path: url.pathname + url.search,
+          headers: {
+            Accept: "application/json",
+            "User-Agent": `@yugabytedb/meko-mcp/${currentVersion}`,
+          },
+        },
+        (res) => {
+          if (res.statusCode && res.statusCode >= 400) {
+            // Drain so the socket can be freed, then report error.
+            res.resume();
+            return done({
+              latest: null,
+              isOutdated: false,
+              error: `http ${res.statusCode}`,
+            });
+          }
+          let body = "";
+          res.setEncoding("utf8");
+          res.on("data", (chunk) => (body += chunk));
+          res.on("end", () => {
+            try {
+              const parsed = JSON.parse(body);
+              const latest = parsed?.version;
+              if (typeof latest !== "string" || latest.length === 0) {
+                return done({
+                  latest: null,
+                  isOutdated: false,
+                  error: "registry response missing .version",
+                });
+              }
+              let isOutdated;
+              const cmp = compareSemver(currentVersion, latest);
+              if (cmp === null) {
+                // Incomparable (non-numeric tags). Fall back to strict
+                // string inequality; only flag outdated if they actually
+                // differ as strings.
+                isOutdated = currentVersion !== latest;
+              } else {
+                isOutdated = cmp < 0;
+              }
+              done({ latest, isOutdated });
+            } catch (err) {
+              done({
+                latest: null,
+                isOutdated: false,
+                error: `parse: ${err.message}`,
+              });
+            }
+          });
+          res.on("error", (err) => {
+            done({ latest: null, isOutdated: false, error: err.message });
+          });
+        },
+      );
+    } catch (err) {
+      return done({ latest: null, isOutdated: false, error: err.message });
+    }
+
+    const timer = setTimeout(() => {
+      try {
+        req.destroy(new Error("timeout"));
+      } catch {
+        /* ignore */
+      }
+      done({ latest: null, isOutdated: false, error: "timeout" });
+    }, timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+
+    // In background mode, unref the socket so Node can exit as soon as the
+    // main work finishes even if the registry request is still in flight.
+    // The socket appears on "socket" — not on the request object itself at
+    // construction time — so we subscribe rather than reaching for req.socket.
+    if (background) {
+      req.on("socket", (socket) => {
+        if (socket && typeof socket.unref === "function") socket.unref();
+      });
+    }
+
+    req.on("error", (err) => {
+      clearTimeout(timer);
+      done({ latest: null, isOutdated: false, error: err.message });
+    });
+
+    try {
+      req.end();
+    } catch (err) {
+      clearTimeout(timer);
+      done({ latest: null, isOutdated: false, error: err.message });
+    }
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yugabytedb/meko-mcp",
-  "version": "1.0.8",
+  "version": "1.2.0",
   "description": "Single-line installer for Meko MCP Server across Claude and Cursor clients",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "postpack": "node scripts/bundle-assets.mjs --clean",
     "bundle-assets": "node scripts/bundle-assets.mjs",
     "test": "node --test \"test/*.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"

package/scripts/bundle-assets.mjs

@@ -18,10 +18,18 @@ const PAYLOAD = [
     from: join(repoRoot, "skills", "skills", "meko-mcp-tools"),
     to: join(assetsDir, "skills", "meko-mcp-tools"),
   },
+  {
+    from: join(repoRoot, "skills", "skills", "meko-mcp-tools-desktop"),
+    to: join(assetsDir, "skills", "meko-mcp-tools-desktop"),
+  },
   {
     from: join(repoRoot, "skills", "hooks-handlers"),
     to: join(assetsDir, "hooks-handlers"),
   },
+  {
+    from: join(repoRoot, "skills", "scripts", "package-desktop-skill.sh"),
+    to: join(assetsDir, "scripts", "package-desktop-skill.sh"),
+  },
 ];
 
 const cleaning = process.argv.includes("--clean");