@eovidiu/pi-extensions 0.1.0

package/extensions/mcp-bridge/mcp-client.ts

@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { getDefaultEnvironment, StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { McpServerConfig, PiMcpConfig } from "./types.js";
+import { logDebug } from "./logger.js";
+
+export interface McpToolBinding {
+  piToolName: string;
+  serverName: string;
+  mcpToolName: string;
+  description: string;
+  inputSchema: unknown;
+}
+
+interface ConnectedServer {
+  name: string;
+  config: McpServerConfig;
+  client: Client;
+  transport: StdioClientTransport;
+  tools: McpToolBinding[];
+}
+
+export class McpBridgeRuntime {
+  private servers = new Map<string, ConnectedServer>();
+  private bindings = new Map<string, McpToolBinding>();
+
+  getToolBindings(): McpToolBinding[] {
+    return [...this.bindings.values()].sort((a, b) => a.piToolName.localeCompare(b.piToolName));
+  }
+
+  getConnectedServerNames(): string[] {
+    return [...this.servers.keys()].sort();
+  }
+
+  getConnectionSummary(): string {
+    const connected = this.getConnectedServerNames();
+    const tools = this.getToolBindings();
+    return [
+      `Connected servers: ${connected.length ? connected.join(", ") : "none"}`,
+      `Registered MCP tool bindings: ${tools.length}`,
+      ...tools.map((tool) => `- ${tool.piToolName} -> ${tool.serverName}/${tool.mcpToolName}`),
+    ].join("\n");
+  }
+
+  async startEnabled(config: PiMcpConfig): Promise<McpToolBinding[]> {
+    const enabled = Object.entries(config.servers).filter(([serverName, server]) => server.enabled && isServerAllowed(serverName, config));
+    for (const [serverName, server] of enabled) {
+      if (this.servers.has(serverName)) continue;
+      try {
+        await this.startServer(serverName, server);
+      } catch (error) {
+        await logDebug("Failed to start MCP server", { serverName, error: errorMessage(error) });
+      }
+    }
+    return this.getToolBindings();
+  }
+
+  async restartServer(serverName: string, config: PiMcpConfig): Promise<McpToolBinding[]> {
+    await this.stopServer(serverName);
+    const server = config.servers[serverName];
+    if (!server) throw new Error(`Unknown MCP server: ${serverName}`);
+    if (!server.enabled) throw new Error(`MCP server is disabled: ${serverName}`);
+    if (!isServerAllowed(serverName, config)) throw new Error(`MCP server is blocked by allow/deny filters: ${serverName}`);
+    await this.startServer(serverName, server);
+    return this.getToolBindings();
+  }
+
+  async restartEnabled(config: PiMcpConfig): Promise<McpToolBinding[]> {
+    await this.stopAll();
+    return this.startEnabled(config);
+  }
+
+  async stopNotEnabled(config: PiMcpConfig): Promise<string[]> {
+    const removed: string[] = [];
+    for (const serverName of this.getConnectedServerNames()) {
+      if (!config.servers[serverName]?.enabled) removed.push(...await this.stopServer(serverName));
+    }
+    return removed;
+  }
+
+  async stopServer(serverName: string): Promise<string[]> {
+    const existing = this.servers.get(serverName);
+    if (!existing) return [];
+    this.servers.delete(serverName);
+    const removedTools = existing.tools.map((tool) => tool.piToolName);
+    for (const toolName of removedTools) this.bindings.delete(toolName);
+    try {
+      await existing.transport.close();
+    } catch (error) {
+      await logDebug("Error while closing MCP transport", { serverName, error: errorMessage(error) });
+    }
+    await logDebug("Stopped MCP server", { serverName, removedTools });
+    return removedTools;
+  }
+
+  async stopAll(): Promise<string[]> {
+    const names = this.getConnectedServerNames();
+    const removed: string[] = [];
+    for (const name of names) removed.push(...await this.stopServer(name));
+    return removed;
+  }
+
+  async callTool(piToolName: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
+    const binding = this.bindings.get(piToolName);
+    if (!binding) throw new Error(`MCP tool is not active: ${piToolName}`);
+    const server = this.servers.get(binding.serverName);
+    if (!server) throw new Error(`MCP server is not connected: ${binding.serverName}`);
+    return server.client.callTool(
+      { name: binding.mcpToolName, arguments: args },
+      undefined,
+      signal ? { signal } : undefined,
+    );
+  }
+
+  private async startServer(serverName: string, config: McpServerConfig): Promise<void> {
+    const transport = new StdioClientTransport({
+      command: config.command,
+      args: config.args ?? [],
+      env: { ...getDefaultEnvironment(), ...(config.env ?? {}) },
+      stderr: "pipe",
+    });
+
+    transport.stderr?.on("data", (chunk: Buffer | string) => {
+      void logDebug("MCP server stderr", { serverName, stderr: String(chunk).slice(0, 4000) });
+    });
+
+    const client = new Client({ name: "pi-mcp-bridge", version: "0.1.0" }, { capabilities: {} });
+    await client.connect(transport);
+    const listed = await client.listTools();
+    const tools = listed.tools.map((tool) => ({
+      piToolName: this.makePiToolName(serverName, tool.name),
+      serverName,
+      mcpToolName: tool.name,
+      description: tool.description ?? `MCP tool ${tool.name} from ${serverName}`,
+      inputSchema: tool.inputSchema,
+    }));
+
+    const connected: ConnectedServer = { name: serverName, config, client, transport, tools };
+    this.servers.set(serverName, connected);
+    for (const tool of tools) this.bindings.set(tool.piToolName, tool);
+    await logDebug("Started MCP server", { serverName, toolCount: tools.length, tools: tools.map((tool) => tool.piToolName) });
+  }
+
+  private makePiToolName(serverName: string, mcpToolName: string): string {
+    const base = normalizeToolName(`mcp_${serverName}_${mcpToolName}`);
+    if (!this.bindings.has(base)) return base;
+    return `${base}_${shortHash(`${serverName}/${mcpToolName}`)}`;
+  }
+}
+
+function normalizeToolName(value: string): string {
+  return value.replace(/[^A-Za-z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "") || "mcp_tool";
+}
+
+function shortHash(value: string): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, 6);
+}
+
+function isServerAllowed(serverName: string, config: PiMcpConfig): boolean {
+  if (config.allowServers?.length && !config.allowServers.some((pattern) => matchesPattern(serverName, pattern))) return false;
+  if (config.denyServers?.some((pattern) => matchesPattern(serverName, pattern))) return false;
+  return true;
+}
+
+function matchesPattern(value: string, pattern: string): boolean {
+  if (pattern === "*" || pattern === value) return true;
+  if (!pattern.includes("*")) return false;
+  const escaped = pattern.split("*").map(escapeRegExp).join(".*");
+  return new RegExp(`^${escaped}$`).test(value);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/extensions/mcp-bridge/schema-conversion.ts

@@ -0,0 +1,84 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type TSchema } from "typebox";
+
+interface JsonSchema {
+  type?: string | string[];
+  description?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  items?: JsonSchema;
+  enum?: unknown[];
+  additionalProperties?: unknown;
+}
+
+export function convertMcpInputSchema(schema: unknown): TSchema {
+  if (!isObject(schema)) throw new Error("inputSchema must be an object");
+  const typed = schema as JsonSchema;
+  if (schemaType(typed) !== "object") throw new Error("Only object top-level input schemas are supported");
+  return convertObjectSchema(typed, "root");
+}
+
+function convertSchema(schema: JsonSchema, path: string): TSchema {
+  if (Array.isArray(schema.type)) throw new Error(`Unsupported union type at ${path}`);
+
+  if (schema.enum) {
+    if (schema.enum.length === 0) throw new Error(`Unsupported empty enum at ${path}`);
+    if (schema.enum.every((value): value is string => typeof value === "string")) {
+      return withDescription(StringEnum(schema.enum as [string, ...string[]]), schema.description);
+    }
+    throw new Error(`Unsupported non-string enum at ${path}`);
+  }
+
+  switch (schemaType(schema)) {
+    case "string":
+      return withDescription(Type.String(), schema.description);
+    case "number":
+      return withDescription(Type.Number(), schema.description);
+    case "integer":
+      return withDescription(Type.Integer(), schema.description);
+    case "boolean":
+      return withDescription(Type.Boolean(), schema.description);
+    case "array": {
+      const items = schema.items ? convertSchema(schema.items, `${path}[]`) : Type.Any();
+      return withDescription(Type.Array(items), schema.description);
+    }
+    case "object":
+      return convertObjectSchema(schema, path);
+    default:
+      throw new Error(`Unsupported or missing type at ${path}`);
+  }
+}
+
+function convertObjectSchema(schema: JsonSchema, path: string): TSchema {
+  if (hasComplexCombinators(schema)) throw new Error(`Unsupported schema combinator at ${path}`);
+  const required = new Set(schema.required ?? []);
+  const props: Record<string, TSchema> = {};
+  for (const [key, value] of Object.entries(schema.properties ?? {})) {
+    if (hasComplexCombinators(value)) throw new Error(`Unsupported schema combinator at ${path}.${key}`);
+    const converted = convertSchema(value, `${path}.${key}`);
+    props[key] = required.has(key) ? converted : Type.Optional(converted);
+  }
+  return withDescription(Type.Object(props), schema.description);
+}
+
+function schemaType(schema: JsonSchema): string | undefined {
+  if (Array.isArray(schema.type)) return undefined;
+  if (schema.type) return schema.type;
+  if (schema.properties) return "object";
+  if (schema.items) return "array";
+  return undefined;
+}
+
+function hasComplexCombinators(schema: unknown): boolean {
+  if (!isObject(schema)) return false;
+  return "oneOf" in schema || "anyOf" in schema || "allOf" in schema || "$ref" in schema;
+}
+
+function withDescription<T extends TSchema>(schema: T, description: string | undefined): T {
+  if (description) (schema as unknown as { description?: string }).description = description;
+  return schema;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}

