pi-mcp-extension 1.6.0 → 1.7.1

package/README.md

@@ -143,7 +143,7 @@ Config files are loaded from two locations. **Project config overrides global co
 | `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:start` |
+| `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 |
 
@@ -170,7 +170,13 @@ Server-name arguments provide autocomplete suggestions from the configured MCP s
 | `/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 |
 
-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, 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.
+
+### Connection readiness and active tools
+
+`mcp_status` reports `tools.discovered` and `tools.active` for each server. Connection state `ready` means the MCP handshake and discovery completed. It does not mean that another Pi extension has kept every discovered tool active.
+
+`mcp_connect` checks current tool activation before reporting success, including when the server is already connected. If discovered tools are inactive, it reports that condition instead of overriding another extension's tool restrictions. Check the active tool policy or conflicting extension. A reconnect is not a substitute for fixing an extension that removes tools at each user turn.
 
 ## How It Works
 
@@ -198,7 +204,7 @@ Repeated credential resets share one pending authorization; stop or shutdown can
 ```
 
 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:start`
+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)
 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.6.0",
+  "version": "1.7.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

@@ -2,8 +2,9 @@
  * 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
+ *   1. <cwd>/.pi/mcp.json      — project-level config
+ *   2. <agent dir>/mcp.json    — global config; the agent dir is what Pi itself uses:
+ *      $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.
@@ -118,6 +119,25 @@ const McpConfigSchema = z.object({
   mcpServers: z.record(ServerConfigSchema).default({}),
 });
 
+/**
+ * Project-level file: `settings` keys are optional and carry NO defaults, so a project file
+ * only overrides what it actually states. (Parsing it with SettingsSchema filled in the
+ * defaults — e.g. toolPrefix "mcp" — and the merge then overwrote the global settings.)
+ */
+const ProjectSettingsSchema = z.object({
+  toolPrefix: z
+    .string()
+    .regex(/^[a-zA-Z0-9_]+$/, "toolPrefix must match [a-zA-Z0-9_]")
+    .optional(),
+  requestTimeoutMs: z.number().positive().optional(),
+  maxRetries: z.number().int().min(0).max(10).optional(),
+});
+const ProjectConfigSchema = z.object({
+  settings: ProjectSettingsSchema.default({}),
+  mcpServers: z.record(ServerConfigSchema).default({}),
+});
+type ProjectConfig = z.output<typeof ProjectConfigSchema>;
+
 // ─── Public Types ─────────────────────────────────────────────────────────────
 
 export type AuthConfig = z.output<typeof AuthConfigSchema>;
