pi-mcp-adapter 1.5.0 → 2.0.0

package/lifecycle.ts

@@ -7,8 +7,12 @@ export type ReconnectCallback = (serverName: string) => void;
 export class McpLifecycleManager {
   private manager: McpServerManager;
   private keepAliveServers = new Map<string, ServerDefinition>();
+  private allServers = new Map<string, ServerDefinition>();
+  private serverSettings = new Map<string, { idleTimeout?: number }>();
+  private globalIdleTimeout: number = 10 * 60 * 1000;
   private healthCheckInterval?: NodeJS.Timeout;
   private onReconnect?: ReconnectCallback;
+  private onIdleShutdown?: (serverName: string) => void;
   
   constructor(manager: McpServerManager) {
     this.manager = manager;
@@ -25,6 +29,21 @@ export class McpLifecycleManager {
   markKeepAlive(name: string, definition: ServerDefinition): void {
     this.keepAliveServers.set(name, definition);
   }
+
+  registerServer(name: string, definition: ServerDefinition, settings?: { idleTimeout?: number }): void {
+    this.allServers.set(name, definition);
+    if (settings?.idleTimeout !== undefined) {
+      this.serverSettings.set(name, settings);
+    }
+  }
+
+  setGlobalIdleTimeout(minutes: number): void {
+    this.globalIdleTimeout = minutes * 60 * 1000;
+  }
+
+  setIdleShutdownCallback(callback: (serverName: string) => void): void {
+    this.onIdleShutdown = callback;
+  }
   
   startHealthChecks(intervalMs = 30000): void {
     this.healthCheckInterval = setInterval(() => {
@@ -48,6 +67,21 @@ export class McpLifecycleManager {
         }
       }
     }
+
+    for (const [name] of this.allServers) {
+      if (this.keepAliveServers.has(name)) continue;
+      const timeout = this.getIdleTimeout(name);
+      if (timeout > 0 && this.manager.isIdle(name, timeout)) {
+        await this.manager.close(name);
+        this.onIdleShutdown?.(name);
+      }
+    }
+  }
+
+  private getIdleTimeout(name: string): number {
+    const perServer = this.serverSettings.get(name)?.idleTimeout;
+    if (perServer !== undefined) return perServer * 60 * 1000;
+    return this.globalIdleTimeout;
   }
   
   async gracefulShutdown(): Promise<void> {

package/metadata-cache.ts

@@ -0,0 +1,175 @@
+// metadata-cache.ts - Persistent MCP metadata cache
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import type { McpTool, McpResource, ServerEntry, ToolMetadata } from "./types.js";
+import { formatToolName } from "./types.js";
+import { resourceNameToToolName } from "./resource-tools.js";
+
+const CACHE_VERSION = 1;
+const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const CACHE_PATH = join(homedir(), ".pi", "agent", "mcp-cache.json");
+
+export interface CachedTool {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+}
+
+export interface CachedResource {
+  uri: string;
+  name: string;
+  description?: string;
+}
+
+export interface ServerCacheEntry {
+  configHash: string;
+  tools: CachedTool[];
+  resources: CachedResource[];
+  cachedAt: number;
+}
+
+export interface MetadataCache {
+  version: number;
+  servers: Record<string, ServerCacheEntry>;
+}
+
+export function getMetadataCachePath(): string {
+  return CACHE_PATH;
+}
+
+export function loadMetadataCache(): MetadataCache | null {
+  if (!existsSync(CACHE_PATH)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(CACHE_PATH, "utf-8"));
+    if (!raw || typeof raw !== "object") return null;
+    if (raw.version !== CACHE_VERSION) return null;
+    if (!raw.servers || typeof raw.servers !== "object") return null;
+    return raw as MetadataCache;
+  } catch {
+    return null;
+  }
+}
+
+export function saveMetadataCache(cache: MetadataCache): void {
+  const dir = dirname(CACHE_PATH);
+  mkdirSync(dir, { recursive: true });
+
+  let merged: MetadataCache = { version: CACHE_VERSION, servers: {} };
+  try {
+    if (existsSync(CACHE_PATH)) {
+      const existing = JSON.parse(readFileSync(CACHE_PATH, "utf-8")) as MetadataCache;
+      if (existing && existing.version === CACHE_VERSION && existing.servers) {
+        merged.servers = { ...existing.servers };
+      }
+    }
+  } catch {
+    // Ignore parse errors and proceed with empty cache
+  }
+
+  merged.version = CACHE_VERSION;
+  merged.servers = { ...merged.servers, ...cache.servers };
+
+  const tmpPath = `${CACHE_PATH}.${process.pid}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
+  renameSync(tmpPath, CACHE_PATH);
+}
+
+export function computeServerHash(definition: ServerEntry): string {
+  // Hash only fields that affect server identity and tool/resource output.
+  // Exclude lifecycle, idleTimeout, debug — those are runtime behavior settings
+  // that don't change which tools a server exposes.
+  const identity: Record<string, unknown> = {
+    command: definition.command,
+    args: definition.args,
+    env: definition.env,
+    cwd: definition.cwd,
+    url: definition.url,
+    headers: definition.headers,
+    auth: definition.auth,
+    bearerToken: definition.bearerToken,
+    bearerTokenEnv: definition.bearerTokenEnv,
+    exposeResources: definition.exposeResources,
+  };
+  const normalized = stableStringify(identity);
+  return createHash("sha256").update(normalized).digest("hex");
+}
+
+export function isServerCacheValid(
+  entry: ServerCacheEntry,
+  definition: ServerEntry,
+  maxAgeMs: number = CACHE_MAX_AGE_MS
+): boolean {
+  if (!entry || entry.configHash !== computeServerHash(definition)) return false;
+  if (!entry.cachedAt || typeof entry.cachedAt !== "number") return false;
+  if (maxAgeMs > 0 && Date.now() - entry.cachedAt > maxAgeMs) return false;
+  return true;
+}
+
+export function reconstructToolMetadata(
+  serverName: string,
+  entry: ServerCacheEntry,
+  prefix: "server" | "none" | "short",
+  exposeResources?: boolean
+): ToolMetadata[] {
+  const metadata: ToolMetadata[] = [];
+
+  for (const tool of entry.tools ?? []) {
+    if (!tool?.name) continue;
+    metadata.push({
+      name: formatToolName(tool.name, serverName, prefix),
+      originalName: tool.name,
+      description: tool.description ?? "",
+      inputSchema: tool.inputSchema,
+    });
+  }
+
+  if (exposeResources !== false) {
+    for (const resource of entry.resources ?? []) {
+      if (!resource?.name || !resource?.uri) continue;
+      const baseName = `get_${resourceNameToToolName(resource.name)}`;
+      metadata.push({
+        name: formatToolName(baseName, serverName, prefix),
+        originalName: baseName,
+        description: resource.description ?? `Read resource: ${resource.uri}`,
+        resourceUri: resource.uri,
+      });
+    }
+  }
+
+  return metadata;
+}
+
+export function serializeTools(tools: McpTool[]): CachedTool[] {
+  return tools
+    .filter(t => t?.name)
+    .map(t => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    }));
+}
+
+export function serializeResources(resources: McpResource[]): CachedResource[] {
+  return resources
+    .filter(r => r?.name && r?.uri)
+    .map(r => ({
+      uri: r.uri,
+      name: r.name,
+      description: r.description,
+    }));
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || value === undefined || typeof value !== "object") {
+    const serialized = JSON.stringify(value);
+    return serialized === undefined ? "undefined" : serialized;
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(v => stableStringify(v)).join(",")}]`;
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map(k => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}

package/npx-resolver.ts

@@ -0,0 +1,419 @@
+// npx-resolver.ts - Resolve npx/npm exec binaries to avoid npm parent processes
+import { existsSync, readFileSync, realpathSync, readdirSync, statSync, writeFileSync, renameSync, mkdirSync, openSync, readSync, closeSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, extname, resolve, sep } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+
+const CACHE_VERSION = 1;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CACHE_PATH = join(homedir(), ".pi", "agent", "mcp-npx-cache.json");
+
+interface NpxCacheEntry {
+  resolvedBin: string;
+  resolvedAt: number;
+  packageVersion?: string;
+  isJs: boolean;
+}
+
+interface NpxCache {
+  version: number;
+  entries: Record<string, NpxCacheEntry>;
+}
+
+export interface NpxResolution {
+  binPath: string;
+  extraArgs: string[];
+  isJs: boolean;
+}
+
+interface ParsedInvocation {
+  packageSpec: string;
+  binName?: string;
+  extraArgs: string[];
+}
+
+export async function resolveNpxBinary(
+  command: string,
+  args: string[]
+): Promise<NpxResolution | null> {
+  const parsed = command === "npx"
+    ? parseNpxArgs(args)
+    : command === "npm"
+      ? parseNpmExecArgs(args)
+      : null;
+
+  if (!parsed) return null;
+
+  const cacheKey = JSON.stringify([command, ...args]);
+  const cache = loadCache();
+  const cached = cache?.entries?.[cacheKey];
+
+  if (cached && Date.now() - cached.resolvedAt < CACHE_TTL_MS && existsSync(cached.resolvedBin)) {
+    return { binPath: cached.resolvedBin, extraArgs: parsed.extraArgs, isJs: cached.isJs };
+  }
+
+  const resolved = resolveFromNpmCache(parsed.packageSpec, parsed.binName);
+  if (resolved) {
+    saveCacheEntry(cacheKey, resolved);
+    return { binPath: resolved.resolvedBin, extraArgs: parsed.extraArgs, isJs: resolved.isJs };
+  }
+
+  // Slow path: force npx cache population
+  await forceNpxCache(parsed.packageSpec);
+  const resolvedAfterInstall = resolveFromNpmCache(parsed.packageSpec, parsed.binName);
+  if (resolvedAfterInstall) {
+    saveCacheEntry(cacheKey, resolvedAfterInstall);
+    return { binPath: resolvedAfterInstall.resolvedBin, extraArgs: parsed.extraArgs, isJs: resolvedAfterInstall.isJs };
+  }
+
+  return null;
+}
+
+function parseNpxArgs(args: string[]): ParsedInvocation | null {
+  const separatorIndex = args.indexOf("--");
+  const before = separatorIndex >= 0 ? args.slice(0, separatorIndex) : args;
+  const after = separatorIndex >= 0 ? args.slice(separatorIndex + 1) : [];
+
+  const positionals: string[] = [];
+  let packageSpec: string | undefined;
+  let sawPackageFlag = false;
+  let foundFirstPositional = false;
+
+  for (let i = 0; i < before.length; i++) {
+    const arg = before[i];
+    if (foundFirstPositional) {
+      positionals.push(arg);
+      continue;
+    }
+    if (arg === "-y" || arg === "--yes") continue;
+    if (arg === "-p" || arg === "--package") {
+      const value = before[i + 1];
+      if (!value || value.startsWith("-")) return null;
+      if (!packageSpec) packageSpec = value;
+      sawPackageFlag = true;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--package=")) {
+      const value = arg.slice("--package=".length);
+      if (!value) return null;
+      if (!packageSpec) packageSpec = value;
+      sawPackageFlag = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      return null;
+    }
+    positionals.push(arg);
+    foundFirstPositional = true;
+  }
+
+  if (sawPackageFlag) {
+    const binName = positionals[0];
+    if (!packageSpec || !binName) return null;
+    const extraArgs = positionals.slice(1).concat(after);
+    return { packageSpec, binName, extraArgs };
+  }
+
+  const packagePositional = positionals[0];
+  if (!packagePositional) return null;
+  const extraArgs = positionals.slice(1).concat(after);
+  return { packageSpec: packagePositional, extraArgs };
+}
+
+function parseNpmExecArgs(args: string[]): ParsedInvocation | null {
+  if (args[0] !== "exec") return null;
+  const execArgs = args.slice(1);
+  const separatorIndex = execArgs.indexOf("--");
+  if (separatorIndex < 0) return null;
+
+  const before = execArgs.slice(0, separatorIndex);
+  const after = execArgs.slice(separatorIndex + 1);
+
+  let packageSpec: string | undefined;
+  for (let i = 0; i < before.length; i++) {
+    const arg = before[i];
+    if (arg === "-y" || arg === "--yes") continue;
+    if (arg === "--package") {
+      const value = before[i + 1];
+      if (!value || value.startsWith("-")) return null;
+      if (!packageSpec) packageSpec = value;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--package=")) {
+      const value = arg.slice("--package=".length);
+      if (!value) return null;
+      if (!packageSpec) packageSpec = value;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      return null;
+    }
+  }
+
+  const binName = after[0];
+  if (!packageSpec || !binName) return null;
+  const extraArgs = after.slice(1);
+  return { packageSpec, binName, extraArgs };
+}
+
+function resolveFromNpmCache(packageSpec: string, binName?: string): NpxCacheEntry | null {
+  const cacheDir = getNpmCacheDir();
+  if (!cacheDir) return null;
+
+  const packageName = extractPackageName(packageSpec);
+  if (!packageName) return null;
+
+  const packageDir = findCachedPackageDir(cacheDir, packageName);
+  if (!packageDir) return null;
+
+  const packageJsonPath = join(packageDir, "package.json");
+  if (!existsSync(packageJsonPath)) return null;
+
+  let pkg: { bin?: string | Record<string, string>; version?: string } | null = null;
+  try {
+    pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
+      bin?: string | Record<string, string>;
+      version?: string;
+    };
+  } catch {
+    return null;
+  }
+
+  const binField = pkg?.bin;
+  if (!binField) return null;
+
+  const candidates = buildBinCandidates(packageName, binName);
+  let chosenBinName: string | undefined;
+  let binRel: string | undefined;
+
+  if (typeof binField === "string") {
+    chosenBinName = defaultBinName(packageName);
+    binRel = binField;
+  } else {
+    for (const candidate of candidates) {
+      if (binField[candidate]) {
+        chosenBinName = candidate;
+        binRel = binField[candidate];
+        break;
+      }
+    }
+    if (!binRel) {
+      const firstEntry = Object.entries(binField)[0];
+      if (firstEntry) {
+        chosenBinName = firstEntry[0];
+        binRel = firstEntry[1];
+      }
+    }
+  }
+
+  if (!binRel) return null;
+
+  const nodeModulesDir = findNodeModulesDir(packageDir);
+  const binLink = chosenBinName ? join(nodeModulesDir, ".bin", chosenBinName) : null;
+  let resolvedBin = binLink && existsSync(binLink) ? safeRealpath(binLink) : "";
+  if (!resolvedBin) {
+    resolvedBin = resolve(packageDir, binRel);
+    if (!existsSync(resolvedBin)) return null;
+  }
+
+  const isJs = detectJsBinary(resolvedBin);
+  return {
+    resolvedBin,
+    resolvedAt: Date.now(),
+    packageVersion: pkg?.version,
+    isJs,
+  };
+}
+
+const FORCE_CACHE_TIMEOUT_MS = 30_000;
+
+async function forceNpxCache(packageSpec: string): Promise<void> {
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const proc = spawn(
+        "npm",
+        ["exec", "--yes", "--package", packageSpec, "--", "node", "-e", "1"],
+        { stdio: "ignore" }
+      );
+      const timer = setTimeout(() => {
+        proc.kill();
+        reject(new Error("timeout"));
+      }, FORCE_CACHE_TIMEOUT_MS);
+      timer.unref();
+      proc.on("close", () => { clearTimeout(timer); resolve(); });
+      proc.on("error", (err) => { clearTimeout(timer); reject(err); });
+    });
+  } catch {
+    // Ignore failures, resolution will fall back to original command
+  }
+}
+
+function buildBinCandidates(packageName: string, explicitBin?: string): string[] {
+  const candidates: string[] = [];
+  if (explicitBin) candidates.push(explicitBin);
+
+  if (packageName.startsWith("@")) {
+    const namePart = packageName.split("/")[1] ?? "";
+    const scopePart = packageName.split("/")[0]?.replace("@", "") ?? "";
+    if (namePart) candidates.push(namePart);
+    if (scopePart && namePart) candidates.push(`${scopePart}-${namePart}`);
+  } else {
+    candidates.push(packageName);
+  }
+
+  return [...new Set(candidates.filter(Boolean))];
+}
+
+function extractPackageName(spec: string): string | null {
+  const trimmed = spec.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith("@")) {
+    const slashIndex = trimmed.indexOf("/");
+    if (slashIndex < 0) return null;
+    const atIndex = trimmed.lastIndexOf("@");
+    if (atIndex > slashIndex) {
+      return trimmed.slice(0, atIndex);
+    }
+    return trimmed;
+  }
+  const atIndex = trimmed.indexOf("@");
+  return atIndex >= 0 ? trimmed.slice(0, atIndex) : trimmed;
+}
+
+function defaultBinName(packageName: string): string {
+  if (packageName.startsWith("@")) {
+    const parts = packageName.split("/");
+    return parts[1] ?? packageName.replace("@", "").replace("/", "-");
+  }
+  return packageName;
+}
+
+function findCachedPackageDir(cacheDir: string, packageName: string): string | null {
+  const npxDir = join(cacheDir, "_npx");
+  if (!existsSync(npxDir)) return null;
+
+  const packagePathParts = packageName.startsWith("@")
+    ? packageName.split("/")
+    : [packageName];
+
+  const candidates = readdirSync(npxDir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => {
+      const full = join(npxDir, entry.name);
+      const mtime = safeStatMtime(full);
+      return { name: entry.name, mtime };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+
+  for (const entry of candidates) {
+    const pkgDir = join(npxDir, entry.name, "node_modules", ...packagePathParts);
+    if (existsSync(join(pkgDir, "package.json"))) {
+      return pkgDir;
+    }
+  }
+
+  return null;
+}
+
+function findNodeModulesDir(packageDir: string): string {
+  const parts = packageDir.split(sep);
+  const idx = parts.lastIndexOf("node_modules");
+  if (idx >= 0) {
+    return parts.slice(0, idx + 1).join(sep);
+  }
+  return join(packageDir, "..");
+}
+
+function detectJsBinary(binPath: string): boolean {
+  const ext = extname(binPath).toLowerCase();
+  if (ext === ".js" || ext === ".mjs" || ext === ".cjs") return true;
+  try {
+    const fd = openSync(binPath, "r");
+    try {
+      const buf = Buffer.alloc(256);
+      readSync(fd, buf, 0, 256, 0);
+      const firstLine = buf.toString("utf-8").split("\n")[0] ?? "";
+      return firstLine.startsWith("#!") && firstLine.includes("node");
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return false;
+  }
+}
+
+let npmCacheDirCached: string | null | undefined;
+
+function getNpmCacheDir(): string | null {
+  if (npmCacheDirCached !== undefined) return npmCacheDirCached;
+  if (process.env.NPM_CONFIG_CACHE) {
+    npmCacheDirCached = process.env.NPM_CONFIG_CACHE;
+    return npmCacheDirCached;
+  }
+  try {
+    const result = spawnSync("npm", ["config", "get", "cache"], { encoding: "utf-8" });
+    if (result.status === 0) {
+      const path = String(result.stdout).trim();
+      npmCacheDirCached = path || null;
+      return npmCacheDirCached;
+    }
+  } catch {
+    npmCacheDirCached = null;
+    return null;
+  }
+  npmCacheDirCached = null;
+  return null;
+}
+
+function loadCache(): NpxCache | null {
+  if (!existsSync(CACHE_PATH)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(CACHE_PATH, "utf-8"));
+    if (!raw || typeof raw !== "object") return null;
+    if (raw.version !== CACHE_VERSION) return null;
+    if (!raw.entries || typeof raw.entries !== "object") return null;
+    return raw as NpxCache;
+  } catch {
+    return null;
+  }
+}
+
+function saveCacheEntry(key: string, entry: NpxCacheEntry): void {
+  const dir = dirname(CACHE_PATH);
+  mkdirSync(dir, { recursive: true });
+
+  let merged: NpxCache = { version: CACHE_VERSION, entries: {} };
+  try {
+    if (existsSync(CACHE_PATH)) {
+      const existing = JSON.parse(readFileSync(CACHE_PATH, "utf-8")) as NpxCache;
+      if (existing && existing.version === CACHE_VERSION && existing.entries) {
+        merged.entries = { ...existing.entries };
+      }
+    }
+  } catch {
+    // Ignore parse errors
+  }
+
+  merged.entries[key] = entry;
+  const tmpPath = `${CACHE_PATH}.${process.pid}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
+  renameSync(tmpPath, CACHE_PATH);
+}
+
+function safeRealpath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return "";
+  }
+}
+
+function safeStatMtime(path: string): number {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,7 @@
     "url": "https://github.com/nicobailon/pi-mcp-adapter"
   },
   "keywords": [
+    "pi-package",
     "pi",
     "mcp",
     "model-context-protocol",
@@ -23,7 +24,9 @@
     "llm"
   ],
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   },
   "files": [
     "cli.js",
@@ -34,6 +37,8 @@
     "tool-registrar.ts",
     "resource-tools.ts",
     "lifecycle.ts",
+    "metadata-cache.ts",
+    "npx-resolver.ts",
     "oauth-handler.ts",
     "README.md",
     "CHANGELOG.md",