pi-mcp-extension 1.11.0 → 1.11.1

package/README.md

@@ -151,21 +151,37 @@ In project-level `.pi/mcp.json`, `settings` keys carry no defaults — only the
 
 ### 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`.
+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`, `timeout` (in seconds) as an alias for `requestTimeoutMs`, and `enabled: false` as a request to keep the server out of the eager set (`lifecycle: "lazy"`). Pi's `auth.provider` (`/login` provider token) is **rejected** at load time instead of being silently downgraded to OAuth 2.1 — use `auth` (OAuth) or static `headers`.
 
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `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 |
+| `cwd` | `string` | session working directory | Working directory for a `stdio` server (rejected on `streamable-http` / `sse`). A relative path resolves against the session working directory and a leading `~` expands to your home directory |
 | `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` |
+| `enabled` | `boolean` | `true` | Pi 1.3.0 switch: `false` keeps the entry configured but out of the eager set (normalized to `lifecycle: "lazy"`, even when `lifecycle: "eager"` is also set) |
 | `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 |
 
+### Project Override Entries
+
+A trusted project's `.pi/mcp.json` may carry a Pi 1.3.0 **partial override** for a global server: an entry with no `command`, `url`, `type`, or `transport` changes only per-project settings and keeps the rest of the global entry, including credentials the project cannot set itself.
+
+```jsonc
+// ~/.pi/agent/mcp.json
+{ "mcpServers": { "internal-tools": { "command": "internal-mcp", "lifecycle": "eager" } } }
+
+// <project>/.pi/mcp.json — turn it off for this project only
+{ "mcpServers": { "internal-tools": { "enabled": false } } }
+```
+
+An override may set `enabled`, `lifecycle`, and Pi's `exposure` / `toolExposure` (the two Pi-native exposure keys are accepted for Pi compatibility and ignored, because this extension decides tool activation itself). Any other key, or an override for a name no global entry defines, is reported as a config error naming the file and the server.
+
 ### 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.
@@ -176,6 +192,7 @@ Configured under `auth` (or `oauth`). Token and client state are persisted per s
 | `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 |
