pi-mcp-extension 1.10.2 → 1.11.0

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)
 
@@ -182,13 +185,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.0",
   "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}`;
+}