pi-mcp-adapter 2.5.1 → 2.5.3

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.3] - 2026-05-01
+
+### Added
+- Added environment variable and `~` expansion for stdio server `cwd` values.
+
+## [2.5.2] - 2026-04-29
+
+### Fixed
+- Respected `PI_CODING_AGENT_DIR` for Pi-owned MCP config and state files, including metadata cache, npx cache, onboarding state, OAuth credentials, and `pi-mcp-adapter init` writes.
+
 ## [2.5.1] - 2026-04-24
 
 ### Fixed

package/README.md

@@ -34,7 +34,7 @@ The adapter reads standard MCP files automatically. No extra setup needed if you
 | Host-specific configs (Cursor, Claude Code, Codex, etc.) but no standard MCP files | Run `/mcp setup` to adopt those host configs into Pi. The setup flow shows exactly what it found, lets you pick which ones to import, and previews the exact file changes before writing. |
 | Nothing configured yet | Run `/mcp setup` to scaffold a minimal `.mcp.json`, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. |
 
-If you prefer the terminal, you can also run `pi-mcp-adapter init` after install to scan for host-specific configs and add missing compatibility imports to `~/.pi/agent/mcp.json`.
+If you prefer the terminal, you can also run `pi-mcp-adapter init` after install to scan for host-specific configs and add missing compatibility imports to the Pi agent dir (`~/.pi/agent/mcp.json` by default, or `$PI_CODING_AGENT_DIR/mcp.json` when set).
 
 ## Quick Start
 
@@ -55,13 +55,13 @@ Preferred user-global shared config: `~/.config/mcp/mcp.json`
 
 Pi also reads Pi-owned override files for settings and host-specific compatibility:
 
-- `~/.pi/agent/mcp.json` — Pi global override
+- `<Pi agent dir>/mcp.json` — Pi global override (`~/.pi/agent/mcp.json` by default)
 - `.pi/mcp.json` — Pi project override
 
 Precedence is:
 
 1. `~/.config/mcp/mcp.json`
-2. `~/.pi/agent/mcp.json`
+2. `<Pi agent dir>/mcp.json`
 3. `.mcp.json`
 4. `.pi/mcp.json`
 
@@ -96,7 +96,7 @@ Use the shared MCP files when you want one setup to work across hosts, and Pi-ow
 |------|---------|
 | `~/.config/mcp/mcp.json` | User-global shared MCP config |
 | `.mcp.json` | Project-local shared MCP config |
-| `~/.pi/agent/mcp.json` | Pi global override and compatibility imports |
+| `<Pi agent dir>/mcp.json` | Pi global override and compatibility imports (`~/.pi/agent/mcp.json` by default) |
 | `.pi/mcp.json` | Pi project override |
 
 Pi-specific files are the write targets for imported or shared global servers when Pi needs to persist adapter-only settings such as `directTools`.
@@ -120,9 +120,10 @@ Pi-specific files are the write targets for imported or shared global servers wh
 |-------|-------------|
 | `command` | Executable for stdio transport |
 | `args` | Command arguments |
-| `env` | Environment variables (`${VAR}` interpolation) |
-| `cwd` | Working directory |
+| `env` | Environment variables; supports `${VAR}` and `$env:VAR` interpolation |
+| `cwd` | Working directory; supports `${VAR}`, `$env:VAR`, and `~` expansion |
 | `url` | HTTP endpoint (StreamableHTTP with SSE fallback) |
+| `headers` | HTTP headers; supports `${VAR}` and `$env:VAR` interpolation |
 | `auth` | `"bearer"` or `"oauth"` |
 | `oauth.grantType` | `"authorization_code"` (default) or `"client_credentials"` for non-interactive machine auth |
 | `bearerToken` / `bearerTokenEnv` | Token or env var name |
