@pi-unipi/mcp 0.1.0

package/src/bridge/registry.ts

@@ -0,0 +1,281 @@
+/**
+ * @pi-unipi/mcp — Server registry
+ *
+ * Manages MCP server lifecycle: start, stop, restart, status tracking.
+ * Coordinates McpClient instances and tool registration with pi.
+ */
+
+import { UNIPI_EVENTS, MCP_DEFAULTS } from "@pi-unipi/core";
+import type {
+  ResolvedServer,
+  ServerState,
+  ServerStatus,
+  McpTool,
+  McpRegistryEntry,
+} from "../types.js";
+import { McpClient } from "./client.js";
+import { translateMcpTool, type PiExternalTool } from "./translator.js";
+
+/** Callback for emitting events */
+export type EventEmitFn = (
+  event: string,
+  payload: Record<string, unknown>,
+) => void;
+
+/** Callback for registering a tool with pi */
+export type RegisterToolFn = (tool: PiExternalTool) => void;
+
+/** Callback for unregistering a tool with pi */
+export type UnregisterToolFn = (toolName: string) => void;
+
+/** Options for ServerRegistry */
+export interface ServerRegistryOptions {
+  /** Function to emit events via pi.events */
+  emitEvent: EventEmitFn;
+  /** Function to register a tool with pi */
+  registerTool: RegisterToolFn;
+  /** Function to unregister a tool from pi */
+  unregisterTool: UnregisterToolFn;
+  /** Per-server startup timeout in ms */
+  timeoutMs?: number;
+}
+
+/**
+ * Server registry — tracks all MCP server connections and their tools.
+ */
+export class ServerRegistry {
+  private entries = new Map<string, McpRegistryEntry>();
+  private readonly emitEvent: EventEmitFn;
+  private readonly registerTool: RegisterToolFn;
+  private readonly unregisterTool: UnregisterToolFn;
+  private readonly timeoutMs: number;
+
+  constructor(options: ServerRegistryOptions) {
+    this.emitEvent = options.emitEvent;
+    this.registerTool = options.registerTool;
+    this.unregisterTool = options.unregisterTool;
+    this.timeoutMs = options.timeoutMs ?? MCP_DEFAULTS.STARTUP_TIMEOUT_MS;
+  }
+
+  /**
+   * Start an MCP server: spawn process, initialize, discover tools, register.
+   */
+  async startServer(resolved: ResolvedServer): Promise<void> {
+    const { name, def } = resolved;
+
+    // Check max servers limit
+    if (this.entries.size >= MCP_DEFAULTS.MAX_SERVERS) {
+      throw new Error(
+        `Maximum number of MCP servers (${MCP_DEFAULTS.MAX_SERVERS}) reached. ` +
+          `Stop a server before starting a new one.`,
+      );
+    }
+
+    // Stop existing server with same name if running
+    if (this.entries.has(name)) {
+      await this.stopServer(name);
+    }
+
+    const state: ServerState = {
+      name,
+      status: "starting",
+      toolCount: 0,
+      startedAt: new Date().toISOString(),
+    };
+
+    const entry: McpRegistryEntry = {
+      name,
+      resolved,
+      state,
+      client: null,
+      toolNames: [],
+    };
+
+    this.entries.set(name, entry);
+
+    try {
+      // Create and connect client
+      const client = new McpClient({ timeoutMs: this.timeoutMs });
+      await client.connect(def.command, def.args ?? [], def.env);
+
+      entry.client = client;
+
+      // Discover tools
+      const mcpTools = await client.listTools();
+
+      // Translate and register tools
+      const toolNames: string[] = [];
+      for (const mcpTool of mcpTools) {
+        const piTool = translateMcpTool(mcpTool, name, client);
+        this.registerTool(piTool);
+        toolNames.push(piTool.name);
+      }
+
+      // Update state
+      entry.state = {
+        ...state,
+        status: "running",
+        pid: client.pid,
+        toolCount: toolNames.length,
+      };
+      entry.toolNames = toolNames;
+
+      // Emit events
+      this.emitEvent(UNIPI_EVENTS.MCP_SERVER_STARTED, {
+        name,
+        toolCount: toolNames.length,
+      });
+
+      if (toolNames.length > 0) {
+        this.emitEvent(UNIPI_EVENTS.MCP_TOOLS_REGISTERED, {
+          serverName: name,
+          toolNames,
+        });
+      }
+    } catch (err) {
+      const error =
+        err instanceof Error ? err.message : String(err);
+
+      entry.state = {
+        ...state,
+        status: "error",
+        error,
+      };
+
+      // Clean up client if partially connected
+      if (entry.client) {
+        try {
+          await (entry.client as McpClient).disconnect();
+        } catch {
+          // Ignore cleanup errors
+        }
+        entry.client = null;
+      }
+
+      this.emitEvent(UNIPI_EVENTS.MCP_SERVER_ERROR, {
+        name,
+        error,
+      });
+
+      throw err;
+    }
+  }
+
+  /**
+   * Stop an MCP server: unregister tools, disconnect client.
+   */
+  async stopServer(name: string): Promise<void> {
+    const entry = this.entries.get(name);
+    if (!entry) return;
+
+    // Unregister tools
+    for (const toolName of entry.toolNames) {
+      this.unregisterTool(toolName);
+    }
+
+    if (entry.toolNames.length > 0) {
+      this.emitEvent(UNIPI_EVENTS.MCP_TOOLS_UNREGISTERED, {
+        serverName: name,
+        toolNames: entry.toolNames,
+      });
+    }
+
+    // Disconnect client
+    if (entry.client) {
+      try {
+        await (entry.client as McpClient).disconnect();
+      } catch {
+        // Ignore disconnect errors
+      }
+      entry.client = null;
+    }
+
+    // Update state
+    entry.state = {
+      ...entry.state,
+      status: "stopped",
+      toolCount: 0,
+    };
+    entry.toolNames = [];
+
+    this.emitEvent(UNIPI_EVENTS.MCP_SERVER_STOPPED, { name });
+  }
+
+  /**
+   * Restart an MCP server: stop then start.
+   */
+  async restartServer(name: string): Promise<void> {
+    const entry = this.entries.get(name);
+    if (!entry) {
+      throw new Error(`Server '${name}' not found in registry`);
+    }
+
+    const resolved = entry.resolved;
+    await this.stopServer(name);
+    await this.startServer(resolved);
+  }
+
+  /**
+   * Stop all running servers.
+   */
+  async stopAll(): Promise<void> {
+    const names = Array.from(this.entries.keys());
+    await Promise.allSettled(names.map((name) => this.stopServer(name)));
+  }
+
+  /**
+   * Get all registered server states.
+   */
+  getAll(): ServerState[] {
+    return Array.from(this.entries.values()).map((e) => e.state);
+  }
+
+  /**
+   * Get states of running servers.
+   */
+  getActive(): ServerState[] {
+    return this.getAll().filter((s) => s.status === "running");
+  }
+
+  /**
+   * Get states of servers in error state.
+   */
+  getFailed(): ServerState[] {
+    return this.getAll().filter((s) => s.status === "error");
+  }
+
+  /**
+   * Get total number of tools across all active servers.
+   */
+  getTotalToolCount(): number {
+    return this.getActive().reduce((sum, s) => sum + s.toolCount, 0);
+  }
+
+  /**
+   * Get the state of a specific server.
+   */
+  getServerState(name: string): ServerState | null {
+    return this.entries.get(name)?.state ?? null;
+  }
+
+  /**
+   * Get the full registry entry for a server.
+   */
+  getEntry(name: string): McpRegistryEntry | null {
+    return this.entries.get(name) ?? null;
+  }
+
+  /**
+   * Check if a server exists in the registry.
+   */
+  hasServer(name: string): boolean {
+    return this.entries.has(name);
+  }
+
+  /**
+   * Get the number of registered servers.
+   */
+  get size(): number {
+    return this.entries.size;
+  }
+}

