pi-mcp-adapter 1.5.1 → 2.0.0

package/ARCHITECTURE.md

@@ -329,28 +329,30 @@
 ┌───────────────────────────────────────────────────────────────┐
 │              mcp tool execute() - executeCall()               │
 │                                                               │
-│  1. Look up tool in toolMetadata                              │
+│  1. Look up tool in toolMetadata (may be from cache)          │
 │     for (const [server, metadata] of toolMetadata) {          │
 │       const found = metadata.find(m => m.name === toolName);  │
 │       if (found) { serverName = server; toolMeta = found; }   │
 │     }                                                         │
+│     If not found: try prefix-match → lazy connect candidate   │
 │                                                               │
-│  2. Get connection from ServerManager                         │
+│  2. Ensure connection (lazy connect if needed)                │
 │     const connection = manager.getConnection(serverName);     │
-│     if (!connection || connection.status !== "connected")     │
-│       return error;                                           │
+│     if (!connection || status !== "connected")                │
+│       → check failure backoff (60s)                           │
+│       → connect, refresh metadata, re-resolve toolMeta        │
 │                                                               │
-│  3. Call MCP server                                           │
+│  3. Call MCP server (with in-flight tracking)                 │
+│     incrementInFlight() + touch()                             │
 │     if (toolMeta.resourceUri) {                               │
-│       // Resource tool - use readResource                     │
 │       connection.client.readResource({ uri: resourceUri });   │
 │     } else {                                                  │
-│       // Regular tool - use callTool                          │
 │       connection.client.callTool({                            │
 │         name: toolMeta.originalName,  ◄── Original name!      │
 │         arguments: args ?? {}                                 │
 │       });                                                     │
 │     }                                                         │
+│     finally { decrementInFlight() + touch() }                 │
 └───────────────────────────┬───────────────────────────────────┘
                             │
                             ▼
@@ -411,6 +413,12 @@
 
 ## Lifecycle & Health Checks
 
+Servers support three lifecycle modes:
+
+- **lazy** (default): Don't connect at startup. Connect on first tool call. Subject to idle timeout (default 10 minutes). Cached metadata enables search/list without connections.
+- **eager**: Connect at startup. No idle timeout by default. If the connection drops, reconnects on next use (like lazy).
+- **keep-alive**: Connect at startup. No idle timeout. Auto-reconnects via health checks if the connection drops.
+
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │                          Session Start                                      │
@@ -423,11 +431,17 @@
                     │  1. Load config                 │
                     │  2. Create ServerManager        │
                     │  3. Create LifecycleManager     │
-                    │  4. Connect to each server      │
-                    │  5. Collect tool metadata       │
-                    │  6. Mark keep-alive servers     │
-                    │  7. Start health checks         │
-                    │  8. Set reconnect callback      │
+                    │  4. Load metadata cache         │
+                    │  5. Register all servers with   │
+                    │     lifecycle manager            │
+                    │  6. Reconstruct toolMetadata    │
+                    │     from cache (no connection)  │
+                    │  7. Connect only eager +        │
+                    │     keep-alive servers           │
+                    │     (or all on first-run         │
+                    │      bootstrap)                  │
+                    │  8. Start health checks         │
+                    │  9. Set reconnect/idle callbacks │
                     └─────────────────┬───────────────┘
                                       │
                                       ▼
@@ -439,25 +453,39 @@
 │   │                                                                     │   │
 │   │     for each keep-alive server:                                     │   │
 │   │       if (status !== "connected"):                                  │   │
-│   │         try reconnect                                               │   │
-│   │         if success: call onReconnect callback                       │   │
-│   │                     → updates toolMetadata                          │   │
+│   │         try reconnect → onReconnect → updates toolMetadata + cache  │   │
+│   │                                                                     │   │
+│   │     for each non-keep-alive server:                                 │   │
+│   │       if idle > timeout and inFlight == 0:                          │   │
+│   │         close connection → onIdleShutdown                           │   │
+│   │         (toolMetadata preserved for search/list)                    │   │
+│   │                                                                     │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                    Lazy Connection (on tool call)                    │   │
+│   │                                                                     │   │
+│   │     executeCall() finds tool in cached metadata but no connection:  │   │
+│   │       1. Check failure backoff (60s)                                │   │
+│   │       2. Connect server                                             │   │
+│   │       3. Refresh metadata from live connection                      │   │
+│   │       4. Re-resolve tool (may have changed since cache)             │   │
+│   │       5. Execute tool call with in-flight tracking                  │   │
 │   │                                                                     │   │