+| `clientName` (or `oauth.clientName`) | `string` | `pi-mcp/<server name>` | `client_name` sent with Dynamic Client Registration, for servers that only accept known clients |
 | `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

package/package.json

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

package/src/config.ts

@@ -7,7 +7,9 @@
  *      $PI_CODING_AGENT_DIR when set (Pi profiles / alternative agent dirs), else ~/.pi/agent
  *
  * Project servers/settings override global servers/settings per-key (shallow merge).
- * No deep merge, no env var interpolation — WYSIWYG config.
+ * A Pi 1.3.0 partial project entry (`{ "enabled": false }` — no `command`/`url`) overrides only the
+ * per-project keys of the global server of that name, keeping the global entry's credentials.
+ * No deep merge of any other keys, no env var interpolation — WYSIWYG config.
  */
 
 import { readFile } from "node:fs/promises";
@@ -58,8 +60,27 @@ const AuthConfigSchema = z.preprocess(
        * Pre-registered client_secret.
        */
       clientSecret: z.string().optional(),
+      /**
+       * `client_name` sent with Dynamic Client Registration (Pi 1.3.0 `oauth.clientName`).
+       * Default: `pi-mcp/<server name>`.
+       */
+      clientName: z.string().trim().min(1).optional(),
+      /**
+       * Pi's `/login` provider auth (`auth.provider`), accepted only so it can be rejected with a
+       * clear error: this extension runs OAuth 2.1 and cannot forward a Pi provider token.
+       */
+      provider: z.unknown().optional(),
     })
     .superRefine((auth, ctx) => {
+      if (auth.provider !== undefined) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["provider"],
+          message:
+            '"auth.provider" sends a Pi /login provider token, which pi-mcp-extension does not support; ' +
+            'remove it to use OAuth 2.1, or send a static credential with "headers"',
+        });
+      }
       if (auth.redirectUrl !== undefined) {
         try {
           callbackServerConfigFromRedirectUrl(auth.redirectUrl);
@@ -104,6 +125,17 @@ function normalizeAuthAlias(obj: Record<string, unknown>): void {
   }
 }
 
+/**
+ * Map Pi 1.3.0 `enabled: false` onto `lifecycle: "lazy"`. Pi keeps a disabled entry configured but
+ * out of the connect set; the closest behavior here is the lazy lifecycle (manual `/mcp:start`).
+ * An explicit `lifecycle: "eager"` never wins over `enabled: false`, which is what Pi does too.
+ */
+function normalizeEnabledAlias(obj: Record<string, unknown>): void {
+  if (obj.enabled === false) {
+    obj.lifecycle = "lazy";
+  }
+}
+
 /** Map legacy `timeout` (seconds) onto `requestTimeoutMs` (milliseconds). */
 function normalizeTimeoutAlias(obj: Record<string, unknown>): void {
   if (obj.requestTimeoutMs !== undefined) {
@@ -115,13 +147,14 @@ function normalizeTimeoutAlias(obj: Record<string, unknown>): void {
   obj.requestTimeoutMs = obj.timeout * 1000;
 }
 
-/** Rewrite Pi 1.x config aliases (`type`, `oauth`, `timeout`) before schema validation. */
+/** Rewrite Pi 1.x config aliases (`type`, `oauth`, `timeout`, `enabled`) before schema validation. */
 function normalizeServerConfigAliases(raw: unknown): unknown {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
   const obj = { ...(raw as Record<string, unknown>) };
   normalizeTransportAlias(obj);
   normalizeAuthAlias(obj);
   normalizeTimeoutAlias(obj);
+  normalizeEnabledAlias(obj);
   return obj;
 }
 
@@ -133,6 +166,11 @@ export const ServerConfigSchema = z.preprocess(
       command: z.string().optional(),
       /** Arguments passed to command. */
       args: z.array(z.string()).default([]),
+      /**
+       * Working directory for a stdio server (Pi 1.3.0 `cwd`). A leading `~` expands to the home
+       * directory and a relative path resolves against the session working directory.
+       */
+      cwd: z.string().min(1).optional(),
       /**
        * Extra environment variables passed to the child process as literals.
        * These merge with process.env; project env overrides parent env.
@@ -164,6 +202,11 @@ export const ServerConfigSchema = z.preprocess(
        * "lazy"  — start manually via /mcp:start command.
        */
       lifecycle: z.enum(["eager", "lazy"]).default("lazy"),
+      /**
+       * Pi 1.3.0 switch: `false` keeps the entry configured but out of the eager set (normalized to
+       * `lifecycle: "lazy"`). Default: `true`.
+       */
+      enabled: z.boolean().optional(),
       /** Per-request timeout in ms. Overrides global setting. Default: 30000. */
       requestTimeoutMs: z.number().positive().optional(),
       /**
@@ -188,11 +231,20 @@ export const ServerConfigSchema = z.preprocess(
             message: "OAuth authentication is only supported for 'sse' and 'streamable-http' transports, not 'stdio'",
           });
         }
-      } else if (cfg.url === undefined) {
-        ctx.addIssue({
-          code: "custom",
-          message: `"url" is required for ${cfg.transport} transport`,
-        });
+      } else {
+        if (cfg.url === undefined) {
+          ctx.addIssue({
+            code: "custom",
+            message: `"url" is required for ${cfg.transport} transport`,
+          });
+        }
+        if (cfg.cwd !== undefined) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["cwd"],
+            message: `"cwd" is only supported for 'stdio' transport, not '${cfg.transport}'`,
+          });
+        }
       }
     }),
 );
@@ -242,6 +294,91 @@ const ProjectConfigSchema = z.object({
 });
 type ProjectConfig = z.output<typeof ProjectConfigSchema>;
 
+// ─── Pi 1.3.0 project override entries ────────────────────────────────────────
+
+/**
+ * Keys a Pi 1.3.0 project entry may override on the global entry of the same name (`/mcp` writes
+ * such an entry as soon as a global server is disabled or its exposure is changed for one project).
+ * `exposure` / `toolExposure` are Pi-native tool-exposure settings: they are accepted so a shared
+ * `mcp.json` loads, and ignored because this extension decides tool activation itself. `lifecycle`
+ * is this extension's equivalent of `enabled`.
+ */
+const PROJECT_OVERRIDE_KEYS = ["enabled", "exposure", "toolExposure", "lifecycle"] as const;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A project entry without a transport definition only overrides the global server of that name. */
+function isProjectOverrideEntry(value: unknown): value is Record<string, unknown> {
+  if (!isPlainObject(value)) return false;
+  return (
+    value.command === undefined &&
+    value.url === undefined &&
+    value.type === undefined &&
+    value.transport === undefined
+  );
+}
+
+function invalidProjectConfig(projectPath: string, detail: string): McpError {
+  return new McpError(`Invalid mcp.json at ${projectPath}:\n  ${detail}`, "<config>", "config");
+}
+
+/** Merge a partial project override onto the raw global entry, keeping the global credentials. */
+function mergeProjectOverride(
+  name: string,
+  override: Record<string, unknown>,
+  globalServers: Record<string, unknown>,
+  projectPath: string,
+): Record<string, unknown> {
+  const base = globalServers[name];
+  if (!isPlainObject(base)) {
+    throw invalidProjectConfig(
+      projectPath,
+      `mcpServers.${name}: a project override needs "command" or "url" in this file, or a global server of that name`,
+    );
+  }
+  const unsupported = Object.keys(override).filter(
+    (key) => !(PROJECT_OVERRIDE_KEYS as readonly string[]).includes(key),
+  );
+  if (unsupported.length > 0) {
+    throw invalidProjectConfig(
+      projectPath,
+      `mcpServers.${name}: a project override can only set ${PROJECT_OVERRIDE_KEYS.join(", ")} (found ${unsupported.join(", ")})`,
+    );
+  }
+  const merged: Record<string, unknown> = { ...base };
+  if (override.lifecycle !== undefined && override.enabled === undefined) {
+    delete merged.enabled;
+  }
+  for (const key of PROJECT_OVERRIDE_KEYS) {
+    if (override[key] !== undefined) {
+      merged[key] = override[key];
+    }
+  }
+  return merged;
+}
+
+/**
+ * Resolve Pi 1.3.0 partial project entries (`{ "<server>": { "enabled": false } }`) against the raw
+ * global file *before* validation, so `ProjectConfigSchema` sees a complete entry instead of
+ * failing with `"command" is required for stdio transport` (which tore down every global server on
+ * `session_start`).
+ */
+function applyProjectOverrides(projectRaw: unknown, globalRaw: unknown, projectPath: string): unknown {
+  if (!isPlainObject(projectRaw) || !isPlainObject(projectRaw.mcpServers)) return projectRaw;
+  const globalServers = isPlainObject(globalRaw) && isPlainObject(globalRaw.mcpServers)
+    ? globalRaw.mcpServers
+    : {};
+  const servers: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(projectRaw.mcpServers)) {
+    servers[name] = isProjectOverrideEntry(value)
+      ? mergeProjectOverride(name, value, globalServers, projectPath)
+      : value;
+  }
+  return { ...projectRaw, mcpServers: servers };
+}
+
 // ─── Public Types ─────────────────────────────────────────────────────────────
 
 export type AuthConfig = z.output<typeof AuthConfigSchema>;
@@ -425,7 +562,11 @@ export async function loadConfigWithOrigins(
 
   const projectCfg = projectRaw === undefined
     ? undefined
-    : parseWith(ProjectConfigSchema, projectRaw, projectConfigPath);
+    : parseWith(
+        ProjectConfigSchema,
+        applyProjectOverrides(projectRaw, globalRaw, projectConfigPath),
+        projectConfigPath,
+      );
 
   return {
     config: projectCfg === undefined ? globalCfg : mergeConfigs(globalCfg, projectCfg),

package/src/oauth-provider.ts

@@ -57,6 +57,8 @@ export interface AuthConfig {
    * Pre-registered client_secret.
    */
   clientSecret?: string | undefined;
+  /** `client_name` sent with Dynamic Client Registration. Default: `pi-mcp/<server name>`. */
+  clientName?: string | undefined;
 }
 
 const DEFAULT_CALLBACK_PORT = 19876;
@@ -252,7 +254,7 @@ export class McpOAuthProvider implements OAuthClientProvider {
       redirectUris = [String(this.redirectUrl)];
     }
     return {
-      client_name: `pi-mcp/${this.serverName}`,
+      client_name: this.authConfig.clientName ?? `pi-mcp/${this.serverName}`,
       redirect_uris: redirectUris,
       grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],

package/src/transport-factory.ts

@@ -6,6 +6,8 @@
  * SDK workarounds.
  */
 
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
@@ -67,15 +69,36 @@ function wireStdioStderr(transport: StdioClientTransport, onStderr: (line: strin
   transport.stderr.on("close", flush);
 }
 
+/** Expand a leading `~` / `~/` / `~\` to the home directory, the way Pi resolves a config `cwd`. */
+function expandHome(path: string): string {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/") || path.startsWith("~\\")) return join(homedir(), path.slice(2));
+  return path;
+}
+
+/**
+ * Resolve the working directory for a stdio server: Pi 1.3.0's per-server `cwd` (relative paths
+ * resolve against the session working directory, `~` expands to the home directory), else the
+ * session working directory unchanged.
+ */
+export function resolveStdioCwd(
+  configuredCwd: string | undefined,
+  sessionCwd: string | undefined,
+): string | undefined {
+  if (configuredCwd === undefined) return sessionCwd;
+  return resolve(sessionCwd ?? process.cwd(), expandHome(configuredCwd));
+}
+
 function createStdioTransport(
   serverName: string,
   config: ServerConfig,
-  cwd: string | undefined,
+  sessionCwd: string | undefined,
   onStderr: ((line: string) => void) | undefined,
 ): Transport {
   if (!config.command) {
     throw new McpError("stdio transport requires 'command'", serverName, "config");
   }
+  const cwd = resolveStdioCwd(config.cwd, sessionCwd);
   const transport = new StdioClientTransport({
     command: config.command,
     args: config.args,