pi-mcp-adapter 3.3.0 → 5.0.0

package/cli.js

@@ -3,6 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import stripJsonComments from "strip-json-comments";
 
@@ -74,6 +75,10 @@ function printHelp(log = console.log) {
   log("  pi-mcp-adapter init --dry-run");
   log("  pi-mcp-adapter init --discover-host-configs  Opt in to host config fallback discovery");
   log("");
+  log("Check configured servers (exits 1 when an enabled server fails):");
+  log("  pi-mcp-adapter doctor         Connect each enabled server and report its state and tool count");
+  log("  pi-mcp-adapter doctor --json  Print the same report as a JSON array");
+  log("");
   log("Bearer token storage (servers configured with auth: \"bearer\" and bearerTokenStore: true):");
   log("  pi-mcp-adapter token set <server>     Store a token read from stdin (masked prompt or pipe; never argv)");
   log("  pi-mcp-adapter token status <server>  Report whether a stored token matches the configured URL");
@@ -413,6 +418,207 @@ async function runKey(argv, log, error, stdin) {
   return 0;
 }
 
+const DOCTOR_CONNECT_TIMEOUT_MS = 15_000;
+
+// A second layer behind describeConnectError: messages can still name configured values.
+// Values under 4 characters are flags such as DEBUG=1, and redacting them would garble the text.
+function redactDoctorMessage(text, definition, utils) {
+  const configured = [definition.bearerToken, definition.oauth?.clientSecret, ...Object.values(definition.headers ?? {}), ...Object.values(definition.env ?? {})];
+  if (definition.bearerTokenEnv) configured.push(process.env[definition.bearerTokenEnv]);
+  if (typeof definition.url === "string") {
+    try {
+      configured.push(...new URL(utils.interpolateEnvVars(definition.url)).searchParams.values());
+    } catch {
+      // An invalid URL is reported without its value.
+    }
+  }
+  const secrets = configured
+    .filter((value) => typeof value === "string")
+    .flatMap((value) => [value, utils.interpolateEnvVars(value)])
+    .flatMap((value) => [value, ...value.split(/\s+/)])
+    .filter((value) => value.length >= 4)
+    .sort((left, right) => right.length - left.length);
+  let redacted = text;
+  for (const secret of secrets) redacted = redacted.replaceAll(secret, "***");
+  return redacted;
+}
+
+// Doctor prints only facts the adapter composes, never server-originated text such as HTTP
+// response bodies or child stderr: those can carry secrets that no configured value reveals.
+function describeConnectError(err, definition, url) {
+  if (!definition.url) {
+    // server-manager appends the child's stderr as `${message} (${stderr})`, keeping the original as cause.
+    const base = err.cause instanceof Error && err.message.startsWith(`${err.cause.message} (`) ? err.cause : err;
+    const message = typeof base.code === "number" ? `server returned JSON-RPC error ${base.code}` : base.message;
+    return definition.command ? `${message} — run the command directly to see its output` : message;
+  }
+  // Adapter-composed failures of secret commands and CA files, thrown before any response.
+  if (/^(Failed to resolve MCP server|HTTP request headers command|MCP caFile|Missing environment variable in MCP caFile)/.test(err.message)) {
+    return err.message;
+  }
+  let status;
+  const codes = new Set();
+  const pending = [err];
+  const seen = new Set();
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (typeof current !== "object" || current === null || seen.has(current)) continue;
+    seen.add(current);
+    if (typeof current.status === "number") status ??= current.status;
+    status ??= /\(HTTP (\d{3})\)/.exec(current.message ?? "")?.[1];
+    if (typeof current.code === "string" && /^E[A-Z]+$/.test(current.code)) codes.add(current.code);
+    pending.push(current.cause, current.data?.cause, ...(current instanceof AggregateError ? current.errors : []));
+  }
+  const parts = [...(status ? [`HTTP ${status}`] : []), ...codes];
+  // server-manager appends the probe classification to the original message, keeping it as cause.
+  const suffix = err.cause instanceof Error && err.message.startsWith(err.cause.message) ? err.message.slice(err.cause.message.length) : "";
+  if (suffix.startsWith(" — probe: ")) parts.push(suffix.slice(3));
+  if (codes.has("ECONNREFUSED") && ["localhost", "127.0.0.1", "[::1]"].includes(new URL(url).hostname)) {
+    const configured = definition.url.replace(/[?#].*$/s, "").replace(/^([a-z][a-z\d+.-]*:\/\/)[^/]*@/i, "$1");
+    parts.push(`Nothing is listening at ${configured}. Start the app or local process that serves this MCP server.`);
+  }
+  return parts.length > 0 ? parts.join(" — ") : "connection failed";
+}
+
+async function runDoctor(argv, log, error) {
+  const json = argv[0] === "--json";
+  if (argv.length > (json ? 1 : 0)) {
+    error("Usage: pi-mcp-adapter doctor [--json]");
+    return 1;
+  }
+  let config, trust, manager, auth, authFlow, utils, agentDir;
+  try {
+    [config, trust, manager, auth, authFlow, utils, agentDir] = await Promise.all([
+      import("./dist/config.js"),
+      import("./dist/project-server-trust.js"),
+      import("./dist/server-manager.js"),
+      import("./dist/mcp-auth.js"),
+      import("./dist/mcp-auth-flow.js"),
+      import("./dist/utils.js"),
+      import("./dist/agent-dir.js"),
+    ]);
+  } catch (err) {
+    error("Unable to load doctor command modules.");
+    error(`Import failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+
+  const cwd = process.cwd();
+  // Pi 0.99+ owns ~/.pi/agent/mcp.json and .pi/mcp.json; older Pi used those names for adapter config.
+  const piVersion = spawnSync("pi", ["--version"], { encoding: "utf8", timeout: 5_000, shell: process.platform === "win32" }).stdout ?? "";
+  const [major, minor] = piVersion.trim().split(".").map(Number);
+  const piSupportsMcp = major > 0 || minor >= 99;
+  config.setPiMcpConfigEnabled(piSupportsMcp);
+  if (!piSupportsMcp && [config.getPiMcpGlobalConfigPath(), config.getProjectPiMcpConfigPath(cwd)].some((file) => fs.existsSync(file))) {
+    error("Pi 0.99 or later wasn't found on PATH, so Pi's own mcp.json files were not checked.");
+  }
+  const loaded = config.loadMcpConfigWithSources(undefined, cwd);
+  let projectTrusted = false;
+  if (loaded.projectServers.size > 0) {
+    try {
+      // Pi is a peer dependency and may not resolve from where this CLI is installed.
+      const { ProjectTrustStore } = await import("@earendil-works/pi-coding-agent");
+      projectTrusted = new ProjectTrustStore(agentDir.getAgentDir()).get(cwd) === true;
+    } catch (err) {
+      error(`Could not read Pi's project trust, so project servers are treated as untrusted: ${utils.formatTerminalError(err)}`);
+    }
+  }
+  const { config: effective, blockedServers } = await trust.applyProjectServerTrust(loaded, {
+    cwd,
+    hasUI: false,
+    isProjectTrusted: () => projectTrusted,
+  });
+  const authOptions = auth.getAuthStorageOptions(effective.settings?.oauthDir, cwd, effective.settings?.oauthCredentialStore);
+  const serverManager = new manager.McpServerManager(cwd);
+  serverManager.setDefaultRequestTimeoutMs(effective.settings?.requestTimeoutMs);
+  serverManager.setAuthStorageOptions(authOptions);
+
+  const check = async (name, definition, signal) => {
+    const block = blockedServers.get(name);
+    if (block) return { state: "blocked", message: trust.describeProjectServerBlock(block.reason) };
+    if (definition.disabled === true) return { state: "disabled" };
+    // The doctor has no Pi model registry to read the provider token from, so it never connects these servers.
+    if (definition.url && typeof definition.auth === "object") {
+      return { state: "needs-auth", message: `signs in with a Pi provider: run /login ${definition.auth.provider} in Pi` };
+    }
+    const needsSignIn = { state: "needs-auth", message: `sign-in required: run /mcp-auth ${name} in Pi` };
+    let anonymous = false;
+    let url;
+    if (definition.url) {
+      try {
+        url = utils.resolveServerUrl(definition);
+      } catch {
+        const missing = typeof definition.url === "string" ? utils.getMissingEnvVars(definition.url) : [];
+        return { state: "failed", message: missing.length > 0 ? `URL uses unset environment variables: ${missing.join(", ")}` : "URL is invalid" };
+      }
+      // Report a missing sign-in from stored credentials instead of starting OAuth.
+      if (authFlow.supportsOAuth(definition)) {
+        const stored = auth.inspectAuthForUrl(name, url, authOptions);
+        if (stored.status === "unavailable") return { state: "failed", message: stored.message };
+        // A record without tokens is an unfinished sign-in.
+        if (stored.status === "absent" || !(stored.entry.tokens?.accessToken || stored.entry.tokens?.refreshToken)) {
+          if (definition.auth === "oauth") return needsSignIn;
+          anonymous = true;
+        }
+      }
+    }
+    // Anonymous attempts get no OAuth provider, and debug stderr would bypass redaction.
+    const connectDefinition = { ...definition, debug: false, ...(anonymous ? { oauth: false } : {}) };
+    try {
+      const connection = await serverManager.connect(name, connectDefinition, signal);
+      return connection.status === "needs-auth" ? needsSignIn : { state: "ok", tools: connection.tools.length };
+    } catch (err) {
+      if (anonymous && [err, err?.cause].some(manager.isUnauthorizedHttpError)) return needsSignIn;
+      return { state: "failed", message: describeConnectError(err, definition, url) };
+    }
+  };
+
+  const results = await Promise.all(Object.entries(effective.mcpServers).map(async ([name, definition]) => {
+    // The deadline covers the whole check, including server-manager's follow-up probe.
+    const controller = new AbortController();
+    let timer;
+    const timedOut = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        resolve({ state: "failed", message: `no response within ${DOCTOR_CONNECT_TIMEOUT_MS / 1000}s` });
+      }, DOCTOR_CONNECT_TIMEOUT_MS);
+    });
+    const result = await Promise.race([
+      check(name, definition, controller.signal).catch((err) => ({ state: "failed", message: utils.formatTerminalError(err) })),
+      timedOut,
+    ]);
+    clearTimeout(timer);
+    return {
+      name,
+      state: result.state,
+      tools: result.tools ?? null,
+      message: result.message ? utils.sanitizeTerminalText(redactDoctorMessage(result.message, definition, utils)) : null,
+    };
+  }));
+
+  // Report first: closing waits for timed-out attempts to settle and can fail.
+  let closed = true;
+  try {
+    if (json) {
+      log(JSON.stringify(results, null, 2));
+    } else {
+      if (results.length === 0) log("No MCP servers configured.");
+      for (const result of results) {
+        const tools = result.tools === null ? "" : `, ${result.tools} tool${result.tools === 1 ? "" : "s"}`;
+        log(`${utils.sanitizeTerminalText(result.name)}: ${result.state}${tools}${result.message ? ` — ${result.message}` : ""}`);
+      }
+    }
+  } finally {
+    try {
+      await serverManager.closeAll();
+    } catch (err) {
+      closed = false;
+      error(`Some MCP connections did not close cleanly: ${utils.formatTerminalError(err)}`);
+    }
+  }
+  return !closed || results.some((result) => result.state === "failed" || result.state === "needs-auth") ? 1 : 0;
+}
+
 export async function main(argv = process.argv.slice(2), log = console.log, error = console.error, stdin = process.stdin) {
   const [command, ...rest] = argv;
 
@@ -429,6 +635,10 @@ export async function main(argv = process.argv.slice(2), log = console.log, erro
     return runKey(rest, log, error, stdin);
   }
 
+  if (command === "doctor") {
+    return runDoctor(rest, log, error);
+  }
+
   if (command === "install") {
     error("The custom downloader has been retired.");
     error("Use `pi install npm:pi-mcp-adapter` instead, then optionally run `pi-mcp-adapter init`.");

package/commands.ts

@@ -1,4 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { isDeepStrictEqual } from "node:util";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { OverlayHandle } from "@earendil-works/pi-tui";
 import type { McpExtensionState } from "./state.ts";
@@ -11,6 +13,7 @@ import {
   type KnownServerPreset,
   type SharedConfigTarget,
   getServerProvenance,
+  loadMcpConfig,
   previewCompatibilityImports,
   previewSharedServerEntry,
   previewStarterSharedConfig,
@@ -29,7 +32,8 @@ import { supportsOAuth, authenticate, removeAuth, type McpOAuthRuntime } from ".
 import { getAuthStorageOptions, inspectAuthForUrl } from "./mcp-auth.ts";
 import { inspectBearerTokenForUrl, removeBearerToken } from "./mcp-bearer-store.ts";
 import { loadOnboardingState, markSetupCompleted as persistSetupCompleted, markSharedConfigHintShown } from "./onboarding-state.ts";
-import { formatTerminalError, openPath, resolveServerUrl, sanitizeTerminalText } from "./utils.ts";
+import { findPiSignInImports, importPiSignIn } from "./pi-signin-import.ts";
+import { formatTerminalError, openPath, providerSignInMessage, resolveServerUrl, sanitizeTerminalText } from "./utils.ts";
 import { isAbortError } from "./runtime-owner.ts";
 import { resolveJevCredential } from "./jev-key-store.ts";
 import { describeProjectServerBlock } from "./project-server-trust.ts";
@@ -302,7 +306,9 @@ export async function reconnectServer(
     state.owner?.throwIfInactive();
     if (connection.status === "needs-auth") {
       if (ui) {
-        ui.notify(`MCP: ${name} requires OAuth. Run /mcp-auth ${name} first.`, "warning");
+        ui.notify(typeof definition.auth === "object"
+          ? `MCP: ${providerSignInMessage(name, definition.auth.provider)}`
+          : `MCP: ${name} requires OAuth. Run /mcp-auth ${name} first.`, "warning");
       }
       updateStatusBar(state);
       return false;
@@ -392,6 +398,11 @@ export async function authenticateServer(
     return { ok: false, message };
   }
 
+  if (typeof definition.auth === "object") {
+    const message = providerSignInMessage(serverName, definition.auth.provider);
+    ui.notify(message, "info");
+    return { ok: false, message };
+  }
   if (!supportsOAuth(definition)) {
     const message = `Server "${serverName}" does not use OAuth authentication. Set "auth": "oauth" or omit auth for auto-detection.`;
     ui.notify(
@@ -587,6 +598,21 @@ function buildSharedConfigNoticeLines(configOverridePath: string | undefined, cw
   };
 }
 
+// Any accepted TCP connection counts as reachable; failures resolve false so the add still succeeds.
+function isLocalServerReachable(url: string, timeoutMs = 1_500): Promise<boolean> {
+  const { hostname, port } = new URL(url);
+  return new Promise((resolve) => {
+    const socket = createConnection({ host: hostname, port: Number(port) });
+    const finish = (reachable: boolean) => {
+      socket.destroy();
+      resolve(reachable);
+    };
+    socket.setTimeout(timeoutMs, () => finish(false));
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+  });
+}
+
 export async function openMcpSetup(
   state: McpExtensionState,
   pi: ExtensionAPI,
@@ -641,7 +667,16 @@ export async function openMcpSetup(
     addKnownServer: async (preset: KnownServerPreset, target: SharedConfigTarget) => {
       const path = writeSharedServerEntry(getSharedConfigPath(target, ctx.cwd), preset.id, preset.entry);
       configChanged = true;
-      return { path, serverName: preset.name };
+      // Merging is per field, so the entry is in effect when every preset field survives it and nothing disables it.
+      const active = loadMcpConfig(configOverridePath, ctx.cwd).mcpServers[preset.id];
+      const ignoredBecause = !active
+        ? `the current config mode doesn't read ${path}`
+        : Object.entries(preset.entry).some(([field, value]) => !isDeepStrictEqual(active[field as keyof typeof active], value))
+          ? `another config file also defines ${preset.id} and takes precedence`
+          : isServerDisabled(active) ? `another config file disables ${preset.id}` : undefined;
+      const result = { path, serverName: preset.name, ...(ignoredBecause ? { ignoredBecause } : {}) };
+      if (!preset.desktopApp) return result;
+      return { ...result, reachable: await isLocalServerReachable(preset.entry.url!) };
     },
     openPath: async (targetPath: string) => {
       await openPath(pi, targetPath);
@@ -659,7 +694,8 @@ export async function openMcpSetup(
           resolve({ configChanged });
         });
       },
-      { overlay: true, overlayOptions: { anchor: "center", width: 92 } },
+      // The panel sizes its height from tui.terminal.rows minus this margin, so it always fits.
+      { overlay: true, overlayOptions: { anchor: "center", width: 92, maxHeight: "100%", margin: { top: 1, bottom: 1 } } },
     );
   });
 }
@@ -766,6 +802,21 @@ export async function openMcpPanel(
 
   const { createMcpPanel } = await import("./mcp-panel.ts");
   let configChanged = false;
+  const authStorageOptions = state.authStorageOptions ?? {};
+  if (findPiSignInImports(config, authStorageOptions).length > 0) {
+    callbacks.importPiSignIns = () => {
+      const imported: string[] = [];
+      const failed: { server: string; error: string }[] = [];
+      for (const candidate of findPiSignInImports(config, authStorageOptions)) {
+        try {
+          if (importPiSignIn(candidate, authStorageOptions)) imported.push(candidate.serverName);
+        } catch (error) {
+          failed.push({ server: candidate.serverName, error: error instanceof Error ? error.message : String(error) });
+        }
+      }
+      return { imported, failed };
+    };
+  }
 
   await new Promise<void>((resolve) => {
     ctx.ui.custom(