@@ -231,7 +232,7 @@ To exclude specific tools while still using `directTools: true`, add `excludeToo
 
 Each direct tool costs ~150-300 tokens in the system prompt (name + description + schema). Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy or pick specific tools with a `string[]`.
 
-Direct tools register from the metadata cache (`~/.pi/agent/mcp-cache.json`), so no server connections are needed at startup. On the first session after adding `directTools` to a new server, the cache won't exist yet — tools fall back to proxy-only and the cache populates in the background. To force it: `/mcp reconnect <server>`.
+Direct tools register from the metadata cache in the Pi agent dir (`~/.pi/agent/mcp-cache.json` by default, or `$PI_CODING_AGENT_DIR/mcp-cache.json` when set), so no server connections are needed at startup. On the first session after adding `directTools` to a new server, the cache won't exist yet — tools fall back to proxy-only and the cache populates in the background. To force it: `/mcp reconnect <server>`.
 
 When you change direct-tool toggles in `/mcp` or write new config through `/mcp setup`, the extension triggers Pi's normal reload flow automatically. That refreshes extensions, prompts, skills, and MCP tool registration in one shot, so newly configured direct tools can appear without a manual restart.
 
@@ -313,7 +314,7 @@ Shared MCP files are loaded automatically. Use `imports` only for host-specific
 
 Supported compatibility imports: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`
 
-`pi-mcp-adapter init` detects these host-specific configs and adds missing imports to `~/.pi/agent/mcp.json` for you.
+`pi-mcp-adapter init` detects these host-specific configs and adds missing imports to the Pi agent dir config for you.
 
 ### Project Config
 

package/agent-dir.ts

@@ -0,0 +1,20 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export function getAgentDir(): string {
+  const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+  if (!configured) {
+    return join(homedir(), ".pi", "agent");
+  }
+  if (configured === "~") {
+    return homedir();
+  }
+  if (configured.startsWith("~/")) {
+    return resolve(homedir(), configured.slice(2));
+  }
+  return resolve(configured);
+}
+
+export function getAgentPath(...segments: string[]): string {
+  return join(getAgentDir(), ...segments);
+}

package/cli.js

@@ -6,7 +6,17 @@ import os from "node:os";
 import { pathToFileURL } from "node:url";
 
 const HOME = os.homedir();
-const PI_CONFIG_PATH = path.join(HOME, ".pi", "agent", "mcp.json");
+
+function expandHome(input) {
+  if (input === "~") return HOME;
+  if (input.startsWith("~/")) return path.resolve(HOME, input.slice(2));
+  return path.resolve(input);
+}
+
+const AGENT_DIR = process.env.PI_CODING_AGENT_DIR?.trim()
+  ? expandHome(process.env.PI_CODING_AGENT_DIR.trim())
+  : path.join(HOME, ".pi", "agent");
+const PI_CONFIG_PATH = path.join(AGENT_DIR, "mcp.json");
 const GENERIC_GLOBAL_CONFIG_PATH = path.join(HOME, ".config", "mcp", "mcp.json");
 const PROJECT_CONFIG_PATH = path.resolve(process.cwd(), ".mcp.json");
 const PROJECT_PI_CONFIG_PATH = path.resolve(process.cwd(), ".pi", "mcp.json");

package/config.ts

@@ -2,9 +2,9 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import { getAgentPath } from "./agent-dir.js";
 import type { McpConfig, ServerEntry, McpSettings, ImportKind, ServerProvenance } from "./types.js";
 
-const PI_GLOBAL_CONFIG_PATH = join(homedir(), ".pi", "agent", "mcp.json");
 const GENERIC_GLOBAL_CONFIG_PATH = join(homedir(), ".config", "mcp", "mcp.json");
 const PROJECT_CONFIG_NAME = ".mcp.json";
 const PROJECT_PI_CONFIG_NAME = ".pi/mcp.json";