@@ -139,7 +159,15 @@ async function readJsonFile(path: string): Promise<unknown | null> {
 }
 
 function parseConfig(raw: unknown, sourcePath: string): McpConfig {
-  const result = McpConfigSchema.safeParse(raw);
+  return parseWith(McpConfigSchema, raw, sourcePath);
+}
+
+function parseWith<S extends z.ZodTypeAny>(
+  schema: S,
+  raw: unknown,
+  sourcePath: string,
+): z.output<S> {
+  const result = schema.safeParse(raw);
   if (!result.success) {
     const issues = result.error.issues
       .map((i) => `  ${i.path.join(".")}: ${i.message}`)
@@ -155,22 +183,41 @@ function parseConfig(raw: unknown, sourcePath: string): McpConfig {
 
 function mergeConfigs(
   globalCfg: McpConfig,
-  projectCfg: McpConfig,
+  projectCfg: ProjectConfig,
 ): McpConfig {
+  // Only the settings the project file states may override the global ones.
+  const stated = Object.fromEntries(
+    Object.entries(projectCfg.settings).filter(([, v]) => v !== undefined),
+  ) as Partial<Settings>;
   return {
     // Shallow spread: project settings override global settings per key
-    settings: { ...globalCfg.settings, ...projectCfg.settings },
+    settings: { ...globalCfg.settings, ...stated },
     // 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.
+ * Pi's agent directory, resolved the way Pi resolves it (`getAgentDir()` in
+ * @mariozechner/pi-coding-agent): $PI_CODING_AGENT_DIR when set (tilde expanded), else
+ * ~/.pi/agent. Pi profiles and alternative agent dirs only work through that variable.
+ */
+export function agentDir(env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = env.PI_CODING_AGENT_DIR;
+  if (fromEnv && fromEnv.length > 0) {
+    if (fromEnv === "~") return homedir();
+    if (fromEnv.startsWith("~/")) return join(homedir(), fromEnv.slice(2));
+    return fromEnv;
+  }
+  return join(homedir(), ".pi", "agent");
+}
+
+/**
+ * Load and merge global (<agent dir>/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, globalPath = join(homedir(), ".pi", "agent", "mcp.json")): Promise<McpConfig> {
+export async function loadConfig(cwd: string, globalPath = join(agentDir(), "mcp.json")): Promise<McpConfig> {
   const projectPath = join(cwd, ".pi", "mcp.json");
 
   const [globalRaw, projectRaw] = await Promise.all([
@@ -189,6 +236,6 @@ export async function loadConfig(cwd: string, globalPath = join(homedir(), ".pi"
 
   if (projectRaw === null) return globalCfg;
 
-  const projectCfg = parseConfig(projectRaw, projectPath);
+  const projectCfg = parseWith(ProjectConfigSchema, projectRaw, projectPath);
   return mergeConfigs(globalCfg, projectCfg);
 }

package/src/index.ts

@@ -10,7 +10,8 @@
 import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext, ExtensionUIContext } from "@mariozechner/pi-coding-agent";
 import { loadConfig, type McpConfig } from "./config.js";
 import { ServerManager } from "./server-manager.js";
-import { AuthRequiredError } from "./oauth-provider.js";
+import { AuthLockError, AuthRequiredError } from "./oauth-provider.js";
+import * as Type from "typebox";
 import { ToolBridge } from "./tool-bridge.js";
 import { McpError } from "./errors.js";
 import { spawn } from "node:child_process";
@@ -217,7 +218,7 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
   // ── 2. Initialize bridge components ──────────────────────────────────────
   const manager = new ServerManager(config, undefined, paths.authStorageDir);
   const bridge = new ToolBridge(config.settings, pi);
-  const connectAttempts = new Map<string, { promise: Promise<void>; controller: AbortController; reset: boolean }>();
+  const connectAttempts = new Map<string, { promise: Promise<void>; controller: AbortController; reset: boolean; waiters: number }>();
   let authQueue: Promise<void> = Promise.resolve();
 
   manager.setToolRefreshCallback(async (serverName, client) => {
@@ -534,22 +535,58 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
     if (reset && !server.config.auth) throw new McpError(`Server "${serverName}" has no OAuth configuration`, serverName, "config");
     if (reset && !ctx.hasUI) throw new AuthRequiredError(serverName);
 
+    const waitForAttempt = async (entry: { promise: Promise<void>; controller: AbortController; reset: boolean; waiters: number }): Promise<void> => {
+      entry.waiters++;
+      let released = false;
+      const releaseWaiter = () => {
+        if (!released) {
+          released = true;
+          entry.waiters--;
+        }
+      };
+      if (!signal) {
+        try {
+          return await entry.promise;
+        } finally {
+          releaseWaiter();
+        }
+      }
+      let stopPromise: Promise<unknown> | undefined;
+      let onAbort!: () => void;
+      const aborted = new Promise<never>((_resolve, reject) => {
+        onAbort = () => {
+          releaseWaiter();
+          if (entry.waiters === 0) {
+            entry.controller.abort();
+            stopPromise = manager.stopServer(serverName);
+            void stopPromise.finally(() => reject(new AuthCancelledError(serverName)));
+          } else {
+            reject(new AuthCancelledError(serverName));
+          }
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+      });
+      try {
+        return await Promise.race([entry.promise, aborted]);
+      } finally {
+        signal.removeEventListener("abort", onAbort);
+        releaseWaiter();
+        await stopPromise;
+      }
+    };
+
     const existing = connectAttempts.get(serverName);
     // All requests join an in-flight reset. A reset supersedes a normal connect.
     if (existing && (!reset || existing.reset)) {
-      const abort = () => { existing.controller.abort(); void manager.stopServer(serverName); };
-      signal?.addEventListener("abort", abort, { once: true });
-      try { return await existing.promise; }
-      finally { signal?.removeEventListener("abort", abort); }
+      return await waitForAttempt(existing);
     }
 
     const controller = new AbortController();
-    const abort = () => { controller.abort(); void manager.stopServer(serverName); };
-    signal?.addEventListener("abort", abort, { once: true });
     if (existing) {
       existing.controller.abort();
       void manager.stopServer(serverName);
     }
+    let entry!: { promise: Promise<void>; controller: AbortController; reset: boolean; waiters: number };
     const task = (async () => {
       // Wait for a superseded connect to release its callback listener and auth lock.
       if (existing) await existing.promise.catch(() => {});
@@ -584,15 +621,70 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
     })().catch((err: unknown) => {
       if (controller.signal.aborted) throw new AuthCancelledError(serverName);
       throw err;
+    }).finally(() => {
+      if (connectAttempts.get(serverName) === entry) connectAttempts.delete(serverName);
     });
-    const entry = { promise: task, controller, reset };
+    void task.catch(() => {});
+    entry = { promise: task, controller, reset, waiters: 0 };
     connectAttempts.set(serverName, entry);
-    try { await task; } finally {
-      signal?.removeEventListener("abort", abort);
-      if (connectAttempts.get(serverName) === entry) connectAttempts.delete(serverName);
-    }
+    return await waitForAttempt(entry);
   }
 
+  pi.registerTool({
+    name: "mcp_status",
+    label: "MCP status",
+    description: "List configured MCP servers, lifecycle, connection and OAuth state. Use mcp_connect to connect one server.",
+    parameters: Type.Object({}),
+    async execute() {
+      const rows = await Promise.all(manager.getAllServers().map(async (server) => {
+        const auth = server.config.auth ? await manager.getServerAuthStatus(server.name) : null;
+        return {
+          name: server.name, lifecycle: server.config.lifecycle, state: server.state,
+          tools: bridge.getToolActivity(server.name),
+          auth: server.config.auth ? auth?.hasTokens ? "credentials stored" : "authorization may be required" : "not configured",
+          error: server.lastError
+            ? server.lastError instanceof AuthRequiredError
+              ? "Authorization required: use mcp_connect in an interactive Pi session"
+              : `Connection ${server.lastError instanceof McpError ? server.lastError.code : "failed"}; use mcp_connect to retry`
+            : undefined,
+        };
+      }));
+      return { content: [{ type: "text", text: JSON.stringify(rows) }], details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "mcp_connect",
+    label: "Connect MCP server",
+    description: "Connect one named configured MCP server and activate its tools. May request interactive OAuth authorization.",
+    parameters: Type.Object({ name: Type.String({ description: "Exact configured MCP server name" }) }),
+    async execute(_id, { name }, signal, _update, ctx) {
+      try {
+        await connectRequested(name, ctx, signal);
+      } catch (err) {
+        const message = signal?.aborted || err instanceof AuthCancelledError
+          ? "MCP connection cancelled. Retry when ready."
+          : !manager.getServer(name)
+            ? "Unknown MCP server name. Use mcp_status to list configured servers."
+            : err instanceof AuthLockError
+              ? "Another Pi process is authorizing this server. Retry after it finishes or check for a stale auth lock."
+              : err instanceof AuthRequiredError
+                ? ctx.hasUI
+                  ? "MCP authorization required. Retry with mcp_connect or /mcp:auth."
+                  : "MCP authorization requires an interactive Pi session."
+                : err instanceof McpError && err.code === "protocol"
+                  ? "MCP tool discovery failed. Check the server and retry."
+                  : "MCP connection failed. Check the server configuration and retry.";
+        throw new Error(message);
+      }
+      const activity = bridge.getToolActivity(name);
+      if (activity.active !== activity.discovered) {
+        throw new Error("MCP server connected, but some discovered tools are inactive. Check Pi tool restrictions or extension conflicts; mcp_status reports discovered and active counts.");
+      }
+      return { content: [{ type: "text", text: `MCP server ${name} ready; tools discovered and active.` }], details: {} };
+    },
+  });
+
   pi.registerCommand("mcp:auth", {
     description: "Connect with OAuth; use /mcp:auth <name> --reset to discard stored credentials.",
     handler: async (args, ctx) => {

package/src/oauth-provider.ts

@@ -15,8 +15,8 @@ import type { OAuthClientProvider, OAuthDiscoveryState } from "@modelcontextprot
 import type { OAuthClientMetadata, OAuthClientInformationMixed, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
 import { readFile, writeFile, mkdir, unlink, chmod, open, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { createHash } from "node:crypto";
+import { agentDir } from "./config.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -84,7 +84,7 @@ interface StoredState {
 // ─── File helpers ─────────────────────────────────────────────────────────────
 
 function authDir(storageDir?: string): string {
-  return storageDir ?? join(homedir(), ".pi", "agent", "mcp-auth");
+  return storageDir ?? join(agentDir(), "mcp-auth");
 }
 
 function statePath(serverName: string, storageDir?: string): string {

package/src/tool-bridge.ts

@@ -380,6 +380,13 @@ export class ToolBridge {
     this._activateServerTools(serverName);
   }
 
+  /** Report discovery separately from the tools currently exposed by Pi. */
+  getToolActivity(serverName: string): { discovered: number; active: number } {
+    const names = this.serverToolNames.get(serverName) ?? new Set<string>();
+    const active = new Set(this.pi.getActiveTools());
+    return { discovered: names.size, active: [...names].filter((name) => active.has(name)).length };
+  }
+
   /** Deactivate all Pi tools belonging to a server (called on disconnect). */
   deactivateServer(serverName: string): void {
     this._deactivateServerTools(serverName);