pi-mcp-adapter 1.1.0

package/lifecycle.ts

@@ -0,0 +1,59 @@
+// lifecycle.ts - Connection health checks and reconnection
+import type { ServerDefinition } from "./types.js";
+import type { McpServerManager } from "./server-manager.js";
+
+export type ReconnectCallback = (serverName: string) => void;
+
+export class McpLifecycleManager {
+  private manager: McpServerManager;
+  private keepAliveServers = new Map<string, ServerDefinition>();
+  private healthCheckInterval?: NodeJS.Timeout;
+  private onReconnect?: ReconnectCallback;
+  
+  constructor(manager: McpServerManager) {
+    this.manager = manager;
+  }
+  
+  /**
+   * Set callback to be invoked after a successful auto-reconnect.
+   * Use this to update tool metadata when a server reconnects.
+   */
+  setReconnectCallback(callback: ReconnectCallback): void {
+    this.onReconnect = callback;
+  }
+  
+  markKeepAlive(name: string, definition: ServerDefinition): void {
+    this.keepAliveServers.set(name, definition);
+  }
+  
+  startHealthChecks(intervalMs = 30000): void {
+    this.healthCheckInterval = setInterval(() => {
+      this.checkConnections();
+    }, intervalMs);
+    this.healthCheckInterval.unref();
+  }
+  
+  private async checkConnections(): Promise<void> {
+    for (const [name, definition] of this.keepAliveServers) {
+      const connection = this.manager.getConnection(name);
+      
+      if (!connection || connection.status !== "connected") {
+        try {
+          await this.manager.connect(name, definition);
+          console.log(`MCP: Reconnected to ${name}`);
+          // Notify extension to update metadata
+          this.onReconnect?.(name);
+        } catch (error) {
+          console.error(`MCP: Failed to reconnect to ${name}:`, error);
+        }
+      }
+    }
+  }
+  
+  async gracefulShutdown(): Promise<void> {
+    if (this.healthCheckInterval) {
+      clearInterval(this.healthCheckInterval);
+    }
+    await this.manager.closeAll();
+  }
+}

package/oauth-handler.ts

@@ -0,0 +1,57 @@
+// oauth-handler.ts - OAuth token management for MCP servers
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+
+// Token storage path for a server
+function getTokensPath(serverName: string): string {
+  return join(homedir(), ".pi", "agent", "mcp-oauth", serverName, "tokens.json");
+}
+
+/**
+ * Get stored OAuth tokens for a server (if any).
+ * Returns undefined if no tokens or tokens are expired.
+ * 
+ * Token file location: ~/.pi/agent/mcp-oauth/<server>/tokens.json
+ * 
+ * Expected format:
+ * {
+ *   "access_token": "...",
+ *   "token_type": "bearer",
+ *   "refresh_token": "...",  // optional
+ *   "expires_in": 3600,      // optional, seconds
+ *   "expiresAt": 1234567890  // optional, absolute timestamp ms
+ * }
+ */
+export function getStoredTokens(serverName: string): OAuthTokens | undefined {
+  const tokensPath = getTokensPath(serverName);
+  
+  if (!existsSync(tokensPath)) return undefined;
+  
+  try {
+    const stored = JSON.parse(readFileSync(tokensPath, "utf-8"));
+    
+    // Validate required field
+    if (!stored.access_token || typeof stored.access_token !== "string") {
+      return undefined;
+    }
+    
+    // Check expiration if expiresAt is set
+    if (stored.expiresAt && typeof stored.expiresAt === "number") {
+      if (Date.now() > stored.expiresAt) {
+        // Token expired
+        return undefined;
+      }
+    }
+    
+    return {
+      access_token: stored.access_token,
+      token_type: stored.token_type ?? "bearer",
+      refresh_token: stored.refresh_token,
+      expires_in: stored.expires_in,
+    };
+  } catch {
+    return undefined;
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "pi-mcp-adapter",
+  "version": "1.1.0",
+  "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
+  "type": "module",
+  "license": "MIT",
+  "author": "Nico Bailon",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicobailon/pi-mcp-adapter"
+  },
+  "keywords": [
+    "pi",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "coding-agent",
+    "extension",
+    "claude",
+    "llm"
+  ],
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "files": [
+    "index.ts",
+    "types.ts",
+    "config.ts",
+    "server-manager.ts",
+    "tool-registrar.ts",
+    "resource-tools.ts",
+    "lifecycle.ts",
+    "oauth-handler.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "ARCHITECTURE.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@sinclair/typebox": "^0.32.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "zod": "^3.25.0"
+  }
+}

package/resource-tools.ts

