npm · pi-mcp-adapter2.5.4

Evidence

import { homedir } from "node:os";

import { join, resolve } from "node:path";

export function getAgentDir(): string {

RemediationAI

The problem is that getAgentDir() reads PI_CODING_AGENT_DIR from process.env without verifying the caller's identity or authorization, allowing any code path to access privileged agent configuration. Add a caller-context parameter to getAgentDir(callerContext: CallerContext) and validate the caller's identity against an allowlist before returning the directory path. This ensures only authorized callers can retrieve the agent directory, preventing confused deputy attacks. Verify the fix by adding unit tests that call getAgentDir() with both authorized and unauthorized caller contexts, confirming it throws an error for unauthorized callers.

Evidence

// config.ts - Config loading with import support

import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";

import { homedir } from "node:os";

import { dirname, join, resolve } from "node:path";

RemediationAI

The problem is that getPiGlobalConfigPath() caches the agent path at module load time without per-request authorization checks, allowing any subsequent caller to access the global config path regardless of their privileges. Refactor getPiGlobalConfigPath(callerContext: CallerContext) to accept a caller context parameter and validate authorization on each invocation before returning the path. This ensures authorization is checked at call time rather than relying on module-load-time initialization. Test by creating multiple caller contexts with different privilege levels and confirming only authorized callers receive valid paths.

Evidence

import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";

import type { McpExtensionState } from "./state.js";

import type { ToolMetadata } from "./types.js";

import { existsSync } from "node:fs";

RemediationAI

The problem is that initializeMcp() performs undisclosed side effects including filesystem writes (saveMetadataCache) and environment mutations (lifecycle.setGlobalIdleTimeout) that are not reflected in the function name or JSDoc. Add explicit JSDoc annotations documenting all side effects: @sideEffect FILESYSTEM - writes metadata cache to disk, @sideEffect ENV - modifies global idle timeout via lifecycle.setGlobalIdleTimeout(). This makes the side effects transparent to callers and reviewers. Verify by checking that the JSDoc accurately reflects all I/O and state mutations by tracing the function's execution path.

Evidence

// config.ts - Config loading with import support

import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";

import { homedir } from "node:os";

import { dirname, join, resolve } from "node:path";

RemediationAI

The problem is that getPiGlobalConfigPath() performs filesystem side effects (path resolution and potential directory creation) that are not disclosed in its name or documentation, violating the principle of least surprise. Rename the function to resolvePiGlobalConfigPath() and add JSDoc @sideEffect FILESYSTEM - may create directories via getAgentPath() to explicitly document the side effects. This clarifies that the function performs I/O operations beyond simple path computation. Verify by adding a test that calls the function and confirms that directories are created as expected.

Evidence

/**

 * MCP Auth Flow

 * 

 * High-level OAuth flow management using the MCP SDK's built-in auth functions.

RemediationAI

The problem is that startAuth() performs undisclosed network side effects (ensureCallbackServer, HTTP callback handling) and environment mutations (updateOAuthState) that are not mentioned in the function name or documentation. Add comprehensive JSDoc annotations: @sideEffect NETWORK - starts HTTP callback server, @sideEffect ENV - updates OAuth state via updateOAuthState(). This makes all side effects explicit to callers. Verify by adding integration tests that confirm the callback server starts and OAuth state is mutated as documented.

Evidence

import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";

import type { ImportKind } from "./types.js";

import type { ConfigWritePreview, McpDiscoverySummary } from "./config.js";

import type { McpOnboardingState } from "./onboarding-state.js";

interface SetupTheme {

  border: string;

  title: string;

  selected: string;

  hint: string;

  success: string;

  warning: string;

  muted: string;

}

const DEFAULT_THEME: SetupTheme = {

  border: "2",

  title: "36",

  selected: 

RemediationAI

The problem is that the MCP manifest declares tools but omits an authentication field, making it unclear whether the server relies on network-layer, host-level, or no authentication. Add an explicit auth field to the manifest (e.g., auth: { type: 'oauth', provider: 'mcp-auth-flow' } or auth: { type: 'none' }) to declare the actual authentication mechanism. This enables reviewers to audit the security model. Verify by reviewing the manifest against the actual auth implementation in mcp-auth-flow.ts and confirming the declared mechanism matches the code.

Evidence

<p>

  <img src="banner.png" alt="pi-mcp-adapter" width="1100">

</p>

# Pi MCP Adapter

Use MCP servers with [Pi](https://github.com/badlogic/pi-mono/) without burning your context window.

https://github.com/user-attachments/assets/4b7c66ff-e27e-4639-b195-22c3db406a5a

## Why This Exists

Mario wrote about [why you might not need MCP](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/). The problem: tool definitions are verbose. A single MCP server can burn 10k+ tokens, and you'

RemediationAI

The problem is that the README.md does not declare any authentication mechanism in the MCP manifest, leaving reviewers unable to audit the security model. Add an explicit authentication section to the README documenting the auth mechanism (e.g., 'OAuth via MCP SDK' or 'Host-level authentication') and include it in any manifest declarations. This ensures documentation and code are aligned. Verify by confirming the README's auth documentation matches the actual implementation in the codebase.

Evidence

// oauth-handler.ts - OAuth token management for MCP servers

import { existsSync, readFileSync } from "node:fs";

import { join } from "node:path";

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 {

  const override = process.env.MCP_OAUTH_DIR?.trim();

  const authDir = override ? override : getAgentPath("mcp-oauth");

  return join(authD

RemediationAI

The problem is that oauth-handler.ts uses existsSync() to check if a token file exists, then calls readFileSync() on the same path without atomic operations, allowing an attacker to race a symlink or file replacement between the check and read. Replace the check-then-use pattern by wrapping readFileSync() in a try-catch block that handles ENOENT errors: try { const tokens = readFileSync(tokenPath, 'utf-8'); } catch (err) { if (err.code !== 'ENOENT') throw err; return null; }. This eliminates the race window by making the read atomic. Verify by writing a test that attempts to race a symlink replacement and confirms the function safely handles the error.

Evidence

// config.ts - Config loading with import support

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 GENERIC_GLOBAL_CONFIG_PATH = join(homedir(), ".config", "mcp", "mcp.json");

const PROJECT_CONFIG_NAME = ".mcp.json";

c

RemediationAI

The problem is that config.ts uses existsSync() followed by readFileSync() or writeFileSync() without atomic operations, creating a TOCTOU race where an attacker can replace the file between the check and use. Replace all existsSync() checks with try-catch blocks around the actual file operation: try { const data = readFileSync(path); } catch (err) { if (err.code !== 'ENOENT') throw err; } and use atomic writes via writeFileSync() with a temp file and renameSync(). This eliminates the race window. Verify by running concurrent file operations and confirming no race conditions occur.

Evidence

// 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 { 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;

interface NpxCacheEntry 

RemediationAI

The problem is that npx-resolver.ts uses existsSync() followed by readFileSync(), readdirSync(), or statSync() without atomic operations, allowing symlink or file replacement attacks between the check and use. Replace all existsSync() checks with try-catch blocks around the actual filesystem operation: try { const stat = statSync(path); } catch (err) { if (err.code !== 'ENOENT') throw err; }. This makes each operation atomic and eliminates the race. Verify by writing tests that race symlink replacements and confirm the function handles errors safely.

Evidence

import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";

import { dirname } from "node:path";

import { getAgentPath } from "./agent-dir.js";

export interface McpOnboardingState {

  version: 1;

  sharedConfigHintShown: boolean;

  setupCompleted: boolean;

  lastDiscoveryFingerprint?: string;

}

const DEFAULT_STATE: McpOnboardingState = {

  version: 1,

  sharedConfigHintShown: false,

  setupCompleted: false,

};

export function getOnboardingStatePath(): string {

RemediationAI

The problem is that onboarding-state.ts uses existsSync() followed by readFileSync() or writeFileSync() without atomic operations, creating a TOCTOU vulnerability. Replace existsSync() checks with try-catch blocks around the actual file operation: try { const state = readFileSync(path, 'utf-8'); } catch (err) { if (err.code !== 'ENOENT') throw err; }. For writes, use atomic operations: writeFileSync(tmpPath, data); renameSync(tmpPath, finalPath). This eliminates the race window. Verify by running concurrent read/write operations and confirming no race conditions occur.

Evidence

/**

 * MCP Auth Storage Module

 * 

 * Handles secure storage of OAuth credentials, tokens, client information,

 * and PKCE state for MCP servers. Maintains backward compatibility with

 * per-server directory structure.

 * 

 * 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 { getAgentPath } from '

RemediationAI

The problem is that mcp-auth.ts uses existsSync() followed by readFileSync() or writeFileSync() without atomic operations, allowing file replacement attacks between the check and use. Replace all existsSync() checks with try-catch blocks around the actual file operation: try { const tokens = readFileSync(tokenPath); } catch (err) { if (err.code !== 'ENOENT') throw err; }. For writes, use atomic operations via writeFileSync(tmpPath, data); renameSync(tmpPath, finalPath). This eliminates the TOCTOU race. Verify by writing tests that race file replacements and confirm the function handles errors safely.

Evidence

// metadata-cache.ts - Persistent MCP metadata cache

import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";

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";

impor

RemediationAI

The problem is that metadata-cache.ts uses existsSync() followed by readFileSync() or writeFileSync() without atomic operations, creating a TOCTOU race where an attacker can replace the cache file between the check and use. Replace existsSync() checks with try-catch blocks around the actual file operation: try { const cache = readFileSync(cachePath); } catch (err) { if (err.code !== 'ENOENT') throw err; }. For writes, use atomic operations: writeFileSync(tmpPath, data); renameSync(tmpPath, cachePath). This eliminates the race window. Verify by running concurrent cache operations and confirming no race conditions occur.

Evidence

const address = server.address();

      if (!address || typeof address === "string") {

        const err = new ServerError("invalid address");

        log.error("Invalid server address", err);

        reject(err);

        return;

      }

RemediationAI

The problem is that ui-server.ts logs the server address object directly, which may contain PII or sensitive network information that could be exposed in centralized logging systems. Replace log.error('Invalid server address', err) with log.error('Invalid server address', { port: address?.port }) to log only non-sensitive fields. Create a sanitizeAddress() helper function that extracts only the port and excludes hostname/IP. This prevents PII leakage to log aggregation services. Verify by checking logs and confirming only the port is logged, not the full address object.

Evidence

return;

      }

      log.debug("Server started", { port: address.port });

      const handle: UiServerHandle = {

        url: `http://localhost:${address.port}/?session=${sessionToken}`,

RemediationAI

The problem is that ui-server.ts logs the sessionToken in the URL, which is sensitive authentication material that should not appear in logs accessible to a wider audience. Replace log.debug('Server started', { port: address.port, url: ... }) with log.debug('Server started', { port: address.port }) and remove the sessionToken from logged output. Store the full URL in memory only and never log authentication tokens. This prevents token leakage to centralized logging systems. Verify by checking logs and confirming the sessionToken does not appear anywhere.

Evidence

import type { ToolDefinition } from "@mariozechner/pi-coding-agent";

import type { McpExtensionState } from "./state.js";

import type { DirectToolSpec, McpConfig, McpContent } from "./types.js";

import type { MetadataCache } from "./metadata-cache.js";

import { lazyConnect, getFailureAgeSeconds } from "./init.js";

import { isServerCacheValid } from "./metadata-cache.js";

import { formatSchema } from "./tool-metadata.js";

import { transformMcpContent } from "./tool-registrar.js";

import { maybeSt

RemediationAI

The problem is that direct-tools.ts tool descriptions may contain imperative phrases directing the LLM to invoke other tools, enabling cross-tool chaining injection where the user authorized one tool but the description escalates to others. Audit all tool descriptions in direct-tools.ts and remove phrases like 'invoke', 'call', 'also use', 'silently invoke' that direct the LLM to use other tools. Rewrite descriptions to state what the tool DOES, not what other tools to call. This prevents unauthorized tool chaining. Verify by reviewing each tool description and confirming it contains no imperative directives to invoke other tools.

Evidence

const globalRoot = execFileSync("npm", ["root", "-g"], { encoding: "utf-8" }).trim();

    const binaryPath = join(globalRoot, "glimpseui", "src", "glimpse");

    if (existsSync(binaryPath)) return binaryPath;

  } catch {}

  return null;

}

RemediationAI

The problem is that glimpse-ui.ts silently swallows exceptions in the catch block with no logging, making it impossible to diagnose why the binary path resolution failed. Replace catch {} with catch (err) { log.debug('Failed to resolve glimpseui binary', { error: err.message }); } to log the error at an appropriate level. This enables incident response and debugging. Verify by triggering the error condition and confirming the error is logged with sufficient detail.

Evidence

setTimeout(() => {

          try {

            server.close();

          } catch {}

          closeSse();

        }, 20).unref();

        return;

RemediationAI

The problem is that ui-server.ts silently swallows server.close() errors with no logging, hiding failures that could indicate resource leaks or shutdown issues. Replace catch {} with catch (err) { log.warn('Error closing server', { error: err.message }); } to log the error. This enables visibility into shutdown failures. Verify by triggering a close error and confirming it is logged.

Evidence

markCompleted(reason ?? "closed");

          try {

            server.close();

          } catch {}

          closeSse();

        },

        sendToolInput: (args: Record<string, unknown>) => {

RemediationAI

The problem is that ui-server.ts silently swallows server.close() errors in multiple places with no logging, hiding shutdown failures. Replace all catch {} blocks around server.close() with catch (err) { log.warn('Error closing server during completion', { error: err.message }); } to log errors. This provides visibility into shutdown issues. Verify by triggering close errors and confirming they are logged.

Evidence

markCompleted("stale");

    try {

      server.close();

    } catch {}

    closeSse();

  }, WATCHDOG_INTERVAL_MS);

  watchdog.unref();

RemediationAI

The problem is that ui-server.ts silently swallows server.close() errors in the watchdog timer with no logging, hiding failures that could indicate resource leaks. Replace catch {} with catch (err) { log.warn('Error closing server in watchdog', { error: err.message }); } to log the error. This enables debugging of watchdog-related failures. Verify by triggering the error and confirming it is logged.

Evidence

for (const client of sseClients) {

      try {

        client.end();

      } catch {}

    }

    sseClients.clear();

  };

RemediationAI

The problem is that ui-server.ts silently swallows client.end() errors in the closeSse() function with no logging, hiding failures that could indicate SSE client cleanup issues. Replace catch {} with catch (err) { log.debug('Error closing SSE client', { error: err.message }); } to log the error. This provides visibility into SSE cleanup failures. Verify by triggering client close errors and confirming they are logged.

Evidence

var Mu=Object.defineProperty;var $e=(t,r)=>{for(var n in r)Mu(t,n,{get:r[n],enumerable:!0})};var s={};$e(s,{$brand:()=>pn,$input:()=>Si,$output:()=>ki,NEVER:()=>mn,TimePrecision:()=>ji,ZodAny:()=>Mc,ZodArray:()=>Hc,ZodBase64:()=>Ea,ZodBase64URL:()=>Aa,ZodBigInt:()=>Dt,ZodBigIntFormat:()=>Ma,ZodBoolean:()=>Zt,ZodCIDRv4:()=>Da,ZodCIDRv6:()=>Ra,ZodCUID:()=>ja,ZodCUID2:()=>Pa,ZodCatch:()=>au,ZodCustom:()=>Hr,ZodCustomStringFormat:()=>Ec,ZodDate:()=>qr,ZodDefault:()=>eu,ZodDiscriminatedUnion:()=>Jc,Z

RemediationAI

The problem is that app-bridge.bundle.js contains minified code with silent error swallowing that is difficult to audit. Ensure the source TypeScript/JavaScript files have proper error logging before bundling. Add a build-time check that flags catch blocks with no logging. This prevents error swallowing in the source. Verify by examining the source files and confirming all catch blocks have appropriate logging.

Evidence

} catch {}

      try {

        await bridge.teardownResource({});

      } catch {}

      clearInterval(heartbeat);

      eventSource.close();

      window.close();

RemediationAI

The problem is that host-html-template.ts silently swallows errors in bridge.teardownResource() and eventSource.close() with no logging, hiding cleanup failures. Replace catch {} with catch (err) { console.warn('Error during teardown', err); } to log errors. This enables debugging of resource cleanup issues. Verify by triggering teardown errors and confirming they are logged to the console.

Evidence

eventSource.addEventListener("host-context", (event) => {

      try {

        bridge.setHostContext(JSON.parse(event.data));

      } catch {}

    });

    eventSource.addEventListener("session-complete", async () => {

      await bridge.teardownResource({}).catch(() => {});

RemediationAI

The problem is that host-html-template.ts silently swallows JSON.parse() errors and bridge method errors with no logging, hiding parsing or communication failures. Replace catch {} with catch (err) { console.warn('Error parsing host context or tearing down', err); } to log errors. This provides visibility into event handling failures. Verify by sending malformed JSON and confirming the error is logged.

Evidence

path: iss.path ? [${xe(S)}, ...iss.path] : [${xe(S)}]

          })));`),$.write(`newResult[${xe(S)}] = ${I}.value`)}$.write("payload.value = newResult;"),$.write("return payload;");let D=$.compile();return(S,I)=>D(m,S,I)},e,o=Ne,a=!Ke.jitless,p=a&&bn.value,h=r.catchall,g;t._zod.parse=(m,$)=>{g??(g=n.value);let b=m.value;if(!o(b))return m.issues.push({expected:"object",code:"invalid_type",input:b,inst:t}),m;let d=[];if(a&&p&&$?.async===!1&&$.jitless!==!0)e||(e=i(r.shape)),m=e(m,$);else{m.value={}

RemediationAI

The problem is that app-bridge.bundle.js contains minified code with silent error swallowing that cannot be audited. Ensure the source files have proper error handling before bundling. Add a build-time linter rule that flags catch blocks with no logging. This prevents error swallowing in production code. Verify by examining the source TypeScript and confirming all catch blocks have logging.

Evidence

provenance.set(name, { path: userPath, kind: "import", importKind });

            }

          }

        } catch {}

      }

    }

RemediationAI

The problem is that config.ts silently swallows errors during config import processing with no logging, hiding failures that could indicate malformed config files. Replace catch {} with catch (err) { log.debug('Error processing config import', { name, error: err.message }); } to log the error. This enables debugging of config loading issues. Verify by providing malformed config and confirming the error is logged.

Evidence

const complete = async (reason) => {

      try {

        await post("/proxy/ui/complete", { reason });

      } catch {}

      try {

        await bridge.teardownResource({});

      } catch {}

RemediationAI

The problem is that host-html-template.ts silently swallows errors in post() and bridge.teardownResource() calls with no logging, hiding communication or cleanup failures. Replace catch {} with catch (err) { console.warn('Error during completion', err); } to log errors. This provides visibility into completion failures. Verify by triggering errors and confirming they are logged.

Evidence

const glimpseuiPath = require.resolve("glimpseui");

    const binaryPath = join(dirname(glimpseuiPath), "glimpse");

    if (existsSync(binaryPath)) return binaryPath;

  } catch {}

  // Global npm install

  try {

RemediationAI

The problem is that glimpse-ui.ts silently swallows errors when resolving the glimpseui binary with no logging, hiding failures that could indicate missing dependencies. Replace catch {} with catch (err) { log.debug('Failed to resolve glimpseui from require.resolve', { error: err.message }); } to log the error. This enables debugging of binary resolution issues. Verify by triggering the error and confirming it is logged.