package/extensions/mcp-bridge/tool-registration.ts

@@ -0,0 +1,114 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { McpBridgeRuntime, McpToolBinding } from "./mcp-client.js";
+import { convertMcpInputSchema } from "./schema-conversion.js";
+import { logDebug } from "./logger.js";
+
+export class McpToolRegistrar {
+  private registered = new Set<string>();
+  private active = new Set<string>();
+
+  constructor(private readonly pi: ExtensionAPI, private readonly runtime: McpBridgeRuntime, private maxOutputChars = 20_000) {}
+
+  setMaxOutputChars(maxOutputChars: number | undefined): void {
+    this.maxOutputChars = maxOutputChars && maxOutputChars > 0 ? maxOutputChars : 20_000;
+  }
+
+  async registerBindings(bindings: McpToolBinding[]): Promise<string[]> {
+    const activated: string[] = [];
+    for (const binding of bindings) {
+      if (!this.registered.has(binding.piToolName)) {
+        try {
+          this.registerBinding(binding);
+          this.registered.add(binding.piToolName);
+        } catch (error) {
+          await logDebug("Skipped MCP tool with unsupported schema", {
+            piToolName: binding.piToolName,
+            serverName: binding.serverName,
+            mcpToolName: binding.mcpToolName,
+            error: errorMessage(error),
+          });
+          continue;
+        }
+      }
+      this.active.add(binding.piToolName);
+      activated.push(binding.piToolName);
+    }
+    this.applyActiveTools();
+    return activated;
+  }
+
+  deactivateTools(toolNames: string[]): void {
+    for (const toolName of toolNames) this.active.delete(toolName);
+    this.applyActiveTools();
+  }
+
+  deactivateAll(): void {
+    this.active.clear();
+    this.applyActiveTools();
+  }
+
+  private registerBinding(binding: McpToolBinding): void {
+    const parameters = convertMcpInputSchema(binding.inputSchema);
+    this.pi.registerTool({
+      name: binding.piToolName,
+      label: `MCP ${binding.mcpToolName}`,
+      description: `${binding.description}\n\nMCP server: ${binding.serverName}; MCP tool: ${binding.mcpToolName}`,
+      promptSnippet: `Call MCP tool ${binding.mcpToolName} from server ${binding.serverName}`,
+      promptGuidelines: [`Use ${binding.piToolName} only when the user asks for capability provided by MCP server ${binding.serverName}.`],
+      parameters,
+      execute: async (_toolCallId, params, signal) => {
+        const result = await this.runtime.callTool(binding.piToolName, params as Record<string, unknown>, signal);
+        return {
+          content: [{ type: "text", text: truncateText(formatMcpResult(result), this.maxOutputChars) }],
+          details: { serverName: binding.serverName, mcpToolName: binding.mcpToolName, result },
+        };
+      },
+    });
+  }
+
+  private applyActiveTools(): void {
+    const active = new Set(this.pi.getActiveTools());
+    for (const registered of this.registered) active.delete(registered);
+    for (const toolName of this.active) active.add(toolName);
+    this.pi.setActiveTools([...active]);
+  }
+}
+
+function formatMcpResult(result: unknown): string {
+  if (isObject(result) && Array.isArray(result.content)) {
+    const chunks = result.content.map(formatMcpContent).filter(Boolean);
+    if (chunks.length) return chunks.join("\n\n");
+  }
+  if (isObject(result) && "toolResult" in result) return stringify(result.toolResult);
+  return stringify(result);
+}
+
+function formatMcpContent(content: unknown): string {
+  if (!isObject(content)) return stringify(content);
+  if (content.type === "text" && typeof content.text === "string") return content.text;
+  if (content.type === "image") return `[MCP image content: ${typeof content.mimeType === "string" ? content.mimeType : "unknown mime type"}]`;
+  if (content.type === "audio") return `[MCP audio content: ${typeof content.mimeType === "string" ? content.mimeType : "unknown mime type"}]`;
+  if (content.type === "resource" && isObject(content.resource)) {
+    if (typeof content.resource.text === "string") return content.resource.text;
+    if (typeof content.resource.uri === "string") return `[MCP resource: ${content.resource.uri}]`;
+  }
+  return stringify(content);
+}
+
+export function truncateText(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const omitted = text.length - maxChars;
+  return `${text.slice(0, maxChars)}\n\n[Truncated ${omitted} characters from MCP tool output]`;
+}
+
+function stringify(value: unknown): string {
+  return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/extensions/mcp-bridge/types.ts

@@ -0,0 +1,52 @@
+export const MANAGED_BY = "pi-mcp-bridge";
+
+export type McpSource = "claude-desktop" | "claude-code" | "codex" | "manual" | string;
+
+export interface McpServerConfig {
+  enabled: boolean;
+  managedBy?: string;
+  source?: McpSource;
+  sourceName?: string;
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+export interface PiMcpConfig {
+  version: 1;
+  autoStart: boolean;
+  servers: Record<string, McpServerConfig>;
+  allowServers?: string[];
+  denyServers?: string[];
+  maxOutputChars?: number;
+}
+
+export interface DiscoveredMcpServer extends McpServerConfig {
+  managedBy: typeof MANAGED_BY;
+  source: McpSource;
+  sourceName: string;
+  configPath: string;
+}
+
+export interface DiscoveryEvent {
+  path: string;
+  source: McpSource;
+  status: "missing" | "found" | "parsed" | "contains-mcp" | "unsupported" | "parse-error";
+  message?: string;
+}
+
+export interface DiscoveryResult {
+  servers: Record<string, DiscoveredMcpServer>;
+  events: DiscoveryEvent[];
+}
+
+export interface SyncResult {
+  configPath: string;
+  discoveredCount: number;
+  added: string[];
+  updated: string[];
+  removed: string[];
+  preservedManual: string[];
+  enabled: string[];
+  disabled: string[];
+}

package/fixtures/claude-code/settings.json

@@ -0,0 +1,15 @@
+{
+  "projects": {
+    "/tmp/example": {
+      "mcpServers": {
+        "github": {
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-github"],
+          "env": {
+            "GITHUB_TOKEN": "$GITHUB_TOKEN"
+          }
+        }
+      }
+    }
+  }
+}

package/fixtures/claude-desktop/claude_desktop_config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+      "env": {
+        "EXAMPLE_TOKEN": "redacted-in-logs"
+      }
+    }
+  }
+}

package/fixtures/codex/config.toml

@@ -0,0 +1,6 @@
+[mcp_servers.playwright]
+command = "npx"
+args = ["-y", "@playwright/mcp"]
+
+[mcp_servers.playwright.env]
+BROWSER = "chromium"

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@eovidiu/pi-extensions",
+  "version": "0.1.0",
+  "description": "Personal Pi extensions, starting with an opt-in MCP sync bridge.",
+  "type": "module",
+  "homepage": "https://github.com/eovidiu/pi-extensions#readme",
+  "bugs": {
+    "url": "https://github.com/eovidiu/pi-extensions/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eovidiu/pi-extensions.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "mcp"
+  ],
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "examples",
+    "fixtures",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/mcp-bridge"
+    ]
+  },
+  "dependencies": {
+    "@iarna/toml": "2.2.5",
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}