pi-mcp-adapter 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nico Bailon
+
+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/README.md

@@ -0,0 +1,189 @@
+# Pi MCP Adapter
+
+Connect [Pi](https://github.com/badlogic/pi-mono/) to any MCP server without burning your context window.
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    }
+  }
+}
+```
+
+## The Problem
+
+MCP servers expose tools for databases, browsers, file systems, APIs. But each tool definition costs ~200 tokens when sent to the LLM. A server with 50 tools? That's 10,000 tokens gone before you've even started. Three servers and you've lost 30K tokens to tool definitions alone.
+
+## The Solution
+
+One proxy tool. The LLM searches for what it needs, sees the schema, and calls it:
+
+```
+mcp({ search: "screenshot" })
+```
+```
+chrome_devtools_take_screenshot
+  Take a screenshot of the page or element.
+
+  Parameters:
+    format (enum: "png", "jpeg", "webp") [default: "png"]
+    fullPage (boolean) - Full page instead of viewport
+```
+```
+mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })
+```
+
+Two calls. ~200 tokens for the proxy tool instead of 30K+ for every tool definition.
+
+## Install
+
+```bash
+cd ~/.pi/agent/extensions
+npm install pi-mcp-adapter
+```
+
+Or clone it:
+
+```bash
+git clone https://github.com/nicobailon/pi-mcp-adapter
+cd pi-mcp-adapter && npm install
+```
+
+Restart Pi.
+
+## Config
+
+Create `~/.pi/agent/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"],
+      "lifecycle": "keep-alive"
+    }
+  }
+}
+```
+
+For HTTP servers:
+
+```json
+{
+  "mcpServers": {
+    "remote-api": {
+      "url": "https://api.example.com/mcp",
+      "auth": "bearer",
+      "bearerTokenEnv": "API_TOKEN"
+    }
+  }
+}
+```
+
+### Options
+
+| Field | Description |
+|-------|-------------|
+| `command` | Executable for stdio transport |
+| `args` | Command arguments |
+| `env` | Environment variables (`${VAR}` interpolation supported) |
+| `url` | HTTP endpoint (tries StreamableHTTP, falls back to SSE) |
+| `auth` | `"bearer"` or `"oauth"` |
+| `bearerToken` / `bearerTokenEnv` | Token or env var containing token |
+| `lifecycle` | `"keep-alive"` for auto-reconnect |
+| `exposeResources` | Expose MCP resources as tools (default: true) |
+| `debug` | Show server stderr output (default: false) |
+
+### Import Existing Configs
+
+Already have MCP set up in Cursor or Claude? Import it:
+
+```json
+{
+  "imports": ["cursor", "claude-code", "claude-desktop"],
+  "mcpServers": { }
+}
+```
+
+Supported: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`
+
+## Usage
+
+### Search
+
+```
+mcp({ search: "screenshot navigate" })
+```
+
+Space-separated words are OR'd. Results include parameter schemas by default.
+
+Use `includeSchemas: false` for compact output, `regex: true` for regex matching.
+
+### Describe
+
+```
+mcp({ describe: "chrome_devtools_take_screenshot" })
+```
+
+Full details for a specific tool. Mostly redundant now that search includes schemas.
+
+### Call
+
+```
+mcp({ tool: "chrome_devtools_navigate_page", args: { type: "url", url: "https://example.com" } })
+```
+
+If you pass bad arguments, the error includes the expected schema.
+
+### Status
+
+```
+mcp({ })
+mcp({ server: "chrome-devtools" })
+```
+
+See connected servers and their tools.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/mcp` | Server status |
+| `/mcp tools` | List all tools |
+| `/mcp reconnect` | Reconnect all servers |
+| `/mcp-auth <server>` | OAuth setup instructions |
+
+## OAuth
+
+For OAuth servers, get a token from your provider and save it:
+
+```bash
+mkdir -p ~/.pi/agent/mcp-oauth/my-server
+cat > ~/.pi/agent/mcp-oauth/my-server/tokens.json << 'EOF'
+{
+  "access_token": "your-token",
+  "token_type": "bearer"
+}
+EOF
+```
+
+Then `/mcp reconnect`.
+
+## How It Works
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full breakdown. The short version:
+
+- One `mcp` tool registered with Pi (~200 tokens)
+- Tool metadata stored in a map, looked up at call time
+- MCP server validates arguments (no schema conversion needed)
+- Keep-alive servers get health checks and auto-reconnect
+
+## Limitations
+
+- OAuth tokens obtained externally (no browser flow)
+- No automatic token refresh
+- Servers connect sequentially on startup

package/config.ts

@@ -0,0 +1,132 @@
+// config.ts - Config loading with import support
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { McpConfig, ServerEntry, McpSettings, ImportKind } from "./types.js";
+
+const DEFAULT_CONFIG_PATH = join(homedir(), ".pi", "agent", "mcp.json");
+const PROJECT_CONFIG_NAME = ".pi/mcp.json";
+
+// Import source paths for other tools
+const IMPORT_PATHS: Record<ImportKind, string> = {
+  "cursor": join(homedir(), ".cursor", "mcp.json"),
+  "claude-code": join(homedir(), ".claude", "claude_desktop_config.json"),
+  "claude-desktop": join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+  "codex": join(homedir(), ".codex", "config.json"),
+  "windsurf": join(homedir(), ".windsurf", "mcp.json"),
+  "vscode": ".vscode/mcp.json", // Relative to project
+};
+
+export function loadMcpConfig(overridePath?: string): McpConfig {
+  const configPath = overridePath ? resolve(overridePath) : DEFAULT_CONFIG_PATH;
+  
+  // Load base config
+  let config: McpConfig = { mcpServers: {} };
+  
+  if (existsSync(configPath)) {
+    try {
+      const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+      config = validateConfig(raw);
+    } catch (error) {
+      console.warn(`Failed to load MCP config from ${configPath}:`, error);
+    }
+  }
+  
+  // Process imports from other tools
+  if (config.imports?.length) {
+    for (const importKind of config.imports) {
+      const importPath = IMPORT_PATHS[importKind];
+      if (!importPath) continue;
+      
+      const fullPath = importPath.startsWith(".") 
+        ? resolve(process.cwd(), importPath) 
+        : importPath;
+      
+      if (!existsSync(fullPath)) continue;
+      
+      try {
+        const imported = JSON.parse(readFileSync(fullPath, "utf-8"));
+        const servers = extractServers(imported, importKind);
+        
+        // Merge - local config takes precedence over imports
+        for (const [name, def] of Object.entries(servers)) {
+          if (!config.mcpServers[name]) {
+            config.mcpServers[name] = def;
+          }
+        }
+      } catch (error) {
+        console.warn(`Failed to import MCP config from ${importKind}:`, error);
+      }
+    }
+  }
+  
+  // Check for project-local config (skip if it's the same as the main config)
+  const projectPath = resolve(process.cwd(), PROJECT_CONFIG_NAME);
+  if (existsSync(projectPath) && projectPath !== configPath) {
+    try {
+      const projectConfig = JSON.parse(readFileSync(projectPath, "utf-8"));
+      const validated = validateConfig(projectConfig);
+      
+      // Project config overrides everything
+      config.mcpServers = { ...config.mcpServers, ...validated.mcpServers };
+      if (validated.settings) {
+        config.settings = { ...config.settings, ...validated.settings };
+      }
+    } catch (error) {
+      console.warn(`Failed to load project MCP config:`, error);
+    }
+  }
+  
+  return config;
+}
+
+function validateConfig(raw: unknown): McpConfig {
+  if (!raw || typeof raw !== "object") {
+    return { mcpServers: {} };
+  }
+  
+  const obj = raw as Record<string, unknown>;
+  const servers = obj.mcpServers ?? obj["mcp-servers"] ?? {};
+  
+  // Must be a plain object, not an array or null
+  if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
+    return { mcpServers: {} };
+  }
+  
+  return {
+    mcpServers: servers as Record<string, ServerEntry>,
+    imports: Array.isArray(obj.imports) ? obj.imports as ImportKind[] : undefined,
+    settings: obj.settings as McpSettings | undefined,
+  };
+}
+
+function extractServers(config: unknown, kind: ImportKind): Record<string, ServerEntry> {
+  if (!config || typeof config !== "object") return {};
+  
+  const obj = config as Record<string, unknown>;
+  
+  let servers: unknown;
+  switch (kind) {
+    case "claude-desktop":
+    case "claude-code":
+      servers = obj.mcpServers;
+      break;
+    case "cursor":
+    case "windsurf":
+    case "vscode":
+      servers = obj.mcpServers ?? obj["mcp-servers"];
+      break;
+    case "codex":
+      servers = obj.mcpServers;
+      break;
+    default:
+      return {};
+  }
+  
+  // Validate servers is a plain object
+  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+    return {};
+  }
+  
+  return servers as Record<string, ServerEntry>;
+}