-│   │     ┌──────────────────────────────────────────────────────────┐    │   │
-│   │     │  Note: Reconnect callback updates tool metadata so       │    │   │
-│   │     │  the mcp proxy tool can find tools after reconnection.   │    │   │
-│   │     └──────────────────────────────────────────────────────────┘    │   │
+│   │     Prefix-match fallback: if tool name has a server prefix but     │   │
+│   │       no metadata, try connecting the matching server               │   │
 │   │                                                                     │   │
 │   └─────────────────────────────────────────────────────────────────────┘   │
 │                                                                             │
 │   ┌─────────────────────────────────────────────────────────────────────┐   │
 │   │                    /mcp Commands                                    │   │
 │   │                                                                     │   │
-│   │   /mcp status    - Show all servers and their connection status    │   │
-│   │   /mcp tools     - List all available MCP tools                    │   │
-│   │   /mcp reconnect - Force reconnect all servers, update metadata    │   │
+│   │   /mcp status           - Show all servers and connection status   │   │
+│   │   /mcp tools            - List all available MCP tools             │   │
+│   │   /mcp reconnect        - Force reconnect all servers              │   │
+│   │   /mcp reconnect <name> - Connect or reconnect a single server    │   │
 │   │                                                                     │   │
-│   │   /mcp-auth <server> - Show OAuth setup instructions               │   │
+│   │   /mcp-auth <server>    - Show OAuth setup instructions            │   │
 │   │                                                                     │   │
 │   └─────────────────────────────────────────────────────────────────────┘   │
 │                                                                             │
@@ -468,9 +496,9 @@
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │                          Graceful Shutdown                                  │
 │                                                                             │
-│   1. Clear health check interval                                            │
-│   2. Close all MCP connections (client + transport)                         │
-│   3. Tool calls via mcp proxy return "not connected" error                  │
+│   1. Flush metadata cache for all connected servers                         │
+│   2. Clear health check interval                                            │
+│   3. Close all MCP connections (client + transport)                         │
 │                                                                             │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
@@ -498,17 +526,26 @@
 │                         - HTTP transport (StreamableHTTP + SSE fallback)
 │                         - connection pooling and deduplication
 │
-├── tool-registrar.ts     Tool name collection (NOT registration!)
-│                         - collectToolNames() - builds name list
+├── tool-registrar.ts     MCP content transformation
 │                         - transformMcpContent() - MCP → Pi content
 │
-├── resource-tools.ts     Resource tool name collection
-│                         - collectResourceToolNames()
+├── resource-tools.ts     Resource name utilities
 │                         - resourceNameToToolName()
 │
-├── lifecycle.ts          Health checks, reconnection
-│                         - keep-alive server tracking
-│                         - reconnect callback for metadata updates
+├── metadata-cache.ts     Persistent tool/resource metadata cache
+│                         - Per-server cache at ~/.pi/agent/mcp-cache.json
+│                         - Config hashing, staleness checks, reconstruction
+│                         - Read-merge-write for multi-session safety
+│
+├── npx-resolver.ts       npx binary resolution (skip npm parent process)
+│                         - Probes ~/.npm/_npx/ cache directly
+│                         - Persistent cache at ~/.pi/agent/mcp-npx-cache.json
+│                         - JS detection (extension + shebang)
+│
+├── lifecycle.ts          Health checks, reconnection, idle timeout
+│                         - keep-alive server tracking + auto-reconnect
+│                         - Idle timeout for lazy/eager servers
+│                         - Per-server and global timeout settings
 │
 ├── oauth-handler.ts      OAuth token file reading
 │                         - getStoredTokens() from ~/.pi/agent/mcp-oauth/
@@ -568,5 +605,26 @@
 │     Lifecycle manager notifies extension after auto-reconnect.              │
 │     Extension updates tool metadata so proxy can find tools.                │
 │                                                                             │
