@pi-unipi/mcp 0.1.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pi-unipi/mcp",
+  "version": "0.1.0",
+  "description": "MCP server management extension for Pi coding agent — browse, add, configure, and use MCP servers",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/mcp"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "mcp",
+    "model-context-protocol",
+    "tools"
+  ],
+  "pi": {
+    "extensions": [
+      "src/index.ts"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "files": [
+    "src/**/*.ts",
+    "data/**/*",
+    "skills/**/*",
+    "README.md"
+  ],
+  "dependencies": {
+    "@pi-unipi/core": "*"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0"
+  }
+}

package/skills/mcp/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: mcp
+description: "MCP server management — discover, connect, and use Model Context Protocol tools"
+---
+
+# MCP Tools
+
+MCP (Model Context Protocol) servers provide external tools that extend pi's capabilities.
+Tools from MCP servers are named `{serverName}__{toolName}` — e.g., `github__search_code`.
+
+## Adding Servers
+
+Use `/unipi:mcp-add` to browse the catalog of 7,800+ MCP servers and add them interactively.
+The split-pane overlay lets you:
+- **Browse**: Search the cached server catalog by name, description, or category
+- **Select**: Pick a server to get a pre-filled config template
+- **Custom**: Press `c` for an empty editor to add unlisted servers manually
+- **Save**: Press Enter or Ctrl+S to validate and save
+
+## Managing Servers
+
+Use `/unipi:mcp-settings` to manage configured servers:
+- **Toggle**: Press Space to enable/disable a server
+- **Delete**: Press `d` then `y` to remove a server
+- **Scope**: Press `g` for global config, `p` for project config
+- **Sync**: Press `s` to refresh the catalog from GitHub
+
+## Quick Status
+
+Use `/unipi:mcp-status` for a text summary of all servers and their status.
+
+## Config Hierarchy
+
+MCP config supports **global defaults** with **project overrides**:
+
+```
+~/.unipi/config/mcp/              ← Global defaults (shared across all projects)
+{project}/.unipi/config/mcp/      ← Project overrides (when present)
+```
+
+**Merge rules:**
+1. Server only in global → used normally
+2. Server only in project → used normally
+3. Server in both → project wins entirely
+4. `enabled: false` in project metadata → disabled even if defined globally
+
+### Config Files
+
+Each level has three files:
+- `mcp-config.json` — Server definitions (standard MCP format, portable)
+- `config.json` — Metadata (enabled/disabled, sync prefs)
+- `auth.json` — Sensitive env vars (optional, chmod 600)
+
+### Example mcp-config.json
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx" }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/pi/projects"]
+    }
+  }
+}
+```
+
+## Using MCP Tools
+
+Once an MCP server is running, its tools are available as pi tools.
+They're named with the pattern `{serverName}__{toolName}`.
+
+For example, if you add the GitHub MCP server, you'll have tools like:
+- `github__search_code`
+- `github__create_issue`
+- `github__list_pull_requests`
+
+You can call these tools directly in conversations.
+
+## Troubleshooting
+
+### Server won't start
+- Check `/unipi:mcp-status` for error details
+- Verify the command exists: `which npx` or `which docker`
+- Check that required env vars are set in the config
+
+### Tools not appearing
+- Ensure the server status shows "running"
+- Check if the server supports the MCP tools protocol
+- Try restarting pi after adding a new server
+
+### Config issues
+- Validate JSON syntax in your config files
+- Check file permissions (mcp-config.json should be readable)
+- Use `/unipi:mcp-settings` to view current configuration
+
+### Catalog sync issues
+- Run `/unipi:mcp-sync` to force a refresh
+- Check network connectivity to GitHub
+- The seed catalog (49 servers) is available offline as fallback

package/src/bridge/client.ts

@@ -0,0 +1,365 @@
+/**
+ * @pi-unipi/mcp — MCP JSON-RPC Client
+ *
+ * Spawns an MCP server as a child process, performs the JSON-RPC initialize
+ * handshake, and provides listTools/callTool/disconnect methods via stdio.
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import type { McpTool, McpToolResult } from "../types.js";
+import { MCP_DEFAULTS } from "@pi-unipi/core";
+
+/** JSON-RPC request */
+interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+/** JSON-RPC response */
+interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: number;
+  result?: unknown;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+/** JSON-RPC notification (no id) */
+interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+/** Pending request handler */
+interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/** Options for McpClient */
+export interface McpClientOptions {
+  /** Per-request timeout in ms (default: MCP_DEFAULTS.STARTUP_TIMEOUT_MS) */
+  timeoutMs?: number;
+  /** Working directory for the spawned process */
+  cwd?: string;
+}
+
+/**
+ * MCP JSON-RPC client over stdio transport.
+ *
+ * Spawns a child process, sends JSON-RPC messages to stdin,
+ * reads responses from stdout, and correlates by request ID.
+ */
+export class McpClient {
+  private process: ChildProcess | null = null;
+  private nextId = 1;
+  private pending = new Map<number, PendingRequest>();
+  private buffer = "";
+  private connected = false;
+  private stderrBuffer = "";
+  private readonly timeoutMs: number;
+  private readonly cwd?: string;
+
+  constructor(options?: McpClientOptions) {
+    this.timeoutMs = options?.timeoutMs ?? MCP_DEFAULTS.STARTUP_TIMEOUT_MS;
+    this.cwd = options?.cwd;
+  }
+
+  /**
+   * Spawn the MCP server process and perform the initialize handshake.
+   */
+  async connect(
+    command: string,
+    args: string[],
+    env?: Record<string, string>,
+  ): Promise<void> {
+    if (this.connected) {
+      throw new Error("McpClient is already connected");
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      try {
+        const mergedEnv = { ...process.env, ...env };
+
+        this.process = spawn(command, args, {
+          stdio: ["pipe", "pipe", "pipe"],
+          env: mergedEnv,
+          cwd: this.cwd,
+        });
+
+        this.process.on("error", (err) => {
+          this.cleanup();
+          reject(new Error(`Failed to spawn MCP server: ${err.message}`));
+        });
+
+        this.process.on("exit", (code, signal) => {
+          if (!this.connected) {
+            this.cleanup();
+            reject(
+              new Error(
+                `MCP server exited during startup: code=${code}, signal=${signal}\nStderr: ${this.stderrBuffer}`,
+              ),
+            );
+            return;
+          }
+          // Unexpected exit after connection
+          this.connected = false;
+          this.rejectAllPending(
+            new Error(
+              `MCP server exited unexpectedly: code=${code}, signal=${signal}`,
+            ),
+          );
+        });
+
+        // Set up stdout reading
+        this.process.stdout!.on("data", (chunk: Buffer) => {
+          this.handleStdoutData(chunk);
+        });
+
+        // Capture stderr for error reporting
+        this.process.stderr!.on("data", (chunk: Buffer) => {
+          this.stderrBuffer += chunk.toString();
+          // Keep stderr buffer manageable
+          if (this.stderrBuffer.length > 10000) {
+            this.stderrBuffer = this.stderrBuffer.slice(-5000);
+          }
+        });
+
+        // Perform initialize handshake
+        this.sendRequest("initialize", {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: {
+            name: "@pi-unipi/mcp",
+            version: "0.1.0",
+          },
+        })
+          .then(() => {
+            // Send initialized notification
+            this.sendNotification("notifications/initialized", {});
+            this.connected = true;
+            resolve();
+          })
+          .catch((err) => {
+            this.cleanup();
+            reject(
+              new Error(
+                `MCP initialize handshake failed: ${(err as Error).message}\nStderr: ${this.stderrBuffer}`,
+              ),
+            );
+          });
+      } catch (err) {
+        this.cleanup();
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Query available tools from the MCP server.
+   */
+  async listTools(): Promise<McpTool[]> {
+    this.ensureConnected();
+    const result = (await this.sendRequest("tools/list", {})) as {
+      tools: McpTool[];
+    };
+    return result.tools ?? [];
+  }
+
+  /**
+   * Execute a tool call on the MCP server.
+   */
+  async callTool(
+    name: string,
+    args: Record<string, unknown>,
+  ): Promise<McpToolResult> {
+    this.ensureConnected();
+    const result = (await this.sendRequest("tools/call", {
+      name,
+      arguments: args,
+    })) as McpToolResult;
+    return result;
+  }
+
+  /**
+   * Gracefully disconnect from the MCP server.
+   */
+  async disconnect(): Promise<void> {
+    if (!this.process) return;
+
+    try {
+      // Send shutdown notification
+      this.sendNotification("shutdown", {});
+    } catch {
+      // Ignore errors during shutdown
+    }
+
+    // Give the process a moment to clean up
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(() => resolve(), 500);
+
+      this.process!.on("exit", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+
+      // Send SIGTERM
+      try {
+        this.process!.kill("SIGTERM");
+      } catch {
+        resolve();
+      }
+    });
+
+    // Force kill if still running
+    if (this.process && !this.process.killed) {
+      try {
+        this.process.kill("SIGKILL");
+      } catch {
+        // Already dead
+      }
+    }
+
+    this.cleanup();
+  }
+
+  /** Whether the client is currently connected */
+  get isConnected(): boolean {
+    return this.connected;
+  }
+
+  /** Process ID of the spawned MCP server, or undefined if not connected */
+  get pid(): number | undefined {
+    return this.process?.pid;
+  }
+
+  /** Captured stderr output */
+  get stderr(): string {
+    return this.stderrBuffer;
+  }
+
+  // ── Internal methods ────────────────────────────────────────────
+
+  private ensureConnected(): void {
+    if (!this.connected || !this.process) {
+      throw new Error("McpClient is not connected");
+    }
+  }
+
+  private sendRequest(
+    method: string,
+    params?: Record<string, unknown>,
+  ): Promise<unknown> {
+    return new Promise<unknown>((resolve, reject) => {
+      if (!this.process?.stdin) {
+        reject(new Error("MCP server process not available"));
+        return;
+      }
+
+      const id = this.nextId++;
+      const request: JsonRpcRequest = {
+        jsonrpc: "2.0",
+        id,
+        method,
+        params,
+      };
+
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(
+          new Error(
+            `MCP request timed out after ${this.timeoutMs}ms: ${method}`,
+          ),
+        );
+      }, this.timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+
+      const message = JSON.stringify(request) + "\n";
+      this.process.stdin.write(message);
+    });
+  }
+
+  private sendNotification(
+    method: string,
+    params?: Record<string, unknown>,
+  ): void {
+    if (!this.process?.stdin) return;
+
+    const notification: JsonRpcNotification = {
+      jsonrpc: "2.0",
+      method,
+      params,
+    };
+
+    const message = JSON.stringify(notification) + "\n";
+    this.process.stdin.write(message);
+  }
+
+  private handleStdoutData(chunk: Buffer): void {
+    this.buffer += chunk.toString();
+
+    // Process complete lines
+    let newlineIdx: number;
+    while ((newlineIdx = this.buffer.indexOf("\n")) !== -1) {
+      const line = this.buffer.slice(0, newlineIdx).trim();
+      this.buffer = this.buffer.slice(newlineIdx + 1);
+
+      if (!line) continue;
+
+      try {
+        const message = JSON.parse(line) as
+          | JsonRpcResponse
+          | JsonRpcNotification;
+
+        if ("id" in message && message.id !== undefined) {
+          // This is a response
+          this.handleResponse(message as JsonRpcResponse);
+        }
+        // Notifications are ignored for now
+      } catch {
+        // Skip malformed JSON lines
+      }
+    }
+  }
+
+  private handleResponse(response: JsonRpcResponse): void {
+    const pending = this.pending.get(response.id);
+    if (!pending) return;
+
+    this.pending.delete(response.id);
+    clearTimeout(pending.timer);
+
+    if (response.error) {
+      pending.reject(
+        new Error(
+          `MCP error ${response.error.code}: ${response.error.message}`,
+        ),
+      );
+    } else {
+      pending.resolve(response.result);
+    }
+  }
+
+  private rejectAllPending(error: Error): void {
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+      this.pending.delete(id);
+    }
+  }
+
+  private cleanup(): void {
+    this.connected = false;
+    this.rejectAllPending(new Error("McpClient disconnected"));
+    this.process = null;
+    this.buffer = "";
+  }
+}