@@ -90,7 +90,7 @@ export interface ConfigWritePreview {
 }
 
 export function getPiGlobalConfigPath(overridePath?: string): string {
-  return overridePath ? resolve(overridePath) : PI_GLOBAL_CONFIG_PATH;
+  return overridePath ? resolve(overridePath) : getAgentPath("mcp.json");
 }
 
 export function getGenericGlobalConfigPath(): string {

package/mcp-auth.ts

@@ -5,12 +5,13 @@
  * and PKCE state for MCP servers. Maintains backward compatibility with
  * per-server directory structure.
  * 
- * Token storage location: ~/.pi/agent/mcp-oauth/<server>/tokens.json
+ * Token storage location: $MCP_OAUTH_DIR/<server>/tokens.json when set,
+ * otherwise <Pi agent dir>/mcp-oauth/<server>/tokens.json
  */
 
 import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from 'fs';
 import { join } from 'path';
-import { homedir } from 'os';
+import { getAgentPath } from './agent-dir.js';
 
 /** OAuth token storage format */
 export interface StoredTokens {
@@ -39,9 +40,8 @@ export interface AuthEntry {
 
 // Base directory for auth storage - can be overridden via env var for testing
 function getAuthBaseDir(): string {
-  return process.env.MCP_OAUTH_DIR 
-    ? process.env.MCP_OAUTH_DIR 
-    : join(homedir(), '.pi', 'agent', 'mcp-oauth');
+  const override = process.env.MCP_OAUTH_DIR?.trim();
+  return override ? override : getAgentPath('mcp-oauth');
 }
 
 /**

package/mcp-setup-panel.ts

@@ -459,7 +459,7 @@ export class McpSetupPanel {
           this.callbacks.previewImports(this.discovery.imports.filter((entry) => this.selectedImports.has(entry.kind)).map((entry) => entry.kind)),
           [
             `Detected imports: ${this.discovery.imports.map((entry) => `${entry.kind} (${entry.serverCount} servers)`).join(", ")}`,
-            "Selected imports are written into `~/.pi/agent/mcp.json` as Pi-owned compatibility state.",
+            "Selected imports are written into the Pi agent dir config as Pi-owned compatibility state.",
           ],
         );
       case "view-example":
@@ -480,7 +480,7 @@ export class McpSetupPanel {
         return this.formatPreview([
           "Read order:",
           "1. ~/.config/mcp/mcp.json",
-          "2. ~/.pi/agent/mcp.json",
+          "2. <Pi agent dir>/mcp.json",
           "3. .mcp.json",
           "4. .pi/mcp.json",
           "Pi writes compatibility imports and adapter-only overrides to Pi-owned files.",

package/metadata-cache.ts

@@ -1,17 +1,16 @@
 // metadata-cache.ts - Persistent MCP metadata cache
 import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname } from "node:path";
+import { getAgentPath } from "./agent-dir.js";
 import { createHash } from "node:crypto";
 import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
 import type { McpTool, McpResource, ServerEntry, ToolMetadata } from "./types.js";
 import { formatToolName, isToolExcluded } from "./types.js";
 import { resourceNameToToolName } from "./resource-tools.js";
-import { extractToolUiStreamMode } from "./utils.js";
+import { extractToolUiStreamMode, interpolateEnvRecord, resolveConfigPath } from "./utils.js";
 
 const CACHE_VERSION = 1;
 const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
-const CACHE_PATH = join(homedir(), ".pi", "agent", "mcp-cache.json");
 
 export interface CachedTool {
   name: string;
@@ -40,13 +39,14 @@ export interface MetadataCache {
 }
 
 export function getMetadataCachePath(): string {
-  return CACHE_PATH;
+  return getAgentPath("mcp-cache.json");
 }
 
 export function loadMetadataCache(): MetadataCache | null {
-  if (!existsSync(CACHE_PATH)) return null;
+  const cachePath = getMetadataCachePath();
+  if (!existsSync(cachePath)) return null;
   try {
-    const raw = JSON.parse(readFileSync(CACHE_PATH, "utf-8"));
+    const raw = JSON.parse(readFileSync(cachePath, "utf-8"));
     if (!raw || typeof raw !== "object") return null;
     if (raw.version !== CACHE_VERSION) return null;
     if (!raw.servers || typeof raw.servers !== "object") return null;
@@ -57,13 +57,14 @@ export function loadMetadataCache(): MetadataCache | null {
 }
 
 export function saveMetadataCache(cache: MetadataCache): void {
-  const dir = dirname(CACHE_PATH);
+  const cachePath = getMetadataCachePath();
+  const dir = dirname(cachePath);
   mkdirSync(dir, { recursive: true });
 
   let merged: MetadataCache = { version: CACHE_VERSION, servers: {} };
   try {
-    if (existsSync(CACHE_PATH)) {
-      const existing = JSON.parse(readFileSync(CACHE_PATH, "utf-8")) as MetadataCache;
+    if (existsSync(cachePath)) {
+      const existing = JSON.parse(readFileSync(cachePath, "utf-8")) as MetadataCache;
       if (existing && existing.version === CACHE_VERSION && existing.servers) {
         merged.servers = { ...existing.servers };
       }
@@ -75,9 +76,9 @@ export function saveMetadataCache(cache: MetadataCache): void {
   merged.version = CACHE_VERSION;
   merged.servers = { ...merged.servers, ...cache.servers };
 
-  const tmpPath = `${CACHE_PATH}.${process.pid}.tmp`;
+  const tmpPath = `${cachePath}.${process.pid}.tmp`;
   writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
-  renameSync(tmpPath, CACHE_PATH);
+  renameSync(tmpPath, cachePath);
 }
 
 export function computeServerHash(definition: ServerEntry): string {
@@ -87,12 +88,12 @@ export function computeServerHash(definition: ServerEntry): string {
   const identity: Record<string, unknown> = {
     command: definition.command,
     args: definition.args,
-    env: definition.env,
-    cwd: definition.cwd,
+    env: interpolateEnvRecord(definition.env),
+    cwd: resolveConfigPath(definition.cwd),
     url: definition.url,
-    headers: definition.headers,
+    headers: interpolateEnvRecord(definition.headers),
     auth: definition.auth,
-    bearerToken: definition.bearerToken,
+    bearerToken: definition.bearerToken ?? (definition.bearerTokenEnv ? process.env[definition.bearerTokenEnv] : undefined),
     bearerTokenEnv: definition.bearerTokenEnv,
     exposeResources: definition.exposeResources,
     excludeTools: definition.excludeTools,

package/npx-resolver.ts

@@ -1,12 +1,11 @@
 // npx-resolver.ts - Resolve npx/npm exec binaries to avoid npm parent processes
 import { existsSync, readFileSync, realpathSync, readdirSync, statSync, writeFileSync, renameSync, mkdirSync, openSync, readSync, closeSync } from "node:fs";
-import { homedir } from "node:os";
 import { join, dirname, extname, resolve, sep } from "node:path";
+import { getAgentPath } from "./agent-dir.js";
 import { spawn, spawnSync } from "node:child_process";
 
 const CACHE_VERSION = 1;
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-const CACHE_PATH = join(homedir(), ".pi", "agent", "mcp-npx-cache.json");
 
 interface NpxCacheEntry {
   resolvedBin: string;
@@ -367,10 +366,15 @@ function getNpmCacheDir(): string | null {
   return null;
 }
 
+function getNpxCachePath(): string {
+  return getAgentPath("mcp-npx-cache.json");
+}
+
 function loadCache(): NpxCache | null {
-  if (!existsSync(CACHE_PATH)) return null;
+  const cachePath = getNpxCachePath();
+  if (!existsSync(cachePath)) return null;
   try {
-    const raw = JSON.parse(readFileSync(CACHE_PATH, "utf-8"));
+    const raw = JSON.parse(readFileSync(cachePath, "utf-8"));
     if (!raw || typeof raw !== "object") return null;
     if (raw.version !== CACHE_VERSION) return null;
     if (!raw.entries || typeof raw.entries !== "object") return null;
@@ -381,13 +385,14 @@ function loadCache(): NpxCache | null {
 }
 
 function saveCacheEntry(key: string, entry: NpxCacheEntry): void {
-  const dir = dirname(CACHE_PATH);
+  const cachePath = getNpxCachePath();
+  const dir = dirname(cachePath);
   mkdirSync(dir, { recursive: true });
 
   let merged: NpxCache = { version: CACHE_VERSION, entries: {} };
   try {
-    if (existsSync(CACHE_PATH)) {
-      const existing = JSON.parse(readFileSync(CACHE_PATH, "utf-8")) as NpxCache;
+    if (existsSync(cachePath)) {
+      const existing = JSON.parse(readFileSync(cachePath, "utf-8")) as NpxCache;
       if (existing && existing.version === CACHE_VERSION && existing.entries) {
         merged.entries = { ...existing.entries };
       }
@@ -397,9 +402,9 @@ function saveCacheEntry(key: string, entry: NpxCacheEntry): void {
   }
 
   merged.entries[key] = entry;
-  const tmpPath = `${CACHE_PATH}.${process.pid}.tmp`;
+  const tmpPath = `${cachePath}.${process.pid}.tmp`;
   writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
-  renameSync(tmpPath, CACHE_PATH);
+  renameSync(tmpPath, cachePath);
 }
 
 function safeRealpath(path: string): string {

package/oauth-handler.ts

@@ -1,19 +1,22 @@
 // oauth-handler.ts - OAuth token management for MCP servers
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
+import { getAgentPath } from "./agent-dir.js";
 import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
 
 // Token storage path for a server
 function getTokensPath(serverName: string): string {
-  return join(homedir(), ".pi", "agent", "mcp-oauth", serverName, "tokens.json");
+  const override = process.env.MCP_OAUTH_DIR?.trim();
+  const authDir = override ? override : getAgentPath("mcp-oauth");
+  return join(authDir, serverName, "tokens.json");
 }
 
 /**
  * Get stored OAuth tokens for a server (if any).
  * Returns undefined if no tokens or tokens are expired.
  * 
- * Token file location: ~/.pi/agent/mcp-oauth/<server>/tokens.json
+ * Token file location: $MCP_OAUTH_DIR/<server>/tokens.json when set,
+ * otherwise <Pi agent dir>/mcp-oauth/<server>/tokens.json
  * 
  * Expected format:
  * {

package/onboarding-state.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname } from "node:path";
+import { getAgentPath } from "./agent-dir.js";
 
 export interface McpOnboardingState {
   version: 1;
@@ -16,7 +16,7 @@ const DEFAULT_STATE: McpOnboardingState = {
 };
 
 export function getOnboardingStatePath(): string {
-  return join(homedir(), ".pi", "agent", "mcp-onboarding.json");
+  return getAgentPath("mcp-onboarding.json");
 }
 
 export function loadOnboardingState(): McpOnboardingState {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,7 @@
   },
   "files": [
     "cli.js",
+    "agent-dir.ts",
     "index.ts",
     "state.ts",
     "utils.ts",

package/server-manager.ts

@@ -17,6 +17,7 @@ import { logger } from "./logger.js";
 import { McpOAuthProvider } from "./mcp-oauth-provider.js";
 import { supportsOAuth } from "./mcp-auth-flow.js";
 import { registerSamplingHandler, type ServerSamplingConfig } from "./sampling-handler.js";
+import { interpolateEnvRecord, resolveConfigPath } from "./utils.js";
 
 interface ServerConnection {
   client: Client;
@@ -91,7 +92,7 @@ export class McpServerManager {
         command,
         args,
         env: resolveEnv(definition.env),
-        cwd: definition.cwd,
+        cwd: resolveConfigPath(definition.cwd),
         stderr: definition.debug ? "inherit" : "ignore",
       });
     } else if (definition.url) {
@@ -362,28 +363,14 @@ function resolveEnv(env?: Record<string, string>): Record<string, string> {
   }
   
   if (!env) return resolved;
-  
-  for (const [key, value] of Object.entries(env)) {
-    // Support ${VAR} and $env:VAR interpolation
-    resolved[key] = value
-      .replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "")
-      .replace(/\$env:(\w+)/g, (_, name) => process.env[name] ?? "");
-  }
-  
-  return resolved;
+
+  const overrides = interpolateEnvRecord(env);
+  return overrides ? { ...resolved, ...overrides } : resolved;
 }
 
 /**
  * Resolve headers with environment variable interpolation.
  */
 function resolveHeaders(headers?: Record<string, string>): Record<string, string> | undefined {
-  if (!headers) return undefined;
-  
-  const resolved: Record<string, string> = {};
-  for (const [key, value] of Object.entries(headers)) {
-    resolved[key] = value
-      .replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "")
-      .replace(/\$env:(\w+)/g, (_, name) => process.env[name] ?? "");
-  }
-  return resolved;
+  return interpolateEnvRecord(headers);
 }

package/utils.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { platform } from "node:os";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
 import type { McpConfig } from "./types.js";
 
 async function execOpen(pi: ExtensionAPI, target: string, browser?: string) {
@@ -58,6 +59,33 @@ export function getConfigPathFromArgv(): string | undefined {
   return undefined;
 }
 
+export function interpolateEnvVars(value: string): string {
+  return value
+    .replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "")
+    .replace(/\$env:(\w+)/g, (_, name) => process.env[name] ?? "");
+}
+
+export function interpolateEnvRecord(values: Record<string, string> | undefined): Record<string, string> | undefined {
+  if (!values) return undefined;
+
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(values)) {
+    resolved[key] = interpolateEnvVars(value);
+  }
+  return resolved;
+}
+
+export function resolveConfigPath(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+
+  const resolved = interpolateEnvVars(value);
+  if (resolved === "~") return homedir();
+  if (resolved.startsWith("~/") || resolved.startsWith("~\\")) {
+    return join(homedir(), resolved.slice(2));
+  }
+  return resolved;
+}
+
 export function truncateAtWord(text: string, target: number): string {
   if (!text || text.length <= target) return text;