package/src/bridge/translator.ts

@@ -0,0 +1,100 @@
+/**
+ * @pi-unipi/mcp — Tool translator
+ *
+ * Converts MCP tool schemas to pi-compatible ExternalTool format.
+ * Naming convention: {serverName}__{toolName}
+ */
+
+import { MCP_DEFAULTS } from "@pi-unipi/core";
+import type { McpTool, McpToolResult } from "../types.js";
+import type { McpClient } from "./client.js";
+
+/** Pi-compatible tool parameter schema */
+interface ToolParameters {
+  type: "object";
+  properties: Record<string, unknown>;
+  required?: string[];
+}
+
+/** Pi-compatible external tool */
+export interface PiExternalTool {
+  name: string;
+  description: string;
+  parameters: ToolParameters;
+  execute: (params: Record<string, unknown>) => Promise<string>;
+}
+
+/**
+ * Translate an MCP tool definition to a pi-compatible external tool.
+ *
+ * @param mcpTool - The MCP tool schema from tools/list
+ * @param serverName - Name of the MCP server this tool belongs to
+ * @param client - The connected McpClient for executing calls
+ * @returns A pi-compatible ExternalTool
+ */
+export function translateMcpTool(
+  mcpTool: McpTool,
+  serverName: string,
+  client: McpClient,
+): PiExternalTool {
+  const separator = MCP_DEFAULTS.TOOL_NAME_SEPARATOR;
+  const toolName = `${serverName}${separator}${mcpTool.name}`;
+
+  // Ensure inputSchema is a valid JSON Schema object
+  const inputSchema = mcpTool.inputSchema ?? {};
+  const parameters: ToolParameters = {
+    type: "object",
+    properties:
+      (inputSchema.properties as Record<string, unknown>) ?? {},
+    required: inputSchema.required as string[] | undefined,
+  };
+
+  const description = [
+    mcpTool.description || `MCP tool: ${mcpTool.name}`,
+    `[Server: ${serverName}]`,
+  ].join(" ");
+
+  const execute = async (
+    params: Record<string, unknown>,
+  ): Promise<string> => {
+    try {
+      const result: McpToolResult = await client.callTool(
+        mcpTool.name,
+        params,
+      );
+
+      // Join all text content blocks
+      const textParts: string[] = [];
+      for (const block of result.content) {
+        if (block.type === "text" && block.text) {
+          textParts.push(block.text);
+        } else if (block.type === "image" && block.data) {
+          textParts.push(`[Image: ${block.mimeType ?? "unknown"}]`);
+        } else if (block.type === "resource") {
+          textParts.push(`[Resource: ${block.text ?? block.mimeType ?? "unknown"}]`);
+        }
+      }
+
+      if (result.isError) {
+        const joined = textParts.join("\n") || "Unknown error";
+        throw new Error(`MCP tool error from ${serverName}: ${joined}`);
+      }
+
+      return textParts.join("\n") || "(no output)";
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `MCP tool "${mcpTool.name}" on server "${serverName}" failed: ${message}\n` +
+          `Check server status via /unipi:mcp-settings`,
+      );
+    }
+  };
+
+  return {
+    name: toolName,
+    description,
+    parameters,
+    execute,
+  };
+}

