pi-mcp-extension 1.9.1 → 1.9.2

package/README.md

@@ -9,19 +9,20 @@
 
 ## Features
 
-- **Multi-transport** — `stdio` subprocesses, `streamable-http`, and legacy `sse` out of the box
+- **Multi-transport** — `stdio` subprocesses, `streamable-http` (including `"http"` and URL-only shorthand), 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
+- **Smart reconnection** — Fixed delay retry schedule (1s → 3s → 5s → 10s → 30s), configurable max retries, and automatic recovery when a server transport closes unexpectedly
 - **Health checks** — Opt-in periodic pings to detect stale connections
-- **Safe process lifecycle** — PID tracking with safety-net `SIGKILL` for orphaned subprocesses
+- **Safe process lifecycle** — Child PID tracking (`StdioClientTransport.pid`) 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
+- **Layered config & trust boundary** — Global `<agent dir>/mcp.json`, project `.pi/mcp.json` (loaded only in trusted projects via `ctx.isProjectTrusted()`), and Pi 1.x extension-registered servers (`pi.registerMcpServer()`)
+- **Rich tool results & annotations** — MCP `image` content passthrough (`ImageContent`), plus `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` surfaced in tool descriptions
+- **On-demand agent tools & commands** — `mcp_status` and `mcp_connect` agent tools plus `/mcp`, `/mcp:start`, `/mcp:stop`, and `/mcp:auth` slash commands with server-name autocomplete
 - **Structured error handling** — Distinct error codes for config, connection, protocol, and tool-level failures
-- **OAuth 2.1** — Browser authorization with PKCE, protected-resource discovery, token refresh, and secure local persistence
+- **OAuth 2.1** — Browser and headless/SSH authorization with PKCE, protected-resource discovery, Dynamic Client Registration, startup prompts for eager servers, cross-process lock recovery, token refresh, and secure local persistence (see [OAUTH.md](./OAUTH.md))
 
 ## Installation
 
