npm - @phi-code-admin/phi-code - Versions diffs - 0.82.3 → 0.83.0 - Mend

@phi-code-admin/phi-code 0.82.3 → 0.83.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/CHANGELOG.md +20 -0
package/docs/usage.md +1 -1
package/extensions/phi/mcp/LICENSE +21 -0
package/extensions/phi/mcp/callback-server.ts +263 -0
package/extensions/phi/mcp/config.ts +195 -0
package/extensions/phi/mcp/errors.ts +35 -0
package/extensions/phi/mcp/index.ts +376 -0
package/extensions/phi/mcp/oauth-provider.ts +367 -0
package/extensions/phi/mcp/server-manager.ts +464 -0
package/extensions/phi/mcp/tool-bridge.ts +494 -0
package/package.json +4 -2

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,25 @@
 # Changelog
+## [0.83.0] - 2026-06-14
+### Added
+- **Built-in MCP (Model Context Protocol) client.** phi now ships a bundled MCP
+  extension (`extensions/phi/mcp/`), on by default with no install: connect to any
+  MCP server (Supabase, Playwright, Context7, filesystem, databases, and more)
+  over `stdio`, `streamable-http`, or `sse`, including OAuth for remote servers.
+  Each server's tools are bridged into the agent as `<prefix>_<server>_<tool>`.
+  New commands: `/mcp`, `/mcp <name>`, `/mcp:start`, `/mcp:stop`, `/mcp:auth`.
+  Configure servers in `~/.phi/agent/mcp.json` (global) or
+  `<project>/.phi/mcp.json` (project). Vendored from the MIT-licensed
+  `pi-mcp-extension` by irahardianto and adapted for phi: imports resolve via
+  `phi-code`, config uses the phi `configDir` (`.phi`), and it ships bundled
+  instead of requiring `phi install`.
+- Dependencies: `@modelcontextprotocol/sdk` and `zod`, used by the bundled MCP
+  extension.
 ## [0.82.3] - 2026-06-14
 ### Added

package/docs/usage.md CHANGED Viewed

@@ -272,6 +272,6 @@ pi --tools read,grep,find,ls -p "Review the code"
 Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
-It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+It bundles MCP support (see the MCP extension) and sub-agents. It does not include permission popups, to-dos, or background bash by default: you can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
 For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).

package/extensions/phi/mcp/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 irahardianto
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/phi/mcp/callback-server.ts ADDED Viewed

