minutes-mcp 0.25.0 → 0.25.2

package/dist/index.d.ts

@@ -411,6 +411,17 @@ export declare function selectCopilotNudges(observation: CopilotNudgeObservation
     since?: string;
     limit?: number;
 }, nowMs?: number): CopilotNudgeReadPage;
+/**
+ * What a person should actually do when the CLI is absent, phrased for the
+ * surface they installed.
+ *
+ * The server downloads a prebuilt CLI on first run, so this text is only ever
+ * reached when that could not complete: no network, a proxy, or a platform
+ * with no published binary. Naming the likely cause matters more than naming
+ * the component, because the reader is usually a Claude Desktop user who never
+ * chose to have a CLI at all (#774).
+ */
+export declare function cliMissingGuidance(platform?: NodeJS.Platform): string;
 declare function runMinutes(args: string[], timeoutMs?: number, signal?: AbortSignal, extraEnv?: Record<string, string>): Promise<{
     stdout: string;
     stderr: string;

package/dist/index.js

@@ -1499,7 +1499,8 @@ else {
 }
 // ── Find the minutes binary ─────────────────────────────────
 function findMinutesBinary() {
-    const isWindows = process.platform === "win32";
+    const platform = process.platform;
+    const isWindows = platform === "win32";
     const ext = isWindows ? ".exe" : "";
     const candidates = [
         join(__dirname, "..", "..", "..", "target", "release", `minutes${ext}`),
@@ -1517,6 +1518,19 @@ function findMinutesBinary() {
                 "/opt/homebrew/bin/minutes",
                 "/usr/local/bin/minutes",
             ]),
+        // Inside the desktop app, which ships the CLI as a sidecar and updates it
+        // with the app. Without this, someone who installed the app and never
+        // opened it has the engine on disk while the extension reports it missing,
+        // and the remedy we print is something they have already done. The app's
+        // own "Set up CLI" symlinks ~/.local/bin above, so this is the path for
+        // people who never clicked it.
+        ...(platform === "darwin"
+            ? [
+                "/Applications/Minutes.app/Contents/MacOS/minutes",
+                join(homedir(), "Applications", "Minutes.app", "Contents", "MacOS", "minutes"),
+                join(homedir(), "Applications", "Minutes Dev.app", "Contents", "MacOS", "minutes"),
+            ]
+            : []),
     ];
     for (const candidate of candidates) {
         if (existsSync(candidate)) {
@@ -1555,7 +1569,7 @@ const COPILOT_SUPPORTED = hasFeature(CLI_CAPABILITIES, "copilot_realtime");
 // `./version.ts` (see issue #183). Hosted `.mcpb` bundles will run
 // against CLIs with different minor/patch numbers within the same
 // major; that is explicitly supported.
-const MCP_SERVER_VERSION = "0.25.0";
+const MCP_SERVER_VERSION = "0.25.2";
 export function parseKnowledgeConfig(configContent) {
     const knowledgeMatch = configContent.match(/\[knowledge\][\s\S]*?(?=\n\[|$)/);
     if (!knowledgeMatch) {
@@ -2378,6 +2392,28 @@ export function selectCopilotNudges(observation, options, nowMs = Date.now()) {
  * than several.
  */
 const MCP_CLI_MAX_STDOUT_BYTES = 64 * 1024 * 1024;
+/**
+ * What a person should actually do when the CLI is absent, phrased for the
+ * surface they installed.
+ *
+ * The server downloads a prebuilt CLI on first run, so this text is only ever
+ * reached when that could not complete: no network, a proxy, or a platform
+ * with no published binary. Naming the likely cause matters more than naming
+ * the component, because the reader is usually a Claude Desktop user who never
+ * chose to have a CLI at all (#774).
+ */
+export function cliMissingGuidance(platform = process.platform) {
+    // Only macOS and Windows have a desktop app. Linux ships the CLI alone, so
+    // pointing a Linux user at "the app" sends them to a download that does not
+    // exist.
+    const manual = platform === "darwin" || platform === "win32"
+        ? "Install the free Minutes desktop app from https://useminutes.app, which includes the engine and keeps it updated."
+        : "Install the Minutes CLI from https://useminutes.app, or run `cargo install minutes-cli`.";
+    return ("The Minutes engine is not installed yet. Minutes normally installs it " +
+        "automatically on first run, so this usually means it could not be " +
+        "downloaded: no internet access, a proxy, or an unsupported platform. " +
+        `${manual} Then restart this app.`);
+}
 async function runMinutes(args, timeoutMs = 30000, signal, extraEnv = {}) {
     try {
         const { stdout, stderr } = await execFileAsync(MINUTES_BIN, args, {
@@ -2392,6 +2428,16 @@ async function runMinutes(args, timeoutMs = 30000, signal, extraEnv = {}) {
         if (error.killed) {
             throw new Error(`Command timed out after ${timeoutMs}ms`);
         }
+        // Every tool reaches the CLI through here, including the readiness probe
+        // behind the content-bearing tools, so this one branch is what turns a
+        // missing engine into advice instead of ENOENT.
+        if (error?.code === "ENOENT") {
+            const missing = new Error(cliMissingGuidance());
+            // Tagged rather than string-matched, so callers that deliberately keep
+            // their own failures opaque can still let this one through.
+            missing.cliMissing = true;
+            throw missing;
+        }
         const stderr = error.stderr?.trim() || "";
         const stdout = error.stdout?.trim() || "";
         // Preserve both streams on the thrown error: some commands (e.g.
@@ -2442,7 +2488,14 @@ export async function readAgentTrustReadiness(runner = runMinutes) {
     try {
         ({ stdout } = await runner(["agent-readiness", "--json"]));
     }
-    catch {
+    catch (error) {
+        // A malformed or unverifiable readiness answer stays opaque on purpose:
+        // the caller must not learn why the boundary refused. A missing engine is
+        // not that. It is the reader's own machine state, it is already printed by
+        // the capture tools, and withholding it leaves a Claude Desktop user with
+        // "could not be verified safely" and nothing to do about it (#774).
+        if (error?.cliMissing)
+            throw error;
         throw new Error("Minutes agent readiness could not be verified safely.");
     }
     let result;
@@ -2470,7 +2523,7 @@ export async function requireAgentTrustReadiness(runner = runMinutes) {
     const readiness = await readAgentTrustReadiness(runner);
     if (!readiness.ready) {
         throw new Error(readiness.remediation ||
-            "Run `minutes qmd cleanup`, repair or reinstall qmd if requested, then restart Minutes.");
+            "This machine shows a Minutes-owned QMD registration that qmd could not confirm was removed. Make sure `qmd` runs (`qmd collection list`), then run `minutes qmd cleanup` and restart Minutes.");
     }
     return readiness;
 }
@@ -7099,6 +7152,24 @@ function printUsage() {
     ].join("\n"));
 }
 // ── Start server ────────────────────────────────────────────
+/**
+ * Probe for the engine at startup, install it if possible, and say what
+ * happened. Never throws: startup does not depend on the outcome.
+ */
+async function announceCliAvailability() {
+    let available = false;
+    try {
+        available = await isCliAvailable();
+    }
+    catch {
+        // A probe that fails is the same as one that says no.
+    }
+    crashTrace(available ? "required-cli-ready" : "required-cli-absent");
+    if (!available) {
+        console.error(`[Minutes] ${cliMissingGuidance()}`);
+        console.error("[Minutes] Starting anyway so tools can report this. Tools that need the engine will explain it.");
+    }
+}
 async function main() {
     crashTrace("main-start");
     const config = parseTransportConfig(process.argv.slice(2));
@@ -7108,8 +7179,8 @@ async function main() {
     }
     if (config.transport === "http") {
         crashTrace("main-transport-http", { port: config.port });
-        await afterRequiredCli(async () => {
-            crashTrace("required-cli-ready");
+        await announceCliAvailability();
+        {
             const httpServer = await startMinutesHttpServer({
                 port: config.port,
                 maxSessions: config.maxSessions,
@@ -7123,16 +7194,21 @@ async function main() {
             };
             process.once("SIGINT", shutdown);
             process.once("SIGTERM", shutdown);
-        });
+        }
         return;
     }
-    await afterRequiredCli(async () => {
-        crashTrace("required-cli-ready");
-        const transport = new StdioServerTransport();
-        crashTrace("transport-created");
-        await server.connect(transport);
-        crashTrace("transport-connected");
-    });
+    // The handshake is never gated on the engine. Refusing to start buys no
+    // safety over refusing each operation, because completing a handshake and
+    // listing tools exposes nothing, and every tool that touches content still
+    // checks readiness on each call. What it did cost was the entire diagnosis:
+    // a user whose auto-install could not reach the network got a server that
+    // exited before saying anything, which reads as a broken extension rather
+    // than a missing dependency (#774, reported against v0.25.0).
+    await announceCliAvailability();
+    const transport = new StdioServerTransport();
+    crashTrace("transport-created");
+    await server.connect(transport);
+    crashTrace("transport-connected");
     console.error("Minutes MCP server running on stdio");
 }
 crashTrace("pre-main-guard", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minutes-mcp",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "description": "MCP server for minutes \u2014 conversation memory for AI assistants. Works with Claude Desktop, Mistral Vibe, Cursor, Windsurf, and any MCP client.",
   "main": "dist/index.js",
   "type": "module",
@@ -45,7 +45,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.6.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "minutes-sdk": "0.25.0",
+    "minutes-sdk": "0.25.2",
     "yaml": "^2.8.3",
     "zod": "^3.25 || ^4.0"
   },