perplexity-user-mcp 0.8.39 → 0.8.42

package/README.md

@@ -377,6 +377,11 @@ Logging in still goes through the CLI (`npx perplexity-user-mcp login`) — the
 - A browser runtime — any of: real Chrome, Microsoft Edge, Brave, system Chromium, or patchright's bundled Chromium (see the [Browser requirement](#browser-requirement) section)
 - An active Perplexity account (free tier works; Pro/Max unlock reason/research/compute)
 
+## Troubleshooting
+
+- **External MCP clients hitting "Vault locked":** [Troubleshooting external MCP clients](../../docs/troubleshooting/external-mcp-clients.md)
+- **Vault unseal model and recovery:** [docs/vault-unseal.md](../../docs/vault-unseal.md)
+
 ## Issues
 
 Bug reports and feature requests: <https://github.com/Automations-Project/VSCode-Perplexity-MCP/issues>.

package/dist/{chunk-NJX4RBO6.mjs → chunk-Z4OLYVB2.mjs}

@@ -5,6 +5,22 @@ import {
 // src/daemon/attach.ts
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+var DaemonAttachError = class extends Error {
+  code = "DAEMON_UNREACHABLE";
+  remediation;
+  cause;
+  constructor(message, remediation, cause) {
+    super(message);
+    this.name = "DaemonAttachError";
+    this.remediation = remediation;
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+var DEFAULT_REMEDIATION = [
+  "Reload the VS Code window so the extension restarts the daemon.",
+  "In the VS Code Perplexity dashboard, switch this client's transport to http-loopback.",
+  "(Advanced) Set PERPLEXITY_NO_DAEMON=1 in this client's MCP env block, then run `npx perplexity-user-mcp setup-vault` once."
+];
 async function attachToDaemon(options = {}) {
   const ensure = options.dependencies?.ensureDaemon ?? ensureDaemon;
   const sourceIn = options.stdin ?? process.stdin;
@@ -20,7 +36,11 @@ async function attachToDaemon(options = {}) {
       await runFallback(error, options);
       return;
     }
-    throw error;
+    throw new DaemonAttachError(
+      `Cannot reach the extension-managed daemon: ${asError(error).message}`,
+      DEFAULT_REMEDIATION,
+      error
+    );
   }
   const stdio = new StdioServerTransport(sourceIn, sourceOut);
   const http = new StreamableHTTPClientTransport(new URL(`${daemon.url}/mcp`), {
@@ -77,7 +97,11 @@ async function attachToDaemon(options = {}) {
       await runFallback(error, options);
       return;
     }
-    throw error;
+    throw new DaemonAttachError(
+      `Daemon attached but transport failed to start: ${asError(error).message}`,
+      DEFAULT_REMEDIATION,
+      error
+    );
   }
   await completion;
 }
@@ -102,5 +126,6 @@ function asError(error) {
 }
 
 export {
+  DaemonAttachError,
   attachToDaemon
 };

package/dist/cli.d.ts

@@ -486,12 +486,31 @@ async function routeCommand(parsed) {
       typeof ensureTimeoutRaw === "string" && /^\d+$/.test(ensureTimeoutRaw)
         ? Number(ensureTimeoutRaw)
         : undefined;
-    await attachToDaemon({
-      configDir: process.env.PERPLEXITY_CONFIG_DIR,
-      clientId: "daemon-attach-cli",
-      fallbackStdio: !!flags["fallback-stdio"],
-      ensureTimeoutMs,
-    });
+    try {
+      await attachToDaemon({
+        configDir: process.env.PERPLEXITY_CONFIG_DIR,
+        clientId: "daemon-attach-cli",
+        fallbackStdio: !!flags["fallback-stdio"],
+        ensureTimeoutMs,
+      });
+    } catch (err) {
+      // Phase 2 / Task 2.4: mirror the launcher's DaemonAttachError contract.
+      // Stdout is the JSON-RPC framing channel for the attached client, so the
+      // bullet remediation must land on stderr only; the script entry below
+      // converts code:2 into process.exit(2).
+      if (err && err.code === "DAEMON_UNREACHABLE") {
+        let stderr = "Perplexity MCP: cannot reach the extension-managed daemon.\n";
+        const remediation = Array.isArray(err.remediation) ? err.remediation : [];
+        for (const line of remediation) {
+          stderr += "  • " + line + "\n";
+        }
+        if (err.cause && err.cause.message) {
+          stderr += "Underlying error: " + err.cause.message + "\n";
+        }
+        return { code: 2, stdout: "", stderr };
+      }
+      throw err;
+    }
     return { code: 0, stdout: "", stderr: "" };
   }
 

package/dist/cli.mjs

@@ -402,12 +402,27 @@ Run --help for usage.` };
     const { attachToDaemon } = await import("./daemon/attach.mjs");
     const ensureTimeoutRaw = flags["ensure-timeout-ms"];
     const ensureTimeoutMs = typeof ensureTimeoutRaw === "string" && /^\d+$/.test(ensureTimeoutRaw) ? Number(ensureTimeoutRaw) : void 0;
-    await attachToDaemon({
-      configDir: process.env.PERPLEXITY_CONFIG_DIR,
-      clientId: "daemon-attach-cli",
-      fallbackStdio: !!flags["fallback-stdio"],
-      ensureTimeoutMs
-    });
+    try {
+      await attachToDaemon({
+        configDir: process.env.PERPLEXITY_CONFIG_DIR,
+        clientId: "daemon-attach-cli",
+        fallbackStdio: !!flags["fallback-stdio"],
+        ensureTimeoutMs
+      });
+    } catch (err) {
+      if (err && err.code === "DAEMON_UNREACHABLE") {
+        let stderr = "Perplexity MCP: cannot reach the extension-managed daemon.\n";
+        const remediation = Array.isArray(err.remediation) ? err.remediation : [];
+        for (const line of remediation) {
+          stderr += "  \u2022 " + line + "\n";
+        }
+        if (err.cause && err.cause.message) {
+          stderr += "Underlying error: " + err.cause.message + "\n";
+        }
+        return { code: 2, stdout: "", stderr };
+      }
+      throw err;
+    }
     return { code: 0, stdout: "", stderr: "" };
   }
   if (command === "daemon:install-tunnel") {

package/dist/daemon/attach.d.ts

@@ -5,6 +5,12 @@ import '../config.js';
 import 'patchright';
 import './lockfile.js';
 
+declare class DaemonAttachError extends Error {
+    readonly code = "DAEMON_UNREACHABLE";
+    readonly remediation: readonly string[];
+    readonly cause?: unknown;
+    constructor(message: string, remediation: readonly string[], cause?: unknown);
+}
 interface AttachToDaemonOptions {
     configDir?: string;
     stdin?: Readable;
@@ -33,4 +39,4 @@ interface AttachToDaemonOptions {
 }
 declare function attachToDaemon(options?: AttachToDaemonOptions): Promise<void>;
 
-export { type AttachToDaemonOptions, attachToDaemon };
+export { type AttachToDaemonOptions, DaemonAttachError, attachToDaemon };

package/dist/daemon/attach.mjs

@@ -1,6 +1,7 @@
 import {
+  DaemonAttachError,
   attachToDaemon
-} from "../chunk-NJX4RBO6.mjs";
+} from "../chunk-Z4OLYVB2.mjs";
 import "../chunk-RK4EBZJ3.mjs";
 import "../chunk-XTRJSV72.mjs";
 import "../chunk-6YMQVLFX.mjs";
@@ -21,5 +22,6 @@ import "../chunk-MTDFKNXX.mjs";
 import "../chunk-HJIXH6CL.mjs";
 import "../chunk-4UEJOM6W.mjs";
 export {
+  DaemonAttachError,
   attachToDaemon
 };

package/dist/daemon/index.mjs

@@ -5,7 +5,7 @@ import {
 } from "../chunk-452DK6OS.mjs";
 import {
   attachToDaemon
-} from "../chunk-NJX4RBO6.mjs";
+} from "../chunk-Z4OLYVB2.mjs";
 import {
   disableDaemonTunnel,
   enableDaemonTunnel,

package/dist/index.mjs

@@ -12,7 +12,7 @@ import {
 } from "./chunk-DPGMKSSA.mjs";
 import {
   attachToDaemon
-} from "./chunk-NJX4RBO6.mjs";
+} from "./chunk-Z4OLYVB2.mjs";
 import {
   ensureDaemon,
   startDaemon

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perplexity-user-mcp",
-  "version": "0.8.39",
+  "version": "0.8.42",
   "mcpName": "io.github.Automations-Project/perplexity-user-mcp",
   "type": "module",
   "description": "Perplexity AI MCP server — browser automation for search, reasoning, research, and compute. Not affiliated with Perplexity AI, Inc.",
@@ -33,7 +33,7 @@
     "provenance": true
   },
   "engines": {
-    "node": ">=20"
+    "node": "^22.0.0 || ^24.0.0"
   },
   "keywords": [
     "perplexity",