@fitchmultz/pi-mcp-adapter 5.0.0

package/checkpoint.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { McpExtensionState } from "./state.ts";
+import { flushMetadataCache } from "./init.ts";
+import { getOAuthCheckpointBlocker, holdOAuthCheckpoint } from "./mcp-auth-flow.ts";
+import { isServerDisabled } from "./types.ts";
+
+/** Optional host event. Published Pi hosts without this event simply never emit it.
+ * Keep its structural typing local; do not require a private host package/version. */
+export interface McpCheckpointEvent {
+  readonly boundary: "turn" | "settled";
+  readonly signal: AbortSignal;
+  invalidate(): void;
+}
+export type McpCheckpointResult = { sleepReady: true } | { sleepReady: false; reason: string };
+export function onSessionCheckpoint(pi: ExtensionAPI, handler: (event: McpCheckpointEvent) => Promise<McpCheckpointResult>): void {
+  (pi.on as unknown as (event: "session_checkpoint", callback: (event: McpCheckpointEvent) => Promise<McpCheckpointResult>) => unknown)("session_checkpoint", handler);
+}
+
+/** No shutdown, credential copying, connection replay or permanent owner cancellation. */
+export async function prepareMcpCheckpoint(state: McpExtensionState, event: McpCheckpointEvent): Promise<McpCheckpointResult> {
+  event.signal.throwIfAborted();
+  const releases: Array<() => void> = [];
+  const release = () => { for (const undo of releases.splice(0).reverse()) undo(); };
+  // Fence all owned sources synchronously, before the first await (including trace flush).
+  event.signal.addEventListener("abort", release, { once: true });
+  const undo = () => { release(); event.signal.removeEventListener("abort", release); };
+  const blocked = (reason: string): McpCheckpointResult => { undo(); return { sleepReady: false, reason }; };
+  try {
+    releases.push(state.owner.holdCheckpoint(event));
+    releases.push(state.manager.holdCheckpoint(event));
+    releases.push(holdOAuthCheckpoint(state.oauthRuntime, event));
+    releases.push(state.lifecycle.pauseForCheckpoint());
+    if (state.lifecycle.hasActiveHealthCheck()) return blocked("MCP health check is active");
+    for (const [name, definition] of Object.entries(state.config.mcpServers)) {
+      if (!isServerDisabled(definition) && !definition.url) return blocked(`MCP ${name}: stdio/Unix server state is not reconstructible`);
+    }
+    const callback = state.owner.getCheckpointBlocker();
+    if (callback) return blocked(callback);
+    if (state.activeScripts) return blocked("MCP script is active");
+    if (state.uiServer || state.completedUiSessions.length) return blocked("MCP UI session/messages require the running runtime");
+    if (state.approvedToolCalls.size || state.consentManager.hasDecisions()) return blocked("MCP session approvals are not persisted");
+    const oauth = getOAuthCheckpointBlocker(state.oauthRuntime);
+    if (oauth) return blocked(oauth);
+    const manager = state.manager.getCheckpointBlocker();
+    if (manager) return blocked(manager);
+    flushMetadataCache(state);
+    await state.manager.flushForCheckpoint();
+    event.signal.throwIfAborted();
+    // Release/cancellation is host-owned. Existing clients/timers remain usable afterwards.
+    return { sleepReady: true };
+  } catch (error) {
+    undo();
+    throw error;
+  }
+}