@@ -42,7 +43,16 @@ pi -e npm:pi-mcp-extension
    pi install npm:pi-mcp-extension
    ```
 
-2. Create a config file at `~/.pi/agent/mcp.json` (global) or `.pi/mcp.json` (project-level):
+2. *(Pi 1.x)* Disable Pi's built-in `mcp` extension so Pi does not warn that both extensions are enabled at the same time — either run `pi config` and uncheck `mcp` under **Built-in extensions**, or add `"extensions": ["-builtin:mcp"]` to `~/.pi/agent/settings.json`:
+   ```jsonc
+   {
+     "extensions": [
+       "-builtin:mcp"
+     ]
+   }
+   ```
+
+3. Create a config file at `~/.pi/agent/mcp.json` (global) or `.pi/mcp.json` (project-level):
    ```jsonc
    {
      "mcpServers": {
@@ -55,16 +65,17 @@ pi -e npm:pi-mcp-extension
    }
    ```
 
-3. Start Pi — your MCP tools are ready. Use `/mcp` to check server status.
+4. 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).
+Servers can be configured via JSON files or registered programmatically by other Pi 1.x extensions:
 
-| Location | Scope |
+| Source | Precedence & Scope |
 |---|---|
-| `~/.pi/agent/mcp.json` | Global — applies to all projects (honors `$PI_CODING_AGENT_DIR` when set: `<agent dir>/mcp.json`) |
-| `.pi/mcp.json` | Project — overrides global per-server |
+| `.pi/mcp.json` | **Highest** — Project-level overrides per server and per explicitly stated setting. Loaded on `session_start` **only when the project is trusted** (`ctx.isProjectTrusted()`); never read at bootstrap or in untrusted projects. |
+| `~/.pi/agent/mcp.json` | **Global** — Applies to all projects (honors `$PI_CODING_AGENT_DIR` with `~` expansion when set: `<agent dir>/mcp.json`). |
+| `pi.registerMcpServer()` | **Extension-registered** — Discovered via `pi.getMcpServers()` and updated live on `mcp_servers_change` events when replacing `builtin:mcp`. Any server with the same name in `mcp.json` takes precedence. |
 
 ### Full Example
 
@@ -87,8 +98,7 @@ Config files are loaded from two locations. **Project config overrides global co
       "lifecycle": "eager"
     },
     "deepsource": {
-      "transport": "streamable-http",
-      "url": "https://mcp.deepsource.io/mcp",
+      "url": "https://mcp.deepsource.io/mcp", // "transport" defaults to "streamable-http" when "url" is set
       "lifecycle": "eager"
     },
 
@@ -126,6 +136,8 @@ Config files are loaded from two locations. **Project config overrides global co
 
 ### Global Settings
 
+In project-level `.pi/mcp.json`, `settings` keys carry no defaults — only the keys explicitly stated in the project file override 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_]*$`. |
@@ -134,28 +146,32 @@ Config files are loaded from two locations. **Project config overrides global co
 
 ### Per-Server Config
 
+For Pi 1.x compatibility, server entries also accept `type` as an alias for `transport`, `"http"` as an alias for `"streamable-http"`, `oauth` as an alias for `auth`, and `timeout` (in seconds) as an alias for `requestTimeoutMs`.
+
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `transport` | `"stdio" \| "streamable-http" \| "sse"` | `"stdio"` | Transport protocol |
-| `command` | `string` | — | Executable to spawn (**required** for stdio) |
+| `transport` (or `type`) | `"stdio" \| "streamable-http" \| "http" \| "sse"` | `"stdio"` (`"streamable-http"` when `url` is set without `command`) | Transport protocol (`"http"` is normalized to `"streamable-http"`) |
+| `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) |
-| `headers` | `Record<string, string>` | — | Static headers sent with HTTP and SSE requests |
-| `auth` | `object` | — | OAuth configuration described below |
-| `lifecycle` | `"eager" \| "lazy"` | `"lazy"` | `eager` = auto-start on session start, `lazy` = connect on request via `mcp_connect` or `/mcp:start` |
-| `requestTimeoutMs` | `number` | global setting | Per-server timeout override |
-| `healthCheckIntervalMs` | `number` | disabled | Opt-in ping interval for connection health monitoring |
+| `env` | `Record<string, string>` | — | Extra environment variables for the child process (literal values, no `${VAR}` interpolation) |
+| `url` | `string` | — | Server URL (**required** for `streamable-http` and `sse`) |
+| `headers` | `Record<string, string>` | — | Static headers sent with `streamable-http` and `sse` requests |
+| `auth` (or `oauth`) | `object` | — | OAuth 2.1 configuration described below and in [OAUTH.md](./OAUTH.md) (`streamable-http` / `sse` only) |
+| `lifecycle` | `"eager" \| "lazy"` | `"lazy"` (`"eager"` for `pi.registerMcpServer()` unless `enabled: false`) | `eager` = auto-start on `session_start`, `lazy` = connect on request via `mcp_connect`, `/mcp:start`, or `/mcp:auth` |
+| `requestTimeoutMs` (or `timeout`) | `number` | global setting | Per-server timeout override in ms (`timeout` is specified in seconds and multiplied by `1000`) |
+| `healthCheckIntervalMs` | `number` | disabled | Opt-in ping interval in ms for proactive connection health monitoring |
 
 ### OAuth Config
 
+Configured under `auth` (or `oauth`). Token and client state are persisted per server in `<agent dir>/mcp-auth/<hash>.json` (`0700` directory, `0600` files on POSIX) with atomic writes and automatic backup of corrupt state files. See [OAUTH.md](./OAUTH.md) for architecture and troubleshooting details.
+
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `type` | `"oauth"` | `"oauth"` | Authentication type |
-| `scope` | `string` | discovered | Requested scope when the server does not advertise one |
-| `clientId` | `string` | dynamic registration | Pre-registered OAuth client ID |
+| `scope` | `string` | discovered | Requested scope when the server does not advertise one in `WWW-Authenticate` |
+| `clientId` | `string` | dynamic registration | Pre-registered OAuth client ID (skips Dynamic Client Registration) |
 | `clientSecret` | `string` | — | Secret for a pre-registered confidential client |
-| `redirectUrl` | `string` | `http://127.0.0.1:19876/callback` | Local HTTP loopback callback used by `/mcp:auth` |
+| `redirectUrl` (or `oauth.callbackUrl` / `oauth.callbackPort`) | `string` | `http://127.0.0.1:19876/callback` | Local HTTP loopback callback (`localhost`, `127.0.0.1`, or `::1` with path `/callback` and an explicit non-zero port; `callbackPort` maps to `http://127.0.0.1:<port>/callback`). Scans forward from `19876` when omitted; binds the exact host and port when configured. |
 
 ## Commands
 
@@ -166,11 +182,18 @@ Server-name arguments provide autocomplete suggestions from the configured MCP s
 | `/mcp` | Show status summary of all configured servers |
 | `/mcp <name>` | Show detailed status and stderr log for a specific server |
 | `/mcp:start <name>` | Connect a server and wait for tool discovery |
-| `/mcp:stop <name>` | Cancel a pending connection or authorization, or stop a running server and deactivate its tools |
+| `/mcp:stop <name>` | Cancel a pending connection, startup prompt, or authorization, or stop a running server and deactivate its tools |
 | `/mcp:auth <name>` | Connect with stored OAuth credentials; request browser authorization only if needed |
 | `/mcp:auth <name> --reset` | Discard stored OAuth credentials and request fresh authorization |
 
-Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and connect one named server without routine slash commands. `mcp_status` reports lifecycle, connection state, credential presence, and safe action hints without returning tokens, headers, or authorization URLs. `mcp_connect` activates discovered tools before returning success. Connection failures return fixed actionable categories instead of raw server response text. Repeated credential resets share one pending authorization; stop or shutdown cancels it. Lazy servers remain stopped until requested. An interactive Pi session is required when browser authorization is needed. Eager startup never opens a browser. Retry opens the browser again only when selected in the OAuth prompt.
+Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and connect one named server without routine slash commands. `mcp_status` reports lifecycle, connection state, discovered and active tool counts, credential presence, and safe action hints without returning tokens, headers, or authorization URLs. `mcp_connect` activates discovered tools before returning success. Connection failures return fixed actionable categories instead of raw server response text.
+
+### OAuth startup, headless/SSH, and concurrency behavior
+
+- **Interactive sessions required for browser auth**: Print and RPC sessions fail promptly when interactive authorization is required.
+- **Startup prompt for eager OAuth servers**: Silent startup and background reconnects never open a browser unprompted or trigger Dynamic Client Registration when no client credentials are stored. When an `eager` OAuth server needs interactive authorization at startup in an interactive Pi session, Pi presents a sequential `<name> needs authorization` prompt (`Authorize now` / `Not now`). Choosing `Authorize now` runs the interactive OAuth flow; choosing `Not now` leaves the server stopped, shows a `run /mcp:auth <name>` footer hint, and remembers the decline for the rest of the session.
+- **Headless and SSH support**: While authorization is pending, Pi displays the authorization URL and offers `Retry: open browser again`, `Paste redirect URL`, and `Cancel authentication`. On remote/SSH or headless machines, open the URL locally and either forward the callback port (`ssh -L <port>:127.0.0.1:<port>`) or paste the browser's final `http://127.0.0.1:<port>/callback?code=...&state=...` redirect URL into `Paste redirect URL`. Only `https:` (or loopback `http:`) authorization URLs are passed to the system browser opener.
+- **Coordinated connects and cross-process locks**: Concurrent connect requests join an in-flight attempt, while `--reset` supersedes a normal connect and shares one pending reset. Cross-process interactive flows are serialized per server via `<agent dir>/mcp-auth/<hash>.json.lock` with a 30s heartbeat and automatic reclamation of locks from dead local PIDs or stale heartbeats (>90s), while allowing silent token refreshes to persist rotated tokens.
 
 ### Connection readiness and active tools
 
@@ -199,20 +222,20 @@ Agent tools `mcp_status` and `mcp_connect` let Pi inspect configured servers and
          ▼                  ▼
    Global/Project    ┌──────────────┐
    mcp.json files    │ MCP Servers  │
-                     │ (stdio/http) │
+   + Extensions      │ (stdio/http) │
                      └──────────────┘
 ```
 
-1. **Config is loaded** from global and project files (project overrides global by server name)
-2. **Eager servers connect** at session start without opening browsers; lazy servers wait for `mcp_connect` or `/mcp:start`
-3. **Tools are discovered** via paginated `tools/list` calls (cursor-based, up to 100 pages)
+1. **Config is loaded** from global `<agent dir>/mcp.json`, trusted project `.pi/mcp.json` (checked via `ctx.isProjectTrusted()` on `session_start`), and extension-registered servers (`pi.getMcpServers()` / `mcp_servers_change`), with `mcp.json` taking precedence over extension-registered servers and project entries overriding global ones
+2. **Eager servers connect** at `session_start` (offering a sequential `Authorize now` / `Not now` prompt when an eager OAuth server needs authorization in an interactive session); lazy servers wait for `mcp_connect`, `/mcp:start`, or `/mcp:auth`
+3. **Tools are discovered** via paginated `tools/list` calls (cursor-based, up to 100 pages) before a server enters `ready`
 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)
+5. **Pi tools are registered** as `<prefix>_<server>_<tool>` (sanitized, max 64 chars with hash suffix) and pass through text and `image` content blocks (`ImageContent`)
 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
+8. **Reconnection & recovery** uses a fixed delay schedule with configurable max retries on initial failure, health check failure, or unexpected transport close (`client.onclose`)
 9. **`list_changed` notifications** trigger re-discovery, deactivating stale tools automatically
-10. **Session shutdown** cleanly stops all servers and deactivates all tools
+10. **Session shutdown** cancels pending auth/connection flows, stops the callback server, deactivates all tools, and cleanly stops all servers (with a `SIGKILL` safety net for `stdio` child processes)
 
 ## MCP Spec Compliance
 
@@ -222,15 +245,16 @@ Implements the **MCP 2025-03-26** specification for tool clients:
 |---|---|
 | Protocol version `2025-03-26` (+ `2024-11-05` fallback) | ✅ |
 | `stdio` transport | ✅ |
-| `streamable-http` transport | ✅ |
+| `streamable-http` transport (including `"http"` / URL-only shorthand) | ✅ |
 | `sse` transport (legacy backwards compat) | ✅ |
+| OAuth 2.1 authorization (PKCE S256, RFC 9728 Protected Resource Metadata, RFC 7591 DCR) | ✅ |
 | Cursor-based `tools/list` pagination | ✅ |
-| `tools/call` with parameters | ✅ |
+| `tools/call` with parameters & `image` content (`ImageContent`) passthrough | ✅ |
 | `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) | ✅ |