+│  8. LAZY BY DEFAULT                                                         │
+│     ───────────────                                                         │
+│     All servers default to lifecycle: "lazy". They only connect             │
+│     when a tool call needs them. Cached metadata enables                    │
+│     search/list/describe without live connections. Idle servers             │
+│     are disconnected after 10 minutes (configurable).                       │
+│                                                                             │
+│  9. METADATA CACHE                                                          │
+│     ──────────────                                                          │
+│     ~/.pi/agent/mcp-cache.json stores per-server tool/resource              │
+│     metadata with config hash validation and 7-day staleness.               │
+│     Cache stores original MCP names (not prefixed) — toolPrefix             │
+│     changes never invalidate the cache. Read-merge-write with               │
+│     per-process tmp files for multi-session safety.                         │
+│                                                                             │
+│  10. NPX RESOLUTION                                                         │
+│      ───────────────                                                        │
+│      npx-based servers resolve to direct binary paths, eliminating          │
+│      the ~143 MB npm parent process per server. Probes ~/.npm/_npx/         │
+│      cache directly. JS files run via node, others executed directly.       │
+│                                                                             │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-01-29
+
+### Changed
+- **BREAKING: Lazy startup by default** - All servers now default to `lifecycle: "lazy"` and only connect when a tool call needs them. Previously all servers connected eagerly on session start. Set `lifecycle: "keep-alive"` or `lifecycle: "eager"` to restore the old behavior per-server.
+- **Idle timeout** - Connected servers are automatically disconnected after 10 minutes of inactivity (configurable via `settings.idleTimeout` or per-server `idleTimeout`). Cached metadata keeps search/list working after disconnect. Set `idleTimeout: 0` to disable.
+- `/mcp reconnect` accepts an optional server name to connect or reconnect a single server
+
+### Added
+- **Metadata cache** - Tool and resource metadata persisted to `~/.pi/agent/mcp-cache.json`. Enables search/list/describe without live connections. Per-server config hashing with 7-day staleness. Multi-session safe via read-merge-write with per-process tmp files.
+- **npx binary resolution** - Resolves npx package binaries to direct paths, eliminating the ~143 MB npm parent process per server. Persistent cache at `~/.pi/agent/mcp-npx-cache.json` with 24h TTL.
+- **`mcp({ connect: "server-name" })` mode** - Explicitly trigger connection and metadata refresh for a named server
+- **Failure backoff** - Servers that fail to connect are skipped for 60 seconds to avoid repeated connection storms
+- **In-flight tracking** - Active tool calls prevent idle timeout from shutting down a server mid-request
+- **Prefix-match fallback** - Tool calls with unrecognized names try to match a server prefix and lazy-connect the matching server
+- Lifecycle options: `lazy` (default), `eager` (connect at startup, no auto-reconnect), `keep-alive` (unchanged)
+- Per-server `idleTimeout` override and global `settings.idleTimeout`
+- First-run bootstrap: connects all servers on first session to populate the cache
+
+### Fixed
+- Connection close race condition: concurrent close + connect no longer orphans server processes
+- **Fuzzy tool name matching** - Hyphens and underscores are treated as equivalent during tool lookup. MCP tools like `resolve-library-id` are now found when called as `resolve_library_id`, which LLMs naturally guess since the prefix separator is `_`.
+- **Better "tool not found" errors** - When a server is identified (via prefix match or override) but the tool isn't found, the error now lists that server's available tools so the LLM can self-correct immediately instead of needing a separate list call
+
+## [1.6.0] - 2026-01-29
+
+### Added
+- **Unified pi tool search** - `mcp({ search: "..." })` now searches both MCP tools and Pi tools (from installed extensions)
+- Pi tools appear first in results with `[pi tool]` prefix
+- Details object includes `server: "pi"` for pi tools
+- Banner image for README
+
+## [1.5.1] - 2026-01-26
+
 ### Changed
 - Added `pi-package` keyword for npm discoverability (pi v0.50.0 package system)
 

package/README.md

@@ -1,3 +1,7 @@
+<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.
@@ -10,15 +14,15 @@ Mario wrote about [why you might not need MCP](https://mariozechner.at/posts/202
 
 His take: skip MCP entirely, write simple CLI tools instead.
 
-But the MCP ecosystem has useful stuff - databases, browsers, APIs. This adapter gives you access without the bloat. One proxy tool (~200 tokens) instead of hundreds. The agent discovers what it needs on-demand.
+But the MCP ecosystem has useful stuff - databases, browsers, APIs. This adapter gives you access without the bloat. One proxy tool (~200 tokens) instead of hundreds. The agent discovers what it needs on-demand. Servers only start when you actually use them.
 
 ## Install
 
 ```bash
-npx pi-mcp-adapter
+pi install npm:pi-mcp-adapter
 ```
 
-This downloads the extension to `~/.pi/agent/extensions/pi-mcp-adapter/`, installs dependencies, and configures Pi to load it. Restart Pi after installation.
+Restart Pi after installation.
 
 ## Quick Start
 
@@ -29,14 +33,13 @@ Create `~/.pi/agent/mcp.json`:
   "mcpServers": {
     "chrome-devtools": {
       "command": "npx",
-      "args": ["-y", "chrome-devtools-mcp@latest"],
-      "lifecycle": "keep-alive"
+      "args": ["-y", "chrome-devtools-mcp@latest"]
     }
   }
 }
 ```
 
-The LLM searches for tools, sees their schemas, and calls them:
+Servers are **lazy by default** — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.
 
 ```
 mcp({ search: "screenshot" })
@@ -67,7 +70,8 @@ Two calls instead of 26 tools cluttering the context.
     "my-server": {
       "command": "npx",
       "args": ["-y", "some-mcp-server"],
-      "lifecycle": "keep-alive"
+      "lifecycle": "lazy",
+      "idleTimeout": 10
     }
   }
 }