package/cli.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { pathToFileURL } from "node:url";
+import stripJsonComments from "strip-json-comments";
+
+const HOME = os.homedir();
+
+function expandHome(input) {
+  if (input === "~") return HOME;
+  if (input.startsWith("~/")) return path.resolve(HOME, input.slice(2));
+  return path.resolve(input);
+}
+
+const AGENT_DIR = process.env.PI_CODING_AGENT_DIR?.trim()
+  ? expandHome(process.env.PI_CODING_AGENT_DIR.trim())
+  : path.join(HOME, ".pi", "agent");
+const PI_CONFIG_PATH = path.join(AGENT_DIR, "fitch-mcp-adapter", "mcp.json");
+const GENERIC_GLOBAL_CONFIG_PATH = path.join(HOME, ".config", "mcp", "mcp.json");
+const AGENTS_GLOBAL_CONFIG_PATH = path.join(HOME, ".agents", "mcp.json");
+const AGENTS_NESTED_GLOBAL_CONFIG_PATH = path.join(HOME, ".agents", "mcp", "mcp.json");
+const PROJECT_CONFIG_PATH = path.resolve(process.cwd(), ".mcp.json");
+const PROJECT_PI_CONFIG_PATH = path.resolve(process.cwd(), ".pi", "fitch-mcp-adapter", "mcp.json");
+
+const IMPORT_PATHS = {
+  cursor: [path.join(HOME, ".cursor", "mcp.json")],
+  "claude-code": [
+    path.join(HOME, ".claude", "mcp.json"),
+    path.join(HOME, ".claude.json"),
+    path.join(HOME, ".claude", "claude_desktop_config.json"),
+  ],
+  "claude-desktop": [path.join(HOME, "Library", "Application Support", "Claude", "claude_desktop_config.json")],
+  codex: [
+    path.join(HOME, ".codex", "config.toml"),
+    path.join(HOME, ".codex", "config.json"),
+  ],
+  opencode: [
+    path.join(HOME, ".config", "opencode", "opencode.json"),
+    path.resolve(process.cwd(), "opencode.json"),
+  ],
+  windsurf: [path.join(HOME, ".windsurf", "mcp.json")],
+  vscode: [path.resolve(process.cwd(), ".vscode", "mcp.json")],
+};
+
+function printHelp(log = console.log) {
+  log("Fitch MCP Adapter helper\n");
+  log("Install the package with:");
+  log("  pi install npm:@fitchmultz/pi-mcp-adapter\n");
+  log("Then optionally run:");
+  log("  fitch-mcp-adapter init       Detect host configs and scaffold Pi imports");
+  log("  fitch-mcp-adapter init --dry-run");
+  log("  fitch-mcp-adapter init --discover-host-configs  Opt in to host config fallback discovery");
+  log("  fitch-mcp-adapter migrate [--dry-run]  Copy pre-v5 state without changing its sources");
+}
+
+function readJsonFile(filePath) {
+  return JSON.parse(stripJsonComments(fs.readFileSync(filePath, "utf-8"), { trailingCommas: true }));
+}
+
+function loadPiConfig() {
+  if (!fs.existsSync(PI_CONFIG_PATH)) {
+    return { mcpServers: {} };
+  }
+
+  const raw = readJsonFile(PI_CONFIG_PATH);
+  const mcpServers = raw.mcpServers ?? raw["mcp-servers"] ?? {};
+  if (!mcpServers || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+    throw new Error(`Invalid MCP config at ${PI_CONFIG_PATH}: expected \"mcpServers\" to be an object`);
+  }
+
+  const normalized = { ...raw };
+  delete normalized["mcp-servers"];
+
+  const imports = Array.isArray(raw.imports) ? raw.imports.filter((value) => typeof value === "string") : undefined;
+  return {
+    ...normalized,
+    mcpServers,
+    imports,
+  };
+}
+
+function findAvailableImports() {
+  const found = [];
+
+  for (const [kind, candidates] of Object.entries(IMPORT_PATHS)) {
+    const existing = candidates.find((candidate) => fs.existsSync(candidate));
+    if (existing) {
+      found.push({ kind, path: existing });
+    }
+  }
+
+  return found;
+}
+
+function printDiscovery(log, imports) {
+  log("Config discovery:\n");
+
+  const paths = [
+    ["User-global standard MCP", GENERIC_GLOBAL_CONFIG_PATH],
+    ["User-global .agents MCP", AGENTS_GLOBAL_CONFIG_PATH],
+    ["User-global .agents nested MCP", AGENTS_NESTED_GLOBAL_CONFIG_PATH],
+    ["Pi global override", PI_CONFIG_PATH],
+    ["Project standard MCP", PROJECT_CONFIG_PATH],
+    ["Project Pi override", PROJECT_PI_CONFIG_PATH],
+  ];
+
+  for (const [label, filePath] of paths) {
+    const prefix = fs.existsSync(filePath) ? "✓" : "-";
+    log(`${prefix} ${label}: ${filePath}`);
+  }
+
+  log("\nCompatibility imports:\n");
+  if (imports.length === 0) {
+    log("- No host-specific MCP configs detected");
+    return;
+  }
+
+  for (const entry of imports) {
+    log(`✓ ${entry.kind}: ${entry.path}`);
+  }
+}
+
+function writePiConfig(config) {
+  fs.mkdirSync(path.dirname(PI_CONFIG_PATH), { recursive: true });
+  fs.writeFileSync(PI_CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+
+async function runInit(argv, log = console.log) {
+  const dryRun = argv.includes("--dry-run");
+  const discoverHostConfigs = argv.includes("--discover-host-configs");
+  const foundImports = findAvailableImports();
+  const existingConfig = loadPiConfig();
+  const existingImports = new Set(existingConfig.imports ?? []);
+  const importsToAdd = foundImports
+    .map((entry) => entry.kind)
+    .filter((kind) => !existingImports.has(kind));
+
+  printDiscovery(log, foundImports);
+
+  const discoverySettingChanged = discoverHostConfigs && existingConfig.settings?.hostConfigDiscovery !== "on";
+  if (importsToAdd.length === 0 && !discoverySettingChanged) {
+    log("\nNo Pi config changes needed.");
+    log("Standard MCP configs are discovered automatically, and host-specific imports are already configured or unavailable.");
+    return 0;
+  }
+
+  const nextConfig = {
+    ...existingConfig,
+    ...(discoverySettingChanged ? { settings: { ...existingConfig.settings, hostConfigDiscovery: "on" } } : {}),
+    ...(importsToAdd.length > 0 ? { imports: [...existingImports, ...importsToAdd] } : {}),
+    mcpServers: existingConfig.mcpServers ?? {},
+  };
+
+  if (importsToAdd.length > 0) {
+    log(`\nDetected host configs to import into Pi: ${importsToAdd.join(", ")}`);
+  }
+  if (discoverySettingChanged) {
+    log("Opting in to host-specific fallback discovery (standard and Pi-owned configs still take precedence).");
+  }
+
+  if (dryRun) {
+    log(`Dry run: would update ${PI_CONFIG_PATH}`);
+    return 0;
+  }
+
+  writePiConfig(nextConfig);
+  log(`Updated ${PI_CONFIG_PATH}`);
+  log("Pi will now keep reading standard MCP configs automatically, while these imports cover host-specific config formats.");
+  if (discoverySettingChanged) {
+    log("Host config discovery is explicit and does not write to or execute commands from external host files.");
+  }
+  return 0;
+}
+
+export async function main(argv = process.argv.slice(2), log = console.log, error = console.error) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printHelp(log);
+    return 0;
+  }
+
+  if (command === "install") {
+    error("The custom downloader has been retired.");
+    error("Use `pi install npm:@fitchmultz/pi-mcp-adapter` instead, then optionally run `fitch-mcp-adapter init`.");
+    return 1;
+  }
+
+  if (command === "init") {
+    return runInit(rest, log);
+  }
+
+  if (command === "migrate") {
+    const { migrateLegacyState } = await import("./dist/legacy-migration.js");
+    const dryRun = rest.includes("--dry-run");
+    const result = migrateLegacyState({ dryRun });
+    for (const file of result.files) log(`${file.status}: ${file.source} -> ${file.destination}`);
+    for (const credential of result.credentials) log(`OAuth ${credential.server}: ${credential.status}`);
+    log(dryRun
+      ? "Dry run: no files changed and no credential store accessed."
+      : "Migration complete. Existing destinations and all source files/credentials were left intact. Restart Pi to use the independent adapter.");
+    return 0;
+  }
+
+  error(`Unknown command: ${command}`);
+  printHelp(log);
+  return 1;
+}
+
+const resolvedEntrypoint = process.argv[1] ? fs.realpathSync(process.argv[1]) : undefined;
+const isEntrypoint = resolvedEntrypoint && import.meta.url === pathToFileURL(resolvedEntrypoint).href;
+
+if (isEntrypoint) {
+  main().then((code) => {
+    process.exitCode = code;
+  }).catch((err) => {
+    console.error(`\nHelper failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  });
+}