pi-mcp-extension 1.10.2 → 1.11.1

package/README.md

@@ -2,6 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/pi-mcp-extension.svg)](https://www.npmjs.com/package/pi-mcp-extension)
 [![license](https://img.shields.io/npm/l/pi-mcp-extension.svg)](https://github.com/irahardianto/pi-mcp-extension/blob/main/LICENSE)
+[![CI](https://github.com/irahardianto/pi-mcp-extension/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/irahardianto/pi-mcp-extension/actions/workflows/ci.yml)
+[![Code Coverage](https://qlty.sh/gh/irahardianto/projects/pi-mcp-extension/coverage.svg)](https://qlty.sh/gh/irahardianto/projects/pi-mcp-extension)
+[![Maintainability](https://qlty.sh/gh/irahardianto/projects/pi-mcp-extension/maintainability.svg)](https://qlty.sh/gh/irahardianto/projects/pi-mcp-extension)<br>
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/irahardianto/pi-mcp-extension/badge)](https://scorecard.dev/viewer/?uri=github.com/irahardianto/pi-mcp-extension)
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15659/badge)](https://www.bestpractices.dev/projects/15659)
 
@@ -148,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.
@@ -173,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
@@ -182,13 +202,39 @@ Server-name arguments provide autocomplete suggestions from the configured MCP s
 | Command | Description |
 |---|---|
 | `/mcp` | Show status summary of all configured servers |
-| `/mcp <name>` | Show detailed status and stderr log for a specific server |
+| `/mcp <name>` | Show detailed status for one server: config source, transport/lifecycle, tool activation, OAuth credential status, failure hint, and stderr log |
 | `/mcp:start <name>` | Connect a server and wait for tool discovery |
 | `/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 and client registration; request browser authorization only if needed |
 | `/mcp:auth <name> --reset` | Discard stored tokens and client registration (re-running Dynamic Client Registration) 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, 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.
+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, config source, 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.
+
+### Inspecting one server (`/mcp <name>`)
+
+`/mcp <name>` answers "why is this server in this state?" without leaving Pi:
+
+```text
+Server: supabase
+State:  stopped
+Retries: 5
+Transport: streamable-http
+Lifecycle: lazy
+Source: global
+Tools: 0/0 active
+OAuth: credentials stored
+Last error: Connection timed out after 30000ms
+Hint: run with PI_MCP_DEBUG=1 pi to log redacted diagnostics, or report server issues at https://github.com/irahardianto/pi-mcp-extension/issues
+
+Recent output:
+(no stderr output from supabase)
+```
+
+- `Source` is the entry that won: `global` (`<agent dir>/mcp.json`), `project` (`<cwd>/.pi/mcp.json`), or `extension` (`pi.registerMcpServer()`). `mcp_status` reports the same value as `source` on each row.
+- When the project is untrusted, `Source` never says `project` and a `Project config: not loaded (<path>)` line explains why `mcp.json` in the workspace is not in effect.
+- `Tools` compares discovered tools with the ones Pi has active; a server can be `ready` with `0/N active` when another extension restricts tools.
+- `OAuth` appears only for servers with an `auth` config: `credentials stored`, `authorization may be required`, or `corrupt state file backed up (re-auth required)` (the corrupt file is backed up and the view still renders).
+- A failed server adds one `Hint:` line: `/mcp:auth <name>` (plus `--reset` when stored credentials expired) for a missing/expired authorization, waiting for another Pi process holding the auth lock, or `PI_MCP_DEBUG=1 pi` plus the issue tracker for a connection failure.
 
 ### OAuth startup, headless/SSH, and concurrency behavior
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.10.2",
+  "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": [
@@ -33,7 +33,7 @@
     ]
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "zod": "^4.6.7"
   },
   "peerDependencies": {
@@ -41,20 +41,23 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
+  "overrides": {
+    "undici": "^8.12.3"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.6.5",
     "eslint": "^10.13.0",
     "fast-check": "^4.10.2",
     "tsx": "^4.19.4",
-    "typescript": "^5.7.0",
-    "typescript-eslint": "^8.71.2"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.0"
   },
   "scripts": {
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx/esm --test ./tests/*.test.ts",
-    "test:coverage": "node --import tsx/esm --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-lines=95 --test-coverage-branches=85 --test-coverage-functions=83 ./tests/*.test.ts",
+    "test:coverage": "node --import tsx/esm --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=lcov.info --test-coverage-include='src/**' --test-coverage-lines=95 --test-coverage-branches=85 --test-coverage-functions=83 ./tests/*.test.ts",
     "test:integration": "node --import tsx/esm --test ./tests/server-manager.test.ts"
   }
 }

package/src/auth-lock-policy.ts

@@ -0,0 +1,63 @@
+/**
+ * Pure lock-record and staleness policy for pi-mcp's cross-process OAuth
+ * authorization lock. No filesystem, clock, or process access.
+ */
+
+import { z } from "zod";
+
+// ─── Constants & Schema ───────────────────────────────────────────────────────
+
+export const HEARTBEAT_MS = 30_000;
+export const STALE_MS = 90_000; // 3 × 30s heartbeat
+
+export const LockRecordSchema = z.object({
+  v: z.literal(1),
+  pid: z.number().int().positive(),
+  hostname: z.string().min(1),
+  nonce: z.string().min(1),
+  createdAt: z.number(),
+});
+
+export type LockRecord = z.output<typeof LockRecordSchema>;
+
+// ─── Pure Staleness Policy ────────────────────────────────────────────────────
+
+export function parseLockRecord(raw: string): LockRecord | null {
+  if (!raw) return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    const result = LockRecordSchema.safeParse(parsed);
+    return result.success ? result.data : null;
+  } catch {
+    // WHY: JSON.parse on a string throws SyntaxError if the lock file is corrupt or
+    // partially written. LockRecordSchema.safeParse does not throw. Unparseable lock
+    // files map to null so isLockStale() can fall back to mtime-based staleness.
+    return null;
+  }
+}
+
+/**
+ * Pure policy determining whether an existing lock file is stale and safe to reclaim.
+ */
+export function isLockStale(
+  record: LockRecord | null,
+  mtimeMs: number,
+  now: number,
+  self: { hostname: string; isPidAlive: (pid: number) => boolean },
+): boolean {
+  if (now - mtimeMs > STALE_MS) {
+    return true;
+  }
+  if (record === null) {
+    return false;
+  }
+  if (record.hostname === self.hostname && !self.isPidAlive(record.pid)) {
+    return true;
+  }
+  return false;
+}
+
+export function formatHolderDetails(record: LockRecord | null): string | undefined {
+  if (!record) return undefined;
+  return `pid ${record.pid} on ${record.hostname}`;
+}