@@ -78,13 +82,40 @@ Two calls instead of 26 tools cluttering the context.
 | `command` | Executable for stdio transport |
 | `args` | Command arguments |
 | `env` | Environment variables (`${VAR}` interpolation) |
+| `cwd` | Working directory |
 | `url` | HTTP endpoint (StreamableHTTP with SSE fallback) |
 | `auth` | `"bearer"` or `"oauth"` |
-| `bearerToken` / `bearerTokenEnv` | Token or env var |
-| `lifecycle` | `"keep-alive"` for auto-reconnect |
+| `bearerToken` / `bearerTokenEnv` | Token or env var name |
+| `lifecycle` | `"lazy"` (default), `"eager"`, or `"keep-alive"` |
+| `idleTimeout` | Minutes before idle disconnect (overrides global) |
 | `exposeResources` | Expose MCP resources as tools (default: true) |
 | `debug` | Show server stderr (default: false) |
 
+### Lifecycle Modes
+
+- **`lazy`** (default) — Don't connect at startup. Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
+- **`eager`** — Connect at startup but don't auto-reconnect if the connection drops. No idle timeout by default (set `idleTimeout` explicitly to enable).
+- **`keep-alive`** — Connect at startup. Auto-reconnect via health checks. No idle timeout. Use for servers you always need available.
+
+### Settings
+
+```json
+{
+  "settings": {
+    "toolPrefix": "server",
+    "idleTimeout": 10
+  },
+  "mcpServers": { }
+}
+```
+
+| Setting | Description |
+|---------|-------------|
+| `toolPrefix` | `"server"` (default), `"short"` (strips `-mcp` suffix), or `"none"` |
+| `idleTimeout` | Global idle timeout in minutes (default: 10, 0 to disable) |
+
+Per-server `idleTimeout` overrides the global setting.
+
 ### Import Existing Configs
 
 Already have MCP set up elsewhere? Import it:
@@ -98,16 +129,24 @@ Already have MCP set up elsewhere? Import it:
 
 Supported: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`
 
+### Project Config
+
+Add `.pi/mcp.json` in a project root for project-specific servers. Project config overrides global and imported servers.
+
 ## Usage
 
 | Mode | Example |
 |------|---------|
+| Status | `mcp({ })` |
+| List server | `mcp({ server: "name" })` |
 | Search | `mcp({ search: "screenshot navigate" })` |
 | Describe | `mcp({ describe: "tool_name" })` |
 | Call | `mcp({ tool: "...", args: '{"key": "value"}' })` |
-| Status | `mcp({ })` or `mcp({ server: "name" })` |
+| Connect | `mcp({ connect: "server-name" })` |
+
+Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are OR'd.
 
-Search includes parameter schemas by default. Space-separated words are OR'd.
+Tool names are fuzzy-matched on hyphens and underscores — `context7_resolve_library_id` finds `context7_resolve-library-id`.
 
 ## Commands
 
@@ -115,19 +154,24 @@ Search includes parameter schemas by default. Space-separated words are OR'd.
 |---------|--------------|
 | `/mcp` | Server status |
 | `/mcp tools` | List all tools |
-| `/mcp reconnect` | Reconnect servers |
+| `/mcp reconnect` | Reconnect all servers |
+| `/mcp reconnect <server>` | Connect or reconnect a single server |
 | `/mcp-auth <server>` | OAuth setup |
 
 ## How It Works
 
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for details. Short version:
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full picture. Short version:
 
-- One `mcp` tool in context (~200 tokens)
-- Tool metadata stored in a map, looked up at call time
-- MCP server validates arguments
+- One `mcp` tool in context (~200 tokens) instead of hundreds
+- Servers are lazy by default — they connect on first tool call, not at startup
+- Tool metadata is cached to disk so search/list/describe work without live connections
+- Idle servers disconnect after 10 minutes (configurable), reconnect automatically on next use
+- npx-based servers resolve to direct binary paths, skipping the ~143 MB npm parent process
+- MCP server validates arguments, not the adapter
 - Keep-alive servers get health checks and auto-reconnect
 
 ## Limitations
 
 - OAuth tokens obtained externally (no browser flow)
 - No automatic token refresh
+- Cross-session server sharing not yet implemented (each Pi session runs its own server processes)

package/cli.js

@@ -19,6 +19,8 @@ const FILES = [
   "tool-registrar.ts",
   "resource-tools.ts",
   "lifecycle.ts",
+  "metadata-cache.ts",
+  "npx-resolver.ts",
   "oauth-handler.ts",
   "package.json",
   "tsconfig.json",

package/config.ts

@@ -109,6 +109,7 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
   switch (kind) {
     case "claude-desktop":
     case "claude-code":
+    case "codex":
       servers = obj.mcpServers;
       break;
     case "cursor":
@@ -116,14 +117,10 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
     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 {};
   }