@@ -0,0 +1,263 @@
+/**
+ * MCP OAuth Callback Server
+ *
+ * Simple HTTP server that handles OAuth callbacks from the authorization server.
+ * Uses Node.js http module for compatibility with no external dependencies.
+ */
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "http";
+import { URL } from "url";
+interface PendingAuth {
+  resolve: (code: string) => void;
+  reject: (error: Error) => void;
+  timeout: ReturnType<typeof setTimeout>;
+}
+let server: Server | null = null;
+let actualServerPort: number | null = null;
+const pendingAuths = new Map<string, PendingAuth>();
+const DEFAULT_PORT = 19876;
+const CALLBACK_PATH = "/callback";
+const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const HTML_SUCCESS = `<!DOCTYPE html>
+<html><head><title>Pi - Authorization Successful</title>
+<style>body{font-family:system-ui,-apple-system,sans-serif;display:flex;justify-content:center;align-items:center;height:100vh;margin:0;background:#1a1a2e;color:#eee}
+.container{text-align:center;padding:2rem}h1{color:#4ade80;margin-bottom:1rem}p{color:#aaa}</style>
+</head><body>
+<div class="container"><h1>✓ Authorization Successful</h1><p>You can close this window and return to Pi.</p></div>
+<script>setTimeout(()=>window.close(),2000)</script>
+</body></html>`;
+const HTML_ERROR = (error: string) => `<!DOCTYPE html>
+<html><head><title>Pi - Authorization Failed</title>
+<style>body{font-family:system-ui,-apple-system,sans-serif;display:flex;justify-content:center;align-items:center;height:100vh;margin:0;background:#1a1a2e;color:#eee}
+.container{text-align:center;padding:2rem}h1{color:#f87171;margin-bottom:1rem}p{color:#aaa}
+.error{color:#fca5a5;font-family:monospace;margin-top:1rem;padding:1rem;background:rgba(248,113,113,0.1);border-radius:.5rem;white-space:pre-wrap;word-break:break-word}</style>
+</head><body>
+<div class="container"><h1>✗ Authorization Failed</h1><p>An error occurred during authorization.</p><div class="error">${escapeHtml(error)}</div></div>
+</body></html>`;
+/**
+ * Escape HTML entities to prevent XSS attacks.
+ */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+/**
+ * Handle incoming HTTP requests to the callback server.
+ */
+function handleRequest(req: IncomingMessage, res: ServerResponse): void {
+  const url = new URL(req.url || "/", `http://${req.headers.host}`);
+  // Only handle the callback path
+  if (url.pathname !== CALLBACK_PATH) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not found");
+    return;
+  }
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+  const error = url.searchParams.get("error");
+  const errorDescription = url.searchParams.get("error_description");
+  // Enforce state parameter presence for CSRF protection
+  if (!state) {
+    const errorMsg = "Missing required state parameter - potential CSRF attack";
+    res.writeHead(400, { "Content-Type": "text/html" });
+    res.end(HTML_ERROR(errorMsg));
+    return;
+  }
+  // Handle OAuth errors
+  if (error) {
+    const errorMsg = errorDescription || error;
+    res.writeHead(200, { "Content-Type": "text/html" });
+    res.end(HTML_ERROR(errorMsg));
+    if (pendingAuths.has(state)) {
+      const pending = pendingAuths.get(state)!;
+      clearTimeout(pending.timeout);
+      pendingAuths.delete(state);
+      setTimeout(() => pending.reject(new Error(errorMsg)), 0);
+    }
+    return;
+  }
+  // Require authorization code
+  if (!code) {
+    res.writeHead(400, { "Content-Type": "text/html" });
+    res.end(HTML_ERROR("No authorization code provided"));
+    return;
+  }
+  // Validate state parameter
+  if (!pendingAuths.has(state)) {
+    const errorMsg = "Invalid or expired state parameter - potential CSRF attack";
+    res.writeHead(400, { "Content-Type": "text/html" });
+    res.end(HTML_ERROR(errorMsg));
+    return;
+  }
+  const pending = pendingAuths.get(state)!;
+  // Clear timeout and resolve the pending promise
+  clearTimeout(pending.timeout);
+  pendingAuths.delete(state);
+  pending.resolve(code);
+  res.writeHead(200, { "Content-Type": "text/html" });
+  res.end(HTML_SUCCESS);
+}
+/**
+ * Ensure the callback server is running.
+ * Scans forward for an available local port if the preferred port is busy.
+ *
+ * @param preferredPort - The preferred port to use (default: 19876)
+ * @returns The actual port the server is listening on
+ */
+export async function ensureCallbackServer(preferredPort: number = DEFAULT_PORT): Promise<number> {
+  if (server) {
+    // Already running, return the tracked actual port
+    if (actualServerPort !== null) {
+      return actualServerPort;
+    }
+    // Fallback: try to get the port from the server
+    const address = server.address();
+    if (address && typeof address === "object" && "port" in address) {
+      actualServerPort = address.port;
+      return address.port;
+    }
+    // If we still can't determine the port, return the preferred port
+    // (this shouldn't happen in practice)
+    return preferredPort;
+  }
+  const maxAttempts = 25; // Try up to 25 ports
+  for (let offset = 0; offset < maxAttempts; offset++) {
+    const candidatePort = preferredPort + offset;
+    const candidateServer = createServer(handleRequest);
+    try {
+      await new Promise<void>((resolve, reject) => {
+        candidateServer.once("error", (err: any) => {
+          reject(err);
+        });
+        // Bind to 127.0.0.1 explicitly (IPv4) to avoid issues with IPv6
+        candidateServer.listen(candidatePort, "127.0.0.1", () => {
+          resolve();
+        });
+      });
+      server = candidateServer;
+      actualServerPort = candidatePort;
+      server.unref(); // Don't block process exit
+      return candidatePort;
+    } catch (error) {
+      const nodeError = error as NodeJS.ErrnoException;
+      await new Promise<void>((resolve) => {
+        candidateServer.close(() => resolve());
+      });
+      // If not EADDRINUSE, rethrow
+      if (nodeError.code !== "EADDRINUSE") {
+        throw error;
+      }
+    }
+  }
+  throw new Error(
+    `OAuth callback port ${preferredPort} is already in use and no free port was found in range ${preferredPort}-${preferredPort + maxAttempts - 1}`
+  );
+}
+/**
+ * Wait for a callback with the given OAuth state.
+ * Returns a promise that resolves with the authorization code.
+ *
+ * @param oauthState - The OAuth state parameter to wait for
+ * @param timeoutMs - Timeout in milliseconds (default: 5 minutes)
+ * @returns Promise that resolves with the authorization code
+ */
+export function waitForCallback(
+  oauthState: string,
+  timeoutMs: number = TIMEOUT_MS
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      if (pendingAuths.has(oauthState)) {
+        pendingAuths.delete(oauthState);
+        reject(new Error("OAuth callback timeout - authorization took too long"));
+      }
+    }, timeoutMs);
+    pendingAuths.set(oauthState, { resolve, reject, timeout });
+  });
+}
+/**
+ * Cancel a pending authorization by state.
+ *
+ * @param oauthState - The OAuth state to cancel
+ */
+export function cancelCallback(oauthState: string): void {
+  const pending = pendingAuths.get(oauthState);
+  if (pending) {
+    clearTimeout(pending.timeout);
+    pendingAuths.delete(oauthState);
+    pending.reject(new Error("Authorization cancelled"));
+  }
+}
+/**
+ * Stop the callback server and reject all pending authorizations.
+ */
+export async function stopCallbackServer(): Promise<void> {
+  if (server) {
+    await new Promise<void>((resolve) => {
+      server!.close(() => {
+        resolve();
+      });
+    });
+    server = null;
+    actualServerPort = null;
+  }
+  // Reject all pending auths (defer to allow any pending operations to complete)
+  const pendingList = Array.from(pendingAuths.entries());
+  pendingAuths.clear();
+  setTimeout(() => {
+    for (const [, pending] of pendingList) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("OAuth callback server stopped"));
+    }
+  }, 0);
+}
+/**
+ * Check if the callback server is running.
+ */
+export function isCallbackServerRunning(): boolean {
+  return server !== null;
+}
+/**
+ * Get the number of pending authorizations.
+ */
+export function getPendingAuthCount(): number {
+  return pendingAuths.size;
+}
+// Export constants for testing/config
+export { DEFAULT_PORT, CALLBACK_PATH, TIMEOUT_MS };