@@ -0,0 +1,45 @@
+// resource-tools.ts - MCP resource tool name collection
+// NOTE: Resources are NOT registered as Pi tools - they're called via the `mcp` proxy.
+
+import { formatToolName, type McpResource } from "./types.js";
+
+interface ResourceCollectionOptions {
+  serverName: string;
+  prefix: "server" | "none" | "short";
+}
+
+/**
+ * Collect tool names for MCP resources.
+ * Does NOT register with Pi - resources are called via the `mcp` proxy.
+ */
+export function collectResourceToolNames(
+  resources: McpResource[],
+  options: ResourceCollectionOptions
+): string[] {
+  const collected: string[] = [];
+  const { serverName, prefix } = options;
+  
+  for (const resource of resources) {
+    const baseName = `get_${resourceNameToToolName(resource.name)}`;
+    const toolName = formatToolName(baseName, serverName, prefix);
+    collected.push(toolName);
+  }
+  
+  return collected;
+}
+
+export function resourceNameToToolName(name: string): string {
+  let result = name
+    .replace(/[^a-zA-Z0-9]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+/, "")  // Remove leading underscores
+    .replace(/_+$/, "")  // Remove trailing underscores
+    .toLowerCase();
+  
+  // Ensure we have a valid name
+  if (!result || /^\d/.test(result)) {
+    result = "resource" + (result ? "_" + result : "");
+  }
+  
+  return result;
+}

package/server-manager.ts

