feat: expand MCP server cwd paths

Author: nicobailon

CHANGELOG.md

@@ -7,6 +7,11 @@ 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

README.md

@@ -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 |

__tests__/direct-tools.test.ts

@@ -1,10 +1,29 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { buildProxyDescription, resolveDirectTools } from "../direct-tools.js";
 import { computeServerHash, type MetadataCache } from "../metadata-cache.js";
 import { buildToolMetadata } from "../tool-metadata.js";
 import type { McpConfig } from "../types.js";
 import { reconstructToolMetadata } from "../metadata-cache.js";
 
+const originalHashEnv = {
+  MCP_HASH_CWD: process.env.MCP_HASH_CWD,
+  MCP_HASH_ENV: process.env.MCP_HASH_ENV,
+  MCP_HASH_HEADER: process.env.MCP_HASH_HEADER,
+  MCP_HASH_TOKEN: process.env.MCP_HASH_TOKEN,
+};
+
+afterEach(() => {
+  for (const [key, value] of Object.entries(originalHashEnv)) {
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+});
+
 describe("buildProxyDescription", () => {
   it("documents the ui-messages action", () => {
     const config: McpConfig = {
@@ -79,6 +98,66 @@ describe("buildProxyDescription", () => {
   });
 });
 
+describe("metadata cache hashing", () => {
+  it("hashes interpolated cwd", () => {
+    process.env.MCP_HASH_CWD = "/tmp/mcp-one";
+    const first = computeServerHash({ command: "node", cwd: "${MCP_HASH_CWD}/server" });
+
+    process.env.MCP_HASH_CWD = "/tmp/mcp-two";
+    const second = computeServerHash({ command: "node", cwd: "${MCP_HASH_CWD}/server" });
+
+    expect(first).not.toBe(second);
+    expect(computeServerHash({ command: "node", cwd: "${MCP_HASH_CWD}/server" })).toBe(
+      computeServerHash({ command: "node", cwd: "/tmp/mcp-two/server" }),
+    );
+  });
+
+  it("hashes interpolated env values", () => {
+    process.env.MCP_HASH_ENV = "/tmp/data-one";
+    const first = computeServerHash({ command: "node", env: { DATA_DIR: "${MCP_HASH_ENV}" } });
+
+    process.env.MCP_HASH_ENV = "/tmp/data-two";
+    const second = computeServerHash({ command: "node", env: { DATA_DIR: "${MCP_HASH_ENV}" } });
+
+    expect(first).not.toBe(second);
+    expect(computeServerHash({ command: "node", env: { DATA_DIR: "${MCP_HASH_ENV}" } })).toBe(
+      computeServerHash({ command: "node", env: { DATA_DIR: "/tmp/data-two" } }),
+    );
+  });
+
+  it("hashes interpolated header values", () => {
+    process.env.MCP_HASH_HEADER = "header-one";
+    const first = computeServerHash({ url: "https://example.test/mcp", headers: { "x-root": "$env:MCP_HASH_HEADER" } });
+
+    process.env.MCP_HASH_HEADER = "header-two";
+    const second = computeServerHash({ url: "https://example.test/mcp", headers: { "x-root": "$env:MCP_HASH_HEADER" } });
+
+    expect(first).not.toBe(second);
+    expect(computeServerHash({ url: "https://example.test/mcp", headers: { "x-root": "$env:MCP_HASH_HEADER" } })).toBe(
+      computeServerHash({ url: "https://example.test/mcp", headers: { "x-root": "header-two" } }),
+    );
+  });
+
+  it("hashes tilde cwd as the home directory", () => {
+    expect(computeServerHash({ command: "node", cwd: "~/server" })).toBe(
+      computeServerHash({ command: "node", cwd: join(homedir(), "server") }),
+    );
+  });
+
+  it("hashes the effective bearerTokenEnv value", () => {
+    process.env.MCP_HASH_TOKEN = "token-one";
+    const first = computeServerHash({ url: "https://example.test/mcp", auth: "bearer", bearerTokenEnv: "MCP_HASH_TOKEN" });
+
+    process.env.MCP_HASH_TOKEN = "token-two";
+    const second = computeServerHash({ url: "https://example.test/mcp", auth: "bearer", bearerTokenEnv: "MCP_HASH_TOKEN" });
+
+    expect(first).not.toBe(second);
+    expect(computeServerHash({ url: "https://example.test/mcp", auth: "bearer", bearerTokenEnv: "MCP_HASH_TOKEN" })).toBe(
+      computeServerHash({ url: "https://example.test/mcp", auth: "bearer", bearerToken: "token-two", bearerTokenEnv: "MCP_HASH_TOKEN" }),
+    );
+  });
+});
+
 describe("excludeTools filtering", () => {
   it("filters excluded tools from live and cached metadata", () => {
     const definition = {

__tests__/server-manager-sampling.test.ts

@@ -1,4 +1,6 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { homedir } from "node:os";
+import { join } from "node:path";
 
 const mocks = vi.hoisted(() => ({
   clients: [] as any[],
@@ -40,11 +42,21 @@ vi.mock("../npx-resolver.js", () => ({
 }));
 
 describe("McpServerManager sampling", () => {
+  const originalMcpTestCwd = process.env.MCP_TEST_CWD;
+
   beforeEach(() => {
     mocks.clients.length = 0;
     mocks.transports.length = 0;
   });
 
+  afterEach(() => {
+    if (originalMcpTestCwd === undefined) {
+      delete process.env.MCP_TEST_CWD;
+    } else {
+      process.env.MCP_TEST_CWD = originalMcpTestCwd;
+    }
+  });
+
   it("advertises sampling and registers the handler before connecting", async () => {
     const { McpServerManager } = await import("../server-manager.ts");
     const manager = new McpServerManager();
@@ -75,4 +87,26 @@ describe("McpServerManager sampling", () => {
     expect(client.options).toBeUndefined();
     expect(client.setRequestHandler).not.toHaveBeenCalled();
   });
+
+  it("expands environment variables and tilde in stdio cwd", async () => {
+    const { McpServerManager } = await import("../server-manager.ts");
+    process.env.MCP_TEST_CWD = "/tmp/pi-mcp-cwd";
+
+    const envManager = new McpServerManager();
+    await envManager.connect("env-cwd", {
+      command: "node",
+      args: ["server.js"],
+      cwd: "${MCP_TEST_CWD}/nested",
+    });
+
+    const homeManager = new McpServerManager();
+    await homeManager.connect("home-cwd", {
+      command: "node",
+      args: ["server.js"],
+      cwd: "~/nested",
+    });
+
+    expect(mocks.transports[0].options).toMatchObject({ cwd: "/tmp/pi-mcp-cwd/nested" });
+    expect(mocks.transports[1].options).toMatchObject({ cwd: join(homedir(), "nested") });
+  });
 });

metadata-cache.ts

@@ -7,7 +7,7 @@ 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;
@@ -88,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-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.5.2",
+  "version": "2.5.3",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "license": "MIT",

package.json

@@ -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);
 }

server-manager.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;