package/extensions/phi/mcp/config.ts ADDED Viewed

@@ -0,0 +1,195 @@
+/**
+ * Configuration loading, validation, and merging for pi-mcp.
+ *
+ * Config file locations (Pi-native convention, highest priority first):
+ *   1. <cwd>/.phi/mcp.json   — project-level config
+ *   2. ~/.phi/agent/mcp.json — global config
+ *
+ * Project servers/settings override global servers/settings per-key (shallow merge).
+ * No deep merge, no env var interpolation — WYSIWYG config.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "phi-code";
+import { z } from "zod";
+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 ServerConfigSchema = z
+  .object({
+    /** Executable to spawn (e.g. "npx", "node", "uvx"). Required for stdio. */
+    command: z.string().optional(),
+    /** Arguments passed to command. */
+    args: z.array(z.string()).default([]),
+    /**
+     * Extra environment variables passed to the child process as literals.
+     * These merge with process.env; project env overrides parent env.
+     * No ${VAR} interpolation — set vars in your shell environment instead.
+     */
+    env: z.record(z.string()).optional(),
+    /** Transport protocol. Default: "stdio". */
+    transport: z.enum(["stdio", "streamable-http", "sse"]).default("stdio"),
+    /**
+     * URL for streamable-http or sse transports.
+     * Must be a valid URL (e.g. "https://my-mcp-server.example.com/mcp").
+     */
+    url: z.string().url().optional(),
+    /**
+     * Static HTTP headers to include with every request (streamable-http / sse only).
+     * Useful for API-key-based auth (e.g. { "Authorization": "Bearer <key>" }).
+     * For OAuth2, use the "auth" field instead.
+     */
+    headers: z.record(z.string()).optional(),
+    /**
+     * OAuth2 configuration for servers that require authorization.
+     * When set, the transport will use the SDK's OAuth flow (discovery,
+     * dynamic client registration, PKCE, token refresh).
+     * Only applies to streamable-http and sse transports.
+     */
+    auth: AuthConfigSchema.optional(),
+    /**
+     * "eager" — start at session_start.
+     * "lazy"  — start manually via /mcp:start command.
+     */
+    lifecycle: z.enum(["eager", "lazy"]).default("lazy"),
+    /** Per-request timeout in ms. Overrides global setting. Default: 30000. */
+    requestTimeoutMs: z.number().positive().optional(),
+    /**
+     * Opt-in heartbeat interval (ping) in ms.
+     * Only useful for long-lived connections where you want proactive liveness checks.
+     * Default: disabled.
+     */
+    healthCheckIntervalMs: z.number().positive().optional(),
+  })
+  .refine(
+    (cfg) => {
+      if (cfg.transport === "stdio") return cfg.command !== undefined;
+      return cfg.url !== undefined;
+    },
+    (cfg) => ({
+      message:
+        cfg.transport === "stdio"
+          ? `"command" is required for stdio transport`
+          : `"url" is required for ${cfg.transport} transport`,
+    }),
+  );
+const SettingsSchema = z.object({
+  /**
+   * Prefix used in Pi tool names: <prefix>_<server>_<tool>.
+   * Must match [a-zA-Z0-9_]. Default: "mcp".
+   */
+  toolPrefix: z
+    .string()
+    .regex(/^[a-zA-Z0-9_]+$/, "toolPrefix must match [a-zA-Z0-9_]")
+    .default("mcp"),
+  /** Default per-request timeout in ms for all servers. Default: 30000. */
+  requestTimeoutMs: z.number().positive().default(30000),
+  /** Maximum retry attempts when a server fails to connect. Default: 5. */
+  maxRetries: z.number().int().min(0).max(10).default(5),
+});
+const McpConfigSchema = z.object({
+  settings: SettingsSchema.default({}),
+  mcpServers: z.record(ServerConfigSchema).default({}),
+});
+// ─── Public Types ─────────────────────────────────────────────────────────────
+export type AuthConfig = z.output<typeof AuthConfigSchema>;
+export type ServerConfig = z.output<typeof ServerConfigSchema>;
+export type Settings = z.output<typeof SettingsSchema>;
+export type McpConfig = z.output<typeof McpConfigSchema>;
+// ─── Loader ───────────────────────────────────────────────────────────────────
+async function readJsonFile(path: string): Promise<unknown | null> {
+  try {
+    const text = await readFile(path, "utf8");
+    return JSON.parse(text) as unknown;
+  } catch (err) {
+    // ENOENT → file doesn't exist, silently skip
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+function parseConfig(raw: unknown, sourcePath: string): McpConfig {
+  const result = McpConfigSchema.safeParse(raw);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  ${i.path.join(".")}: ${i.message}`)
+      .join("\n");
+    throw new McpError(
+      `Invalid mcp.json at ${sourcePath}:\n${issues}`,
+      "<config>",
+      "config",
+    );
+  }
+  return result.data;
+}
+function mergeConfigs(
+  globalCfg: McpConfig,
+  projectCfg: McpConfig,
+): McpConfig {
+  return {
+    // Shallow spread: project settings override global settings per key
+    settings: { ...globalCfg.settings, ...projectCfg.settings },
+    // Per-server override: project server entry completely replaces global entry with same name
+    mcpServers: { ...globalCfg.mcpServers, ...projectCfg.mcpServers },
+  };
+}
+/**
+ * Load and merge global (~/.phi/agent/mcp.json) and project (<cwd>/.phi/mcp.json) configs.
+ * Project config takes precedence over global config.
+ * Returns a fully validated, merged config.
+ */
+export async function loadConfig(cwd: string): Promise<McpConfig> {
+  const globalPath = join(getAgentDir(), "mcp.json");
+  const projectPath = join(cwd, ".phi", "mcp.json");
+  const [globalRaw, projectRaw] = await Promise.all([
+    readJsonFile(globalPath),
+    readJsonFile(projectPath),
+  ]);
+  // If neither file exists, return an empty valid config
+  if (globalRaw === null && projectRaw === null) {
+    return McpConfigSchema.parse({});
+  }
+  const globalCfg = globalRaw !== null
+    ? parseConfig(globalRaw, globalPath)
+    : McpConfigSchema.parse({});
+  if (projectRaw === null) return globalCfg;
+  const projectCfg = parseConfig(projectRaw, projectPath);
+  return mergeConfigs(globalCfg, projectCfg);
+}

package/extensions/phi/mcp/errors.ts ADDED Viewed

@@ -0,0 +1,35 @@
+/**
+ * Single error class for all MCP-related failures.
+ * `code` field enables programmatic discrimination without needing
+ * instanceof checks against a hierarchy of classes.
+ */
+export type McpErrorCode =
+  | "config"      // Configuration loading or validation failed
+  | "connection"  // Transport/connection failed
+  | "protocol"    // JSON-RPC protocol violation (server error response, timeout, etc.)
+  | "tool";       // Tool execution error (isError: true from server)
+export class McpError extends Error {
+  public readonly server: string;
+  public readonly code: McpErrorCode;
+  public readonly cause: unknown;
+  constructor(
+    message: string,
+    server: string,
+    code: McpErrorCode,
+    cause?: unknown,
+  ) {
+    super(message);
+    this.name = "McpError";
+    this.server = server;
+    this.code = code;
+    this.cause = cause;
+  }
+  /** Short user-facing message suitable for ctx.ui.notify() */
+  get userMessage(): string {
+    return `[${this.server}] ${this.message}`;
+  }
+}