@@ -0,0 +1,242 @@
+// server-manager.ts - MCP connection management (stdio + HTTP)
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import type { McpTool, McpResource, ServerDefinition, Transport } from "./types.js";
+import { getStoredTokens } from "./oauth-handler.js";
+
+interface ServerConnection {
+  client: Client;
+  transport: Transport;
+  definition: ServerDefinition;
+  tools: McpTool[];
+  resources: McpResource[];
+  lastUsedAt: number;
+  status: "connected" | "closed";
+}
+
+export class McpServerManager {
+  private connections = new Map<string, ServerConnection>();
+  private connectPromises = new Map<string, Promise<ServerConnection>>();
+  
+  async connect(name: string, definition: ServerDefinition): Promise<ServerConnection> {
+    // Dedupe concurrent connection attempts
+    if (this.connectPromises.has(name)) {
+      return this.connectPromises.get(name)!;
+    }
+    
+    // Reuse existing connection if healthy
+    const existing = this.connections.get(name);
+    if (existing?.status === "connected") {
+      existing.lastUsedAt = Date.now();
+      return existing;
+    }
+    
+    const promise = this.createConnection(name, definition);
+    this.connectPromises.set(name, promise);
+    
+    try {
+      const connection = await promise;
+      this.connections.set(name, connection);
+      return connection;
+    } finally {
+      this.connectPromises.delete(name);
+    }
+  }
+  
+  private async createConnection(
+    name: string,
+    definition: ServerDefinition
+  ): Promise<ServerConnection> {
+    const client = new Client({ name: `pi-mcp-${name}`, version: "1.0.0" });
+    
+    let transport: Transport;
+    
+    if (definition.command) {
+      // Stdio transport
+      transport = new StdioClientTransport({
+        command: definition.command,
+        args: definition.args ?? [],
+        env: resolveEnv(definition.env),
+        cwd: definition.cwd,
+        stderr: definition.debug ? "inherit" : "ignore",
+      });
+    } else if (definition.url) {
+      // HTTP transport with fallback
+      transport = await this.createHttpTransport(definition, name);
+    } else {
+      throw new Error(`Server ${name} has no command or url`);
+    }
+    
+    try {
+      await client.connect(transport);
+      
+      // Discover tools and resources
+      const [tools, resources] = await Promise.all([
+        this.fetchAllTools(client),
+        this.fetchAllResources(client),
+      ]);
+      
+      return {
+        client,
+        transport,
+        definition,
+        tools,
+        resources,
+        lastUsedAt: Date.now(),
+        status: "connected",
+      };
+    } catch (error) {
+      // Clean up both client and transport on any error
+      await client.close().catch(() => {});
+      await transport.close().catch(() => {});
+      throw error;
+    }
+  }
+  
+  private async createHttpTransport(definition: ServerDefinition, serverName?: string): Promise<Transport> {
+    const url = new URL(definition.url!);
+    const headers = resolveHeaders(definition.headers) ?? {};
+    
+    // Add bearer token if configured
+    if (definition.auth === "bearer") {
+      const token = definition.bearerToken 
+        ?? (definition.bearerTokenEnv ? process.env[definition.bearerTokenEnv] : undefined);
+      if (token) {
+        headers["Authorization"] = `Bearer ${token}`;
+      }
+    }
+    
+    // Handle OAuth auth - use stored tokens
+    if (definition.auth === "oauth") {
+      if (!serverName) {
+        throw new Error("Server name required for OAuth authentication");
+      }
+      const tokens = getStoredTokens(serverName);
+      if (!tokens) {
+        throw new Error(
+          `No OAuth tokens found for "${serverName}". Run /mcp-auth ${serverName} to authenticate.`
+        );
+      }
+      headers["Authorization"] = `Bearer ${tokens.access_token}`;
+    }
+    
+    const requestInit = Object.keys(headers).length > 0 ? { headers } : undefined;
+    
+    // Try StreamableHTTP first (modern MCP servers)
+    const streamableTransport = new StreamableHTTPClientTransport(url, { requestInit });
+    
+    try {
+      // Create a test client to verify the transport works
+      const testClient = new Client({ name: "pi-mcp-probe", version: "1.0.0" });
+      await testClient.connect(streamableTransport);
+      await testClient.close().catch(() => {});
+      // Close probe transport before creating fresh one
+      await streamableTransport.close().catch(() => {});
+      
+      // StreamableHTTP works - create fresh transport for actual use
+      return new StreamableHTTPClientTransport(url, { requestInit });
+    } catch {
+      // StreamableHTTP failed, close and try SSE fallback
+      await streamableTransport.close().catch(() => {});
+      
+      // SSE is the legacy transport
+      return new SSEClientTransport(url, { requestInit });
+    }
+  }
+  
+  private async fetchAllTools(client: Client): Promise<McpTool[]> {
+    const allTools: McpTool[] = [];
+    let cursor: string | undefined;
+    
+    do {
+      const result = await client.listTools(cursor ? { cursor } : undefined);
+      allTools.push(...(result.tools ?? []));
+      cursor = result.nextCursor;
+    } while (cursor);
+    
+    return allTools;
+  }
+  
+  private async fetchAllResources(client: Client): Promise<McpResource[]> {
+    try {
+      const allResources: McpResource[] = [];
+      let cursor: string | undefined;
+      
+      do {
+        const result = await client.listResources(cursor ? { cursor } : undefined);
+        allResources.push(...(result.resources ?? []));
+        cursor = result.nextCursor;
+      } while (cursor);
+      
+      return allResources;
+    } catch {
+      // Server may not support resources
+      return [];
+    }
+  }
+  
+  async close(name: string): Promise<void> {
+    const connection = this.connections.get(name);
+    if (!connection) return;
+    
+    connection.status = "closed";
+    // Close both independently - don't let one failure prevent the other
+    await connection.client.close().catch(() => {});
+    await connection.transport.close().catch(() => {});
+    this.connections.delete(name);
+  }
+  
+  async closeAll(): Promise<void> {
+    const names = [...this.connections.keys()];
+    await Promise.all(names.map(name => this.close(name)));
+  }
+  
+  getConnection(name: string): ServerConnection | undefined {
+    return this.connections.get(name);
+  }
+  
+  getAllConnections(): Map<string, ServerConnection> {
+    return new Map(this.connections);
+  }
+}
+
+/**
+ * Resolve environment variables with interpolation.
+ */
+function resolveEnv(env?: Record<string, string>): Record<string, string> {
+  // Copy process.env, filtering out undefined values
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) {
+      resolved[key] = value;
+    }
+  }
+  
+  if (!env) return resolved;
+  
+  for (const [key, value] of Object.entries(env)) {
+    // Support ${VAR} and $env:VAR interpolation
+    resolved[key] = value
+      .replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "")
+      .replace(/\$env:(\w+)/g, (_, name) => process.env[name] ?? "");
+  }
+  
+  return resolved;
+}
+
+/**
+ * Resolve headers with environment variable interpolation.
+ */
+function resolveHeaders(headers?: Record<string, string>): Record<string, string> | undefined {
+  if (!headers) return undefined;
+  
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    resolved[key] = value
+      .replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "")
+      .replace(/\$env:(\w+)/g, (_, name) => process.env[name] ?? "");
+  }
+  return resolved;
+}

package/tool-registrar.ts