package/src/config/manager.ts

@@ -0,0 +1,267 @@
+/**
+ * @pi-unipi/mcp — Config manager
+ *
+ * Reads, merges, and writes MCP configuration files.
+ * Handles global (~/.unipi/config/mcp/) and project (.unipi/config/mcp/) configs.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import type {
+  McpConfig,
+  McpMetadata,
+  McpAuth,
+  ResolvedServer,
+  ServerSource,
+} from "../types.js";
+import {
+  DEFAULT_MCP_CONFIG,
+  DEFAULT_METADATA,
+  validateMcpConfig,
+} from "./schema.js";
+
+// ── Path helpers ──────────────────────────────────────────────────
+
+/** Expand ~ to home directory */
+function expandHome(p: string): string {
+  if (p.startsWith("~")) {
+    return path.join(os.homedir(), p.slice(1));
+  }
+  return p;
+}
+
+/** Get global config directory path */
+export function getGlobalConfigDir(): string {
+  return expandHome("~/.unipi/config/mcp");
+}
+
+/** Get project config directory path */
+export function getProjectConfigDir(cwd: string): string {
+  return path.join(cwd, ".unipi", "config", "mcp");
+}
+
+/** Ensure directory exists */
+function ensureDir(dir: string): void {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+// ── File I/O helpers ──────────────────────────────────────────────
+
+/**
+ * Read and parse a JSON file. Returns null if file doesn't exist.
+ * Throws on parse errors (corrupt JSON).
+ */
+function readJsonFile<T>(filePath: string): T | null {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content) as T;
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return null;
+    }
+    throw new Error(`Failed to read ${filePath}: ${(err as Error).message}`);
+  }
+}
+
+/**
+ * Write JSON to file with optional chmod.
+ * Creates parent directories if needed.
+ */
+function writeJsonFile(
+  filePath: string,
+  data: unknown,
+  chmod?: number,
+): void {
+  ensureDir(path.dirname(filePath));
+  const content = JSON.stringify(data, null, 2) + "\n";
+  fs.writeFileSync(filePath, content, "utf-8");
+  if (chmod !== undefined) {
+    try {
+      fs.chmodSync(filePath, chmod);
+    } catch {
+      // chmod may fail on Windows — log but don't fail
+    }
+  }
+}
+
+// ── Config loading ────────────────────────────────────────────────
+
+/**
+ * Load MCP config (mcp-config.json) from a directory.
+ * Returns defaults if file doesn't exist.
+ */
+export function loadMcpConfig(dir: string): McpConfig {
+  const filePath = path.join(dir, "mcp-config.json");
+  const raw = readJsonFile<McpConfig>(filePath);
+  if (!raw) return { ...DEFAULT_MCP_CONFIG };
+
+  const validation = validateMcpConfig(raw);
+  if (!validation.valid) {
+    throw new Error(
+      `Invalid MCP config at ${filePath}:\n${validation.errors.join("\n")}`,
+    );
+  }
+
+  return raw;
+}
+
+/**
+ * Load metadata (config.json) from a directory.
+ * Returns defaults if file doesn't exist.
+ */
+export function loadMetadata(dir: string): McpMetadata {
+  const filePath = path.join(dir, "config.json");
+  const raw = readJsonFile<Partial<McpMetadata>>(filePath);
+  if (!raw) return { ...DEFAULT_METADATA, servers: {}, sync: { ...DEFAULT_METADATA.sync } };
+
+  return {
+    servers: raw.servers ?? {},
+    sync: { ...DEFAULT_METADATA.sync, ...raw.sync },
+  };
+}
+
+/**
+ * Load auth data (auth.json) from a directory.
+ * Returns empty object if file doesn't exist.
+ */
+export function loadAuth(dir: string): McpAuth {
+  const filePath = path.join(dir, "auth.json");
+  return readJsonFile<McpAuth>(filePath) ?? {};
+}
+
+// ── Config saving ─────────────────────────────────────────────────
+
+/**
+ * Save MCP config (mcp-config.json) with chmod 600.
+ */
+export function saveMcpConfig(dir: string, config: McpConfig): void {
+  const filePath = path.join(dir, "mcp-config.json");
+  writeJsonFile(filePath, config, 0o600);
+}
+
+/**
+ * Save metadata (config.json).
+ */
+export function saveMetadata(dir: string, meta: McpMetadata): void {
+  const filePath = path.join(dir, "config.json");
+  writeJsonFile(filePath, meta);
+}
+
+/**
+ * Save auth data (auth.json) with chmod 600.
+ */
+export function saveAuth(dir: string, auth: McpAuth): void {
+  const filePath = path.join(dir, "auth.json");
+  writeJsonFile(filePath, auth, 0o600);
+}
+
+// ── Config merging ────────────────────────────────────────────────
+
+/**
+ * Merge global and project MCP configs into a resolved server list.
+ *
+ * Rules:
+ * 1. Server only in global → loaded normally (source: "global")
+ * 2. Server only in project → loaded normally (source: "project")
+ * 3. Server in both → project wins entirely (source: "project-override")
+ * 4. Server has enabled: false in project metadata → disabled even if defined globally
+ */
+export function resolveServers(
+  globalConfig: McpConfig,
+  globalMeta: McpMetadata,
+  projectConfig: McpConfig | null,
+  projectMeta: McpMetadata | null,
+): ResolvedServer[] {
+  const merged = new Map<
+    string,
+    { def: McpConfig["mcpServers"][string]; source: ServerSource; enabled: boolean }
+  >();
+
+  // Start with all global servers
+  for (const [name, def] of Object.entries(globalConfig.mcpServers)) {
+    const meta = globalMeta.servers[name];
+    merged.set(name, {
+      def,
+      source: "global",
+      enabled: meta?.enabled ?? true,
+    });
+  }
+
+  // Project overrides: merge or add
+  if (projectConfig) {
+    for (const [name, def] of Object.entries(projectConfig.mcpServers)) {
+      const existing = merged.get(name);
+      merged.set(name, {
+        def,
+        source: existing ? "project-override" : "project",
+        enabled: true, // will be refined by metadata below
+      });
+    }
+  }
+
+  // Apply enabled/disabled from project metadata
+  if (projectMeta) {
+    for (const [name, meta] of Object.entries(projectMeta.servers)) {
+      const existing = merged.get(name);
+      if (existing) {
+        existing.enabled = meta.enabled;
+      }
+    }
+  }
+
+  return Array.from(merged.entries()).map(([name, entry]) => ({
+    name,
+    def: entry.def,
+    source: entry.source,
+    enabled: entry.enabled,
+  }));
+}
+
+/**
+ * Merge auth.json env vars into a server definition at spawn time.
+ * Auth env vars are added to the server's env, but don't override
+ * explicitly set values in mcp-config.json.
+ */
+export function mergeEnvWithAuth(
+  serverDef: McpConfig["mcpServers"][string],
+  auth: Record<string, string>,
+): McpConfig["mcpServers"][string] {
+  if (Object.keys(auth).length === 0) return serverDef;
+
+  return {
+    ...serverDef,
+    env: {
+      ...auth,
+      ...(serverDef.env ?? {}),
+    },
+  };
+}
+
+/**
+ * Load both global and project configs and resolve servers.
+ * Convenience wrapper around the individual load + resolve functions.
+ */
+export function loadAndResolve(
+  cwd: string,
+): { servers: ResolvedServer[]; globalDir: string; projectDir: string } {
+  const globalDir = getGlobalConfigDir();
+  const projectDir = getProjectConfigDir(cwd);
+
+  const globalConfig = loadMcpConfig(globalDir);
+  const globalMeta = loadMetadata(globalDir);
+
+  // Project config is optional
+  const projectConfigExists =
+    fs.existsSync(path.join(projectDir, "mcp-config.json")) ||
+    fs.existsSync(path.join(projectDir, "config.json"));
+
+  const projectConfig = projectConfigExists ? loadMcpConfig(projectDir) : null;
+  const projectMeta = projectConfigExists ? loadMetadata(projectDir) : null;
+
+  const servers = resolveServers(globalConfig, globalMeta, projectConfig, projectMeta);
+
+  return { servers, globalDir, projectDir };
+}