pi-mcp-extension 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 irahardianto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# pi-mcp
+
+[![npm version](https://img.shields.io/npm/v/pi-mcp.svg)](https://www.npmjs.com/package/pi-mcp)
+[![license](https://img.shields.io/npm/l/pi-mcp.svg)](https://github.com/irahardianto/pi-mcp/blob/main/LICENSE)
+
+**Connect [Pi](https://pi.dev) to any MCP server.** Supabase, DeepSource, Playwright, Context7, filesystem, databases — if it speaks [MCP](https://modelcontextprotocol.io), Pi can use it.
+
+`pi-mcp` is a production-ready [Model Context Protocol](https://modelcontextprotocol.io/) client extension for the [Pi coding agent](https://pi.dev). It manages server connections, discovers tools, and bridges them into Pi so the LLM can call them directly.
+
+## Features
+
+- **Multi-transport** — `stdio` subprocesses, `streamable-http`, and legacy `sse` out of the box
+- **Auto-discovery** — Paginated `tools/list` with cursor following (MCP 2025-03-26 spec)
+- **Live tool refresh** — `notifications/tools/list_changed` triggers re-discovery without restart
+- **Clean cancellation** — `AbortSignal` propagation via `notifications/cancelled`
+- **Smart reconnection** — Fixed delay retry schedule (1s → 3s → 5s → 10s → 30s), configurable max retries
+- **Health checks** — Opt-in periodic pings to detect stale connections
+- **Safe process lifecycle** — PID tracking with safety-net `SIGKILL` for orphaned subprocesses
+- **Stable tool names** — Sanitized, collision-avoiding names (max 64 chars) that stay constant across reconnects
+- **No tool churn** — Activate/deactivate pattern ensures tools don't flicker during reconnection
+- **Global + project config** — Layered config (project overrides global) with per-server tuning
+- **Tool annotations** — `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` surfaced in tool descriptions
+- **Structured error handling** — Distinct error codes for config, connection, protocol, and tool-level failures
+
+## Installation
+
+```bash
+pi install npm:pi-mcp
+```
+
+Or try without installing:
+
+```bash
+pi -e npm:pi-mcp
+```
+
+## Quick Start
+
+1. Install the extension:
+   ```bash
+   pi install npm:pi-mcp
+   ```
+
+2. Create a config file at `~/.pi/agent/mcp.json` (global) or `.pi/mcp.json` (project-level):
+   ```jsonc
+   {
+     "mcpServers": {
+       "supabase": {
+         "transport": "streamable-http",
+         "url": "https://mcp.supabase.com/mcp",
+         "lifecycle": "eager"
+       }
+     }
+   }
+   ```
+
+3. Start Pi — your MCP tools are ready. Use `/mcp` to check server status.
+
+## Configuration
+
+Config files are loaded from two locations. **Project config overrides global config** via shallow merge (server-level replacement).
+
+| Location | Scope |
+|---|---|
+| `~/.pi/agent/mcp.json` | Global — applies to all projects |
+| `.pi/mcp.json` | Project — overrides global per-server |
+
+### Full Example
+
+```jsonc
+{
+  "settings": {
+    "toolPrefix": "mcp",         // Tools appear as mcp_<server>_<tool> (default: "mcp")
+    "requestTimeoutMs": 30000,   // Per-request timeout in ms (default: 30000)
+    "maxRetries": 5              // Max reconnection attempts, 0-10 (default: 5)
+  },
+  "mcpServers": {
+
+    // ── HTTP-based servers ───────────────────────────────────────────────────
+    "supabase": {
+      "transport": "streamable-http",
+      "url": "https://mcp.supabase.com/mcp",
+      "lifecycle": "eager"
+    },
+    "deepsource": {
+      "transport": "streamable-http",
+      "url": "https://mcp.deepsource.io/mcp",
+      "lifecycle": "eager"
+    },
+
+    // ── Legacy SSE servers ───────────────────────────────────────────────────
+    "legacy-server": {
+      "transport": "sse",
+      "url": "https://example.com/sse",
+      "lifecycle": "lazy"
+    },
+
+    // ── stdio subprocess servers ─────────────────────────────────────────────
+    "pathfinder": {
+      "command": "/path/to/pathfinder-mcp",
+      "transport": "stdio",
+      "lifecycle": "eager"
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@context7/mcp"],
+      "transport": "stdio",
+      "lifecycle": "lazy"
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
+      "transport": "stdio",
+      "lifecycle": "lazy",
+      "env": {
+        "NODE_ENV": "production"
+      }
+    }
+  }
+}
+```
+
+### Global Settings
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `toolPrefix` | `string` | `"mcp"` | Prefix for registered tools: `<prefix>_<server>_<tool>`. Must match `^[a-zA-Z][a-zA-Z0-9_]*$`. |
+| `requestTimeoutMs` | `number` | `30000` | Default per-request timeout in milliseconds |
+| `maxRetries` | `number` | `5` | Max reconnection attempts (0–10) before giving up |
+
+### Per-Server Config
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `transport` | `"stdio" \| "streamable-http" \| "sse"` | `"stdio"` | Transport protocol |
+| `command` | `string` | — | Executable to spawn (**required** for stdio) |
+| `args` | `string[]` | `[]` | Arguments for the command |
+| `env` | `Record<string, string>` | — | Extra environment variables for the child process |
+| `url` | `string` | — | Server URL (**required** for streamable-http/sse) |
+| `lifecycle` | `"eager" \| "lazy"` | `"lazy"` | `eager` = auto-start on session start, `lazy` = manual via `/mcp:start` |
+| `requestTimeoutMs` | `number` | global setting | Per-server timeout override |
+| `healthCheckIntervalMs` | `number` | disabled | Opt-in ping interval for connection health monitoring |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/mcp` | Show status summary of all configured servers |
+| `/mcp <name>` | Show detailed status and stderr log for a specific server |
+| `/mcp:start <name>` | Start a server (resets retry count) |
+| `/mcp:stop <name>` | Stop a running server and deactivate its tools |
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Pi Agent                                               │
+│                                                         │
+│  ┌──────────┐    ┌────────────────┐    ┌─────────────┐  │
+│  │ index.ts │───▶│ server-manager │───▶│ tool-bridge  │  │
+│  │ (entry)  │    │ (lifecycle)    │    │ (MCP → Pi)   │  │
+│  └──────────┘    └───────┬────────┘    └──────┬──────┘  │
+│       │                  │                     │         │
+│       ▼                  ▼                     ▼         │
+│  ┌──────────┐    ┌──────────────┐    ┌──────────────┐   │
+│  │ config   │    │ MCP SDK      │    │ TypeBox      │   │
+│  │ (Zod)    │    │ (transport)  │    │ (schema)     │   │
+│  └──────────┘    └──────────────┘    └──────────────┘   │
+└─────────────────────────────────────────────────────────┘
+         │                  │
+         ▼                  ▼
+   Global/Project    ┌──────────────┐
+   mcp.json files    │ MCP Servers  │
+                     │ (stdio/http) │
+                     └──────────────┘
+```
+
+1. **Config is loaded** from global and project files (project overrides global by server name)
+2. **Eager servers connect** at session start; lazy servers wait for `/mcp:start`
+3. **Tools are discovered** via paginated `tools/list` calls (cursor-based, up to 100 pages)
+4. **JSON Schema → TypeBox** conversion registers tools with Pi-compatible parameter schemas
+5. **Pi tools are registered** as `<prefix>_<server>_<tool>` (sanitized, max 64 chars with hash suffix)
+6. **Tools activate/deactivate** automatically as servers connect/disconnect
+7. **AbortSignal** is wired through to `notifications/cancelled` for clean cancellation
+8. **Reconnection** uses a fixed delay schedule with configurable max retries
+9. **`list_changed` notifications** trigger re-discovery, deactivating stale tools automatically
+10. **Session shutdown** cleanly stops all servers and deactivates all tools
+
+## MCP Spec Compliance
+
+Implements the **MCP 2025-03-26** specification for tool clients:
+
+| Feature | Status |
+|---|---|
+| Protocol version `2025-03-26` (+ `2024-11-05` fallback) | ✅ |
+| `stdio` transport | ✅ |
+| `streamable-http` transport | ✅ |
+| `sse` transport (legacy backwards compat) | ✅ |
+| Cursor-based `tools/list` pagination | ✅ |
+| `tools/call` with parameters | ✅ |
+| `roots/list` capability (workspace root) | ✅ |
+| `notifications/tools/list_changed` (live refresh) | ✅ |
+| `notifications/cancelled` (AbortSignal) | ✅ |
+| `notifications/message` (structured logging) | ✅ |
+| `isError: true` distinction (protocol vs tool errors) | ✅ |
+| Tool annotations (`readOnlyHint`, `destructiveHint`, etc.) | ✅ |
+| Resources bridge | ⏳ v2 |
+| Prompts bridge | ⏳ v2 |
+| Sampling | ⏳ v2 |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check (strict mode)
+npm run typecheck
+
+# Run all tests (47 tests)
+npm test
+
+# Run integration tests only (real stdio server)
+npm run test:integration
+```
+
+### Testing
+
+The test suite includes:
+- **Config validation** — Zod schema, global/project merge, defaults, error cases
+- **Server lifecycle** — Connect, retry, shutdown, health check, race conditions
+- **Tool bridge** — JSON Schema → TypeBox conversion, name sanitization, activate/deactivate
+- **End-to-end integration** — Real mock MCP server over stdio with tool discovery and execution
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "pi-mcp-extension",
+  "version": "1.3.0",
+  "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "mcp",
+    "model-context-protocol",
+    "pi",
+    "pi-extension",
+    "ai-agent",
+    "tool-bridge"
+  ],
+  "author": "irahardianto",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/irahardianto/pi-mcp.git"
+  },
+  "homepage": "https://github.com/irahardianto/pi-mcp",
+  "bugs": {
+    "url": "https://github.com/irahardianto/pi-mcp/issues"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx/esm --test ./tests/*.test.ts",
+    "test:integration": "node --import tsx/esm --test ./tests/server-manager.test.ts"
+  }
+}

package/src/config.ts

@@ -0,0 +1,159 @@
+/**
+ * Configuration loading, validation, and merging for pi-mcp.
+ *
+ * Config file locations (Pi-native convention, highest priority first):
+ *   1. <cwd>/.pi/mcp.json   — project-level config
+ *   2. ~/.pi/agent/mcp.json — global config
+ *
+ * Project servers/settings override global servers/settings per-key (shallow merge).
+ * No deep merge, no env var interpolation — WYSIWYG config.
+ */
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { McpError } from "./errors.js";
+
+// ─── Zod Schemas ──────────────────────────────────────────────────────────────
+
+const ServerConfigSchema = z
+  .object({
+    /** Executable to spawn (e.g. "npx", "node", "uvx"). Required for stdio. */
+    command: z.string().optional(),
+    /** Arguments passed to command. */
+    args: z.array(z.string()).default([]),
+    /**
+     * Extra environment variables passed to the child process as literals.
+     * These merge with process.env; project env overrides parent env.
+     * No ${VAR} interpolation — set vars in your shell environment instead.
+     */
+    env: z.record(z.string()).optional(),
+    /** Transport protocol. Default: "stdio". */
+    transport: z.enum(["stdio", "streamable-http", "sse"]).default("stdio"),
+    /**
+     * URL for streamable-http or sse transports.
+     * Must be a valid URL (e.g. "https://my-mcp-server.example.com/mcp").
+     */
+    url: z.string().url().optional(),
+    /**
+     * "eager" — start at session_start.
+     * "lazy"  — start manually via /mcp:start command.
+     */
+    lifecycle: z.enum(["eager", "lazy"]).default("lazy"),
+    /** Per-request timeout in ms. Overrides global setting. Default: 30000. */
+    requestTimeoutMs: z.number().positive().optional(),
+    /**
+     * Opt-in heartbeat interval (ping) in ms.
+     * Only useful for long-lived connections where you want proactive liveness checks.
+     * Default: disabled.
+     */
+    healthCheckIntervalMs: z.number().positive().optional(),
+  })
+  .refine(
+    (cfg) => {
+      if (cfg.transport === "stdio") return cfg.command !== undefined;
+      return cfg.url !== undefined;
+    },
+    (cfg) => ({
+      message:
+        cfg.transport === "stdio"
+          ? `"command" is required for stdio transport`
+          : `"url" is required for ${cfg.transport} transport`,
+    }),
+  );
+
+const SettingsSchema = z.object({
+  /**
+   * Prefix used in Pi tool names: <prefix>_<server>_<tool>.
+   * Must match [a-zA-Z0-9_]. Default: "mcp".
+   */
+  toolPrefix: z
+    .string()
+    .regex(/^[a-zA-Z0-9_]+$/, "toolPrefix must match [a-zA-Z0-9_]")
+    .default("mcp"),
+  /** Default per-request timeout in ms for all servers. Default: 30000. */
+  requestTimeoutMs: z.number().positive().default(30000),
+  /** Maximum retry attempts when a server fails to connect. Default: 5. */
+  maxRetries: z.number().int().min(0).max(10).default(5),
+});
+
+const McpConfigSchema = z.object({
+  settings: SettingsSchema.default({}),
+  mcpServers: z.record(ServerConfigSchema).default({}),
+});
+
+// ─── Public Types ─────────────────────────────────────────────────────────────
+
+export type ServerConfig = z.output<typeof ServerConfigSchema>;
+export type Settings = z.output<typeof SettingsSchema>;
+export type McpConfig = z.output<typeof McpConfigSchema>;
+
+// ─── Loader ───────────────────────────────────────────────────────────────────
+
+async function readJsonFile(path: string): Promise<unknown | null> {
+  try {
+    const text = await readFile(path, "utf8");
+    return JSON.parse(text) as unknown;
+  } catch (err) {
+    // ENOENT → file doesn't exist, silently skip
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+function parseConfig(raw: unknown, sourcePath: string): McpConfig {
+  const result = McpConfigSchema.safeParse(raw);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  ${i.path.join(".")}: ${i.message}`)
+      .join("\n");
+    throw new McpError(
+      `Invalid mcp.json at ${sourcePath}:\n${issues}`,
+      "<config>",
+      "config",
+    );
+  }
+  return result.data;
+}
+
+function mergeConfigs(
+  globalCfg: McpConfig,
+  projectCfg: McpConfig,
+): McpConfig {
+  return {
+    // Shallow spread: project settings override global settings per key
+    settings: { ...globalCfg.settings, ...projectCfg.settings },
+    // Per-server override: project server entry completely replaces global entry with same name
+    mcpServers: { ...globalCfg.mcpServers, ...projectCfg.mcpServers },
+  };
+}
+
+/**
+ * Load and merge global (~/.pi/agent/mcp.json) and project (<cwd>/.pi/mcp.json) configs.
+ * Project config takes precedence over global config.
+ * Returns a fully validated, merged config.
+ */
+export async function loadConfig(cwd: string): Promise<McpConfig> {
+  const globalPath = join(homedir(), ".pi", "agent", "mcp.json");
+  const projectPath = join(cwd, ".pi", "mcp.json");
+
+  const [globalRaw, projectRaw] = await Promise.all([
+    readJsonFile(globalPath),
+    readJsonFile(projectPath),
+  ]);
+
+  // If neither file exists, return an empty valid config
+  if (globalRaw === null && projectRaw === null) {
+    return McpConfigSchema.parse({});
+  }
+
+  const globalCfg = globalRaw !== null
+    ? parseConfig(globalRaw, globalPath)
+    : McpConfigSchema.parse({});
+
+  if (projectRaw === null) return globalCfg;
+
+  const projectCfg = parseConfig(projectRaw, projectPath);
+  return mergeConfigs(globalCfg, projectCfg);
+}

package/src/errors.ts

@@ -0,0 +1,35 @@
+/**
+ * Single error class for all MCP-related failures.
+ * `code` field enables programmatic discrimination without needing
+ * instanceof checks against a hierarchy of classes.
+ */
+
+export type McpErrorCode =
+  | "config"      // Configuration loading or validation failed
+  | "connection"  // Transport/connection failed
+  | "protocol"    // JSON-RPC protocol violation (server error response, timeout, etc.)
+  | "tool";       // Tool execution error (isError: true from server)
+
+export class McpError extends Error {
+  public readonly server: string;
+  public readonly code: McpErrorCode;
+  public readonly cause: unknown;
+
+  constructor(
+    message: string,
+    server: string,
+    code: McpErrorCode,
+    cause?: unknown,
+  ) {
+    super(message);
+    this.name = "McpError";
+    this.server = server;
+    this.code = code;
+    this.cause = cause;
+  }
+
+  /** Short user-facing message suitable for ctx.ui.notify() */
+  get userMessage(): string {
+    return `[${this.server}] ${this.message}`;
+  }
+}

package/src/index.ts

@@ -0,0 +1,170 @@
+/**
+ * pi-mcp — MCP client extension for the Pi coding agent.
+ *
+ * Entry point registered in package.json under "pi.extensions".
+ * Pi loads this file via jiti (TypeScript executed directly, no build step).
+ *
+ * Wires together: config → server manager → tool bridge → Pi API.
+ */
+
+import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { loadConfig } from "./config.js";
+import { ServerManager } from "./server-manager.js";
+import { ToolBridge } from "./tool-bridge.js";
+import { McpError } from "./errors.js";
+
+export default async function (pi: ExtensionAPI): Promise<void> {
+  // ── 1. Load and validate config ──────────────────────────────────────────
+  // cwd is available on the ExtensionContext passed to event handlers.
+  // We load config lazily on session_start to get the correct per-session cwd.
+  // For the initial load we use process.cwd() as a bootstrap path to detect
+  // whether any config exists at all.
+  let config;
+  try {
+    config = await loadConfig(process.cwd());
+  } catch (err) {
+    // Can't notify yet (no ctx), so log to stderr. The session_start handler
+    // will re-try with the real cwd and surface errors properly.
+    console.error(`[pi-mcp] Config error: ${err instanceof McpError ? err.message : String(err)}`);
+    return;
+  }
+
+  if (Object.keys(config.mcpServers).length === 0) {
+    // No servers configured — silently exit. Users can create mcp.json later.
+    return;
+  }
+
+  // ── 2. Initialize bridge components ──────────────────────────────────────
+  const manager = new ServerManager(config);
+  const bridge = new ToolBridge(config.settings, pi);
+
+  // Connect tool refresh callback: called on connect and on list_changed
+  manager.setToolRefreshCallback(async (serverName, client) => {
+    await bridge.refreshTools(serverName, client);
+  });
+
+  // ── 3. Session lifecycle ──────────────────────────────────────────────────
+  pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+    // Reload config with the real session cwd (project config may differ)
+    let sessionConfig = config;
+    try {
+      sessionConfig = await loadConfig(ctx.cwd);
+    } catch (err) {
+      const msg = err instanceof McpError ? err.userMessage : String(err);
+      ctx.ui.notify(`pi-mcp: Config error — ${msg}`, "error");
+      return;
+    }
+
+    // If config changed (different cwd with project-level overrides),
+    // shut down old servers and rebuild the manager's server list
+    if (JSON.stringify(sessionConfig) !== JSON.stringify(config)) {
+      // Deactivate and remove all tools from old config
+      for (const server of manager.getAllServers()) {
+        bridge.removeServer(server.name);
+      }
+      // Shut down all running servers
+      await manager.shutdownAll();
+      // Rebuild server entries from new config
+      manager.rebuildServers(sessionConfig);
+    }
+
+    const eagerServers = Object.entries(sessionConfig.mcpServers).filter(
+      ([, cfg]) => cfg.lifecycle === "eager",
+    );
+
+    // Start all eager servers concurrently
+    await Promise.allSettled(
+      eagerServers.map(async ([name]) => {
+        try {
+          await manager.startServer(name, ctx.cwd);
+        } catch (err) {
+          const msg = err instanceof McpError ? err.userMessage : String(err);
+          ctx.ui.notify(`pi-mcp: Failed to start ${name} — ${msg}`, "error");
+        }
+      }),
+    );
+  });
+
+  pi.on("session_shutdown", async (_event, _ctx: ExtensionContext) => {
+    // Deactivate all tools before shutting down servers
+    for (const server of manager.getAllServers()) {
+      bridge.deactivateServer(server.name);
+    }
+    await manager.shutdownAll();
+  });
+
+  // ── 4. /mcp — show server status ─────────────────────────────────────────
+  pi.registerCommand("mcp", {
+    description:
+      "Show MCP server status. Usage: /mcp [server-name] for detail.",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const serverName = args.trim();
+      if (serverName) {
+        // Detailed view: status + recent stderr
+        const server = manager.getServer(serverName);
+        if (!server) {
+          ctx.ui.notify(`pi-mcp: No server named "${serverName}"`, "error");
+          return;
+        }
+        const logs = manager.getServerLogs(serverName);
+        const detail = [
+          `Server: ${serverName}`,
+          `State:  ${server.state}`,
+          `Retries: ${server.retryCount}`,
+          server.lastError ? `Last error: ${server.lastError.message}` : null,
+          "",
+          "Recent output:",
+          logs,
+        ]
+          .filter(Boolean)
+          .join("\n");
+        ctx.ui.notify(detail, "info");
+      } else {
+        // Summary view: all servers
+        ctx.ui.notify(manager.getStatusSummary(), "info");
+      }
+    },
+  });
+
+  // ── 5. /mcp:stop — stop a server ─────────────────────────────────────────
+  pi.registerCommand("mcp:stop", {
+    description: "Stop an MCP server. Usage: /mcp:stop <server-name>",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const serverName = args.trim();
+      if (!serverName) {
+        ctx.ui.notify("Usage: /mcp:stop <server-name>", "error");
+        return;
+      }
+      if (!manager.getServer(serverName)) {
+        ctx.ui.notify(`pi-mcp: No server named "${serverName}"`, "error");
+        return;
+      }
+      bridge.deactivateServer(serverName);
+      await manager.stopServer(serverName);
+      ctx.ui.notify(`pi-mcp: Stopped ${serverName}`, "info");
+    },
+  });
+
+  // ── 6. /mcp:start — manually start a lazy server ─────────────────────────
+  pi.registerCommand("mcp:start", {
+    description: "Start an MCP server. Usage: /mcp:start <server-name>",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const serverName = args.trim();
+      if (!serverName) {
+        ctx.ui.notify("Usage: /mcp:start <server-name>", "error");
+        return;
+      }
+      if (!manager.getServer(serverName)) {
+        ctx.ui.notify(`pi-mcp: No server named "${serverName}"`, "error");
+        return;
+      }
+      try {
+        await manager.startServer(serverName, ctx.cwd);
+        ctx.ui.notify(`pi-mcp: Started ${serverName}`, "info");
+      } catch (err) {
+        const msg = err instanceof McpError ? err.userMessage : String(err);
+        ctx.ui.notify(`pi-mcp: Failed to start ${serverName} — ${msg}`, "error");
+      }
+    },
+  });
+}