@@ -0,0 +1,77 @@
+// tool-registrar.ts - MCP tool metadata and content transformation
+// NOTE: Tools are NOT registered with Pi - only the unified `mcp` proxy tool is registered.
+// This keeps the LLM context small (1 tool instead of 100s).
+
+import type { McpTool, McpContent, ContentBlock } from "./types.js";
+import { formatToolName } from "./types.js";
+
+interface ToolCollectionOptions {
+  serverName: string;
+  prefix: "server" | "none" | "short";
+}
+
+/**
+ * Collect tool names from MCP server tools.
+ * Does NOT register with Pi - tools are called via the `mcp` proxy.
+ */
+export function collectToolNames(
+  tools: McpTool[],
+  options: ToolCollectionOptions
+): { collected: string[]; failed: string[] } {
+  const collected: string[] = [];
+  const failed: string[] = [];
+  
+  for (const tool of tools) {
+    // Basic validation - tool must have a name
+    if (!tool.name) {
+      failed.push("(unnamed)");
+      continue;
+    }
+    
+    const toolName = formatToolName(tool.name, options.serverName, options.prefix);
+    collected.push(toolName);
+  }
+  
+  return { collected, failed };
+}
+
+/**
+ * Transform MCP content types to Pi content blocks.
+ */
+export function transformMcpContent(content: McpContent[]): ContentBlock[] {
+  return content.map(c => {
+    if (c.type === "text") {
+      return { type: "text" as const, text: c.text ?? "" };
+    }
+    if (c.type === "image") {
+      return {
+        type: "image" as const,
+        data: c.data ?? "",
+        mimeType: c.mimeType ?? "image/png",
+      };
+    }
+    if (c.type === "resource") {
+      const resourceUri = c.resource?.uri ?? "(no URI)";
+      const resourceContent = c.resource?.text ?? (c.resource ? JSON.stringify(c.resource) : "(no content)");
+      return {
+        type: "text" as const,
+        text: `[Resource: ${resourceUri}]\n${resourceContent}`,
+      };
+    }
+    if (c.type === "resource_link") {
+      const linkName = c.name ?? c.uri ?? "unknown";
+      const linkUri = c.uri ?? "(no URI)";
+      return {
+        type: "text" as const,
+        text: `[Resource Link: ${linkName}]\nURI: ${linkUri}`,
+      };
+    }
+    if (c.type === "audio") {
+      return {
+        type: "text" as const,
+        text: `[Audio content: ${c.mimeType ?? "audio/*"}]`,
+      };
+    }
+    return { type: "text" as const, text: JSON.stringify(c) };
+  });
+}

package/types.ts

@@ -0,0 +1,112 @@
+// types.ts - Core type definitions
+import type { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import type { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { TextContent, ImageContent } from "@mariozechner/pi-ai";
+
+// Transport type (stdio + HTTP)
+export type Transport = 
+  | StdioClientTransport 
+  | SSEClientTransport 
+  | StreamableHTTPClientTransport;
+
+// Import sources for config
+export type ImportKind = 
+  | "cursor" 
+  | "claude-code" 
+  | "claude-desktop" 
+  | "codex" 
+  | "windsurf" 
+  | "vscode";
+
+// Tool definition from MCP server
+export interface McpTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: unknown; // JSON Schema
+}
+
+// Resource definition from MCP server
+export interface McpResource {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+// Content types from MCP
+export interface McpContent {
+  type: "text" | "image" | "audio" | "resource" | "resource_link";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  resource?: {
+    uri: string;
+    text?: string;
+    blob?: string;
+  };
+  uri?: string;
+  name?: string;
+  description?: string;
+}
+
+// Pi content block type
+export type ContentBlock = TextContent | ImageContent;
+
+// Server configuration
+export interface ServerEntry {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  // HTTP fields
+  url?: string;
+  headers?: Record<string, string>;
+  auth?: "oauth" | "bearer";
+  bearerToken?: string;
+  bearerTokenEnv?: string;
+  lifecycle?: "keep-alive" | "ephemeral";
+  // Resource handling
+  exposeResources?: boolean;
+  // Debug
+  debug?: boolean;  // Show server stderr (default: false)
+}
+
+// Settings
+export interface McpSettings {
+  toolPrefix?: "server" | "none" | "short";
+}
+
+// Root config
+export interface McpConfig {
+  mcpServers: Record<string, ServerEntry>;
+  imports?: ImportKind[];
+  settings?: McpSettings;
+}
+
+// Alias for clarity
+export type ServerDefinition = ServerEntry;
+
+/**
+ * Format a tool name with server prefix.
+ */
+export function formatToolName(
+  toolName: string,
+  serverName: string,
+  prefix: "server" | "none" | "short"
+): string {
+  switch (prefix) {
+    case "none":
+      return toolName;
+    case "short":
+      let short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
+      // Fallback if server name was just "mcp" or similar
+      if (!short) short = "mcp";
+      return `${short}_${toolName}`;
+    case "server":
+    default:
+      const normalized = serverName.replace(/-/g, "_");
+      return `${normalized}_${toolName}`;
+  }
+}