+| `isError: true` distinction (protocol vs tool errors, non-text filtered on error) | ✅ |
 | Tool annotations (`readOnlyHint`, `destructiveHint`, etc.) | ✅ |
 | Resources bridge | ⏳ v2 |
 | Prompts bridge | ⏳ v2 |
@@ -255,10 +279,11 @@ 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
+- **Config & Pi 1.x compatibility** — Zod schema, `$PI_CODING_AGENT_DIR` resolution, global/project merge, project trust boundary (`ctx.isProjectTrusted()`), Pi 1.x schema aliases (`type: "http"`, URL-only HTTP, `oauth`, `timeout`), and dynamic `pi.getMcpServers()` / `mcp_servers_change`
+- **Server lifecycle & coordination** — Connect, retry, unexpected close recovery, shutdown with PID `SIGKILL` safety net, health check, concurrent connect/reset coordination, and cancellation
+- **OAuth 2.1 & auth locks** — Challenge discovery, PKCE, Dynamic Client Registration, startup authorization prompts, headless/SSH redirect URL paste-back, URL scheme validation, cross-process lock heartbeat and stale lock reclamation
+- **Tool bridge & management tools** — JSON Schema → TypeBox conversion, name sanitization, image content passthrough, `isError` filtering, activate/deactivate, `mcp_status` / `mcp_connect`, and slash command completions
+- **End-to-end integration** — Real mock MCP and OAuth servers over stdio and HTTP with tool discovery and execution
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [

package/src/callback-server.ts

@@ -149,7 +149,9 @@ async function closeCurrentServer(): Promise<void> {
  * scans forward from the default port if needed.
  */
 export function callbackServerConfigFromRedirectUrl(redirectUrl?: string): CallbackServerConfig {
-  if (!redirectUrl) {
+  // WHY: Only treat `undefined` (omitted) as default; an explicit empty string `""`
+  // must fall through to `new URL("")` and throw a validation error.
+  if (redirectUrl === undefined) {
     return {
       preferredPort: DEFAULT_PORT,
       host: DEFAULT_HOST,
@@ -236,7 +238,7 @@ export async function ensureCallbackServer(preferredPort: number = DEFAULT_PORT,
       });
 
       await new Promise<void>((resolve, reject) => {
-        candidateServer.once("error", (err: any) => {
+        candidateServer.once("error", (err: Error) => {
           reject(err);
         });
 

package/src/config.ts

@@ -14,31 +14,64 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
+import { callbackServerConfigFromRedirectUrl } from "./callback-server.js";
 import { McpError } from "./errors.js";
 
 // ─── Zod Schemas ──────────────────────────────────────────────────────────────
 
-const AuthConfigSchema = z.object({
-  /** Auth type. Currently only "oauth" is supported. Default: "oauth". */
-  type: z.enum(["oauth"]).default("oauth"),
-  /**
-   * Callback URL for the OAuth redirect.
-   * Default: auto-detected local callback server.
-   */
-  redirectUrl: z.string().optional(),
-  /**
-   * Optional scope to request during authorization.
-   */
-  scope: z.string().optional(),
-  /**
-   * Pre-registered client_id (skip dynamic client registration).
-   */
-  clientId: z.string().optional(),
-  /**
-   * Pre-registered client_secret.
-   */
-  clientSecret: z.string().optional(),
-});
+const AuthConfigSchema = z.preprocess(
+  (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
+    const obj = { ...(raw as Record<string, unknown>) };
+    if (obj.redirectUrl === undefined) {
+      if (typeof obj.callbackUrl === "string") {
+        obj.redirectUrl = obj.callbackUrl;
+      } else if (typeof obj.callbackPort === "number") {
+        obj.redirectUrl = `http://127.0.0.1:${obj.callbackPort}/callback`;
+      } else if (obj.callbackUrl !== undefined) {
+        obj.redirectUrl = obj.callbackUrl;
+      }
+    }
+    delete obj.callbackUrl;
+    delete obj.callbackPort;
+    return obj;
+  },
+  z
+    .object({
+      /** Auth type. Currently only "oauth" is supported. Default: "oauth". */
+      type: z.enum(["oauth"]).default("oauth"),
+      /**
+       * Callback URL for the OAuth redirect.
+       * Default: auto-detected local callback server.
+       */
+      redirectUrl: z.string().optional(),
+      /**
+       * Optional scope to request during authorization.
+       */
+      scope: z.string().optional(),
+      /**
+       * Pre-registered client_id (skip dynamic client registration).
+       */
+      clientId: z.string().optional(),
+      /**
+       * Pre-registered client_secret.
+       */
+      clientSecret: z.string().optional(),
+    })
+    .superRefine((auth, ctx) => {
+      if (auth.redirectUrl !== undefined) {
+        try {
+          callbackServerConfigFromRedirectUrl(auth.redirectUrl);
+        } catch (err) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["redirectUrl"],
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }),
+);
 
 export const ServerConfigSchema = z.preprocess(
   (raw) => {
@@ -53,22 +86,7 @@ export const ServerConfigSchema = z.preprocess(
       obj.transport = "streamable-http";
     }
     if (obj.auth === undefined && obj.oauth && typeof obj.oauth === "object" && !Array.isArray(obj.oauth)) {
-      const oauth = obj.oauth as Record<string, unknown>;
-      const redirectUrl =
-        typeof oauth.redirectUrl === "string"
-          ? oauth.redirectUrl
-          : typeof oauth.callbackUrl === "string"
-            ? oauth.callbackUrl
-            : typeof oauth.callbackPort === "number"
-              ? `http://127.0.0.1:${oauth.callbackPort}/callback`
-              : undefined;
-      obj.auth = {
-        type: "oauth",
-        ...(redirectUrl !== undefined ? { redirectUrl } : {}),
-        ...(typeof oauth.scope === "string" ? { scope: oauth.scope } : {}),
-        ...(typeof oauth.clientId === "string" ? { clientId: oauth.clientId } : {}),
-        ...(typeof oauth.clientSecret === "string" ? { clientSecret: oauth.clientSecret } : {}),
-      };
+      obj.auth = obj.oauth;
     }
     if (obj.requestTimeoutMs === undefined && typeof obj.timeout === "number" && obj.timeout > 0) {
       obj.requestTimeoutMs = obj.timeout * 1000;
@@ -132,17 +150,24 @@ export const ServerConfigSchema = z.preprocess(
             ? `"command" is required for stdio transport`
             : `"url" is required for ${cfg.transport} transport`,
       }),
+    )
+    .refine(
+      (cfg) => !(cfg.transport === "stdio" && cfg.auth !== undefined),
+      {
+        message: "OAuth authentication is only supported for 'sse' and 'streamable-http' transports, not 'stdio'",
+        path: ["auth"],
+      },
     ),
 );
 
 const SettingsSchema = z.object({
   /**
    * Prefix used in Pi tool names: <prefix>_<server>_<tool>.
-   * Must match [a-zA-Z0-9_]. Default: "mcp".
+   * Must match ^[a-zA-Z][a-zA-Z0-9_]*$. Default: "mcp".
    */
   toolPrefix: z
     .string()
-    .regex(/^[a-zA-Z0-9_]+$/, "toolPrefix must match [a-zA-Z0-9_]")
+    .regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, "toolPrefix must start with a letter and contain only alphanumeric characters and underscores")
     .default("mcp"),
   /** Default per-request timeout in ms for all servers. Default: 30000. */
   requestTimeoutMs: z.number().positive().default(30000),
@@ -163,7 +188,7 @@ const McpConfigSchema = z.object({
 const ProjectSettingsSchema = z.object({
   toolPrefix: z
     .string()
-    .regex(/^[a-zA-Z0-9_]+$/, "toolPrefix must match [a-zA-Z0-9_]")
+    .regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, "toolPrefix must start with a letter and contain only alphanumeric characters and underscores")
     .optional(),
   requestTimeoutMs: z.number().positive().optional(),
   maxRetries: z.number().int().min(0).max(10).optional(),
@@ -193,14 +218,105 @@ export interface LoadConfigOptions {
 
 // ─── Loader ───────────────────────────────────────────────────────────────────
 
-async function readJsonFile(path: string): Promise<unknown | null> {
+/**
+ * Strip `//` line comments and `/* ... *\/` block comments outside of double-quoted
+ * JSON strings in a single character-by-character pass.
+ *
+ * Preserves `\n` and `\r` characters so line numbers in `JSON.parse` error messages
+ * remain accurate. Unterminated `/*` block comments are left intact so `JSON.parse`
+ * fails with a syntax error rather than silently truncating the document.
+ */
+export function stripJsonComments(text: string): string {
+  let out = "";
+  let inString = false;
+  let i = 0;
+
+  while (i < text.length) {
+    const ch = text[i]!;
+
+    if (inString) {
+      if (ch === "\\") {
+        out += ch;
+        if (i + 1 < text.length) {
+          out += text[i + 1]!;
+          i += 2;
+        } else {
+          i += 1;
+        }
+        continue;
+      }
+      if (ch === '"') {
+        inString = false;
+      }
+      out += ch;
+      i += 1;
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = true;
+      out += ch;
+      i += 1;
+      continue;
+    }
+
+    if (ch === "/" && text[i + 1] === "/") {
+      i += 2;
+      while (i < text.length && text[i] !== "\n") {
+        if (text[i] === "\r" && text[i + 1] === "\n") break;
+        i += 1;
+      }
+      continue;
+    }
+
+    if (ch === "/" && text[i + 1] === "*") {
+      const closeIdx = text.indexOf("*/", i + 2);
+      if (closeIdx === -1) {
+        // WHY: Leave unterminated block comments intact so JSON.parse fails with a
+        // SyntaxError rather than silently truncating the rest of the file.
+        out += text.slice(i);
+        break;
+      }
+      for (let j = i; j < closeIdx + 2; j += 1) {
+        const commentCh = text[j]!;
+        out += commentCh === "\n" || commentCh === "\r" ? commentCh : " ";
+      }
+      i = closeIdx + 2;
+      continue;
+    }
+
+    out += ch;
+    i += 1;
+  }
+
+  return out;
+}
+
+async function readJsonFile(path: string): Promise<unknown> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new McpError(
+      `Failed to read mcp.json at ${path}: ${detail}`,
+      "<config>",
+      "config",
+      err,
+    );
+  }
+
   try {
-    const text = await readFile(path, "utf8");
-    return JSON.parse(text) as unknown;
+    return JSON.parse(stripJsonComments(text));
   } catch (err) {
-    // ENOENT → file doesn't exist, silently skip
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
-    throw err;
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new McpError(
+      `Invalid JSON in mcp.json at ${path}: ${detail}`,
+      "<config>",
+      "config",
+      err,
+    );
   }
 }
 
@@ -303,19 +419,19 @@ export async function loadConfig(
 
   const [globalRaw, projectRaw] = await Promise.all([
     readJsonFile(globalPath),
-    includeProjectConfig ? readJsonFile(projectPath) : Promise.resolve(null),
+    includeProjectConfig ? readJsonFile(projectPath) : Promise.resolve(undefined),
   ]);
 
   // If neither file exists, return an empty valid config
-  if (globalRaw === null && projectRaw === null) {
+  if (globalRaw === undefined && projectRaw === undefined) {
     return McpConfigSchema.parse({});
   }
 
-  const globalCfg = globalRaw !== null
+  const globalCfg = globalRaw !== undefined
     ? parseConfig(globalRaw, globalPath)
     : McpConfigSchema.parse({});
 
-  if (projectRaw === null) return globalCfg;
+  if (projectRaw === undefined) return globalCfg;
 
   const projectCfg = parseWith(ProjectConfigSchema, projectRaw, projectPath);
   return mergeConfigs(globalCfg, projectCfg);