@docyrus/docyrus 0.0.19 → 0.0.21

package/resources/pi-agent/extensions/notify.ts

@@ -0,0 +1,88 @@
+/**
+ * Desktop Notification Extension
+ *
+ * Sends a native desktop notification when the agent finishes and is waiting for input.
+ * Uses OSC 777 escape sequence - no external dependencies.
+ *
+ * Supported terminals: Ghostty, iTerm2, WezTerm, rxvt-unicode
+ * Not supported: Kitty (uses OSC 99), Terminal.app, Windows Terminal, Alacritty
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Markdown, type MarkdownTheme } from "@mariozechner/pi-tui";
+
+/**
+ * Send a desktop notification via OSC 777 escape sequence.
+ */
+const notify = (title: string, body: string): void => {
+	// OSC 777 format: ESC ] 777 ; notify ; title ; body BEL
+	process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
+};
+
+const isTextPart = (part: unknown): part is { type: "text"; text: string } =>
+	Boolean(part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part);
+
+const extractLastAssistantText = (messages: Array<{ role?: string; content?: unknown }>): string | null => {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i];
+		if (message?.role !== "assistant") {
+			continue;
+		}
+
+		const content = message.content;
+		if (typeof content === "string") {
+			return content.trim() || null;
+		}
+
+		if (Array.isArray(content)) {
+			const text = content.filter(isTextPart).map((part) => part.text).join("\n").trim();
+			return text || null;
+		}
+
+		return null;
+	}
+
+	return null;
+};
+
+const plainMarkdownTheme: MarkdownTheme = {
+	heading: (text) => text,
+	link: (text) => text,
+	linkUrl: () => "",
+	code: (text) => text,
+	codeBlock: (text) => text,
+	codeBlockBorder: () => "",
+	quote: (text) => text,
+	quoteBorder: () => "",
+	hr: () => "",
+	listBullet: () => "",
+	bold: (text) => text,
+	italic: (text) => text,
+	strikethrough: (text) => text,
+	underline: (text) => text,
+};
+
+const simpleMarkdown = (text: string, width = 80): string => {
+	const markdown = new Markdown(text, 0, 0, plainMarkdownTheme);
+	return markdown.render(width).join("\n");
+};
+
+const formatNotification = (text: string | null): { title: string; body: string } => {
+	const simplified = text ? simpleMarkdown(text) : "";
+	const normalized = simplified.replace(/\s+/g, " ").trim();
+	if (!normalized) {
+		return { title: "Ready for input", body: "" };
+	}
+
+	const maxBody = 200;
+	const body = normalized.length > maxBody ? `${normalized.slice(0, maxBody - 1)}…` : normalized;
+	return { title: "π", body };
+};
+
+export default function (pi: ExtensionAPI) {
+	pi.on("agent_end", async (event) => {
+		const lastText = extractLastAssistantText(event.messages ?? []);
+		const { title, body } = formatNotification(lastText);
+		notify(title, body);
+	});
+}

package/resources/pi-agent/extensions/pi-mcp-adapter/CHANGELOG.md

@@ -0,0 +1,192 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.2.0] - 2026-03-16
+
+### Added
+- **MCP UI Integration** - Support for the [MCP UI](https://github.com/MCP-UI-Org/mcp-ui) standard. Tools with `_meta.ui.resourceUri` open interactive UIs:
+  - Bidirectional AppBridge communication (tool calls, messages, context updates)
+  - Works with both stdio and HTTP MCP servers
+  - User consent management for tool calls from UI (configurable: never/once-per-server/always)
+  - Keyboard shortcuts: Cmd/Ctrl+Enter to complete, Escape to cancel
+  - UI prompts/intents trigger agent turns via `pi.sendMessage({ triggerTurn: true })`
+  - `mcp({ action: "ui-messages" })` retrieves accumulated messages from UI sessions
+
+- **Session reuse** - When the agent calls the same tool while its UI is already open, results push to the existing window instead of replacing it. Per-call stream IDs with independent sequences. Error results scoped to the individual call.
+
+- **Glimpse integration** - MCP UI opens in a native macOS WKWebView window instead of a browser tab when [Glimpse](https://github.com/hazat/glimpse) is installed (`pi install npm:glimpseui`). Falls back to browser on non-macOS or when unavailable. Override with `MCP_UI_VIEWER=browser` or `MCP_UI_VIEWER=glimpse`.
+
+- **Logger module** (`logger.ts`) - Centralized logging with levels (debug/info/warn/error), contextual child loggers, and `MCP_UI_DEBUG=1` env var.
+
+- **Error types** (`errors.ts`) - Structured errors with recovery hints: `ResourceFetchError`, `ResourceParseError`, `BridgeConnectionError`, `ConsentError`, `SessionError`, `ServerError`, and `wrapError()` helper.
+
+- **Test suite** - 178 tests covering consent manager, UI resource handler, host HTML template, logger, and error types.
+
+- **Interactive visualizer example** (`examples/interactive-visualizer`) - Minimal MCP server demonstrating charts (bar/line/pie/doughnut via Chart.js), bidirectional messaging, and streaming.
+
+### Fixed
+- Host-iframe timing: bridge now connects before loading iframe, fixing `ui/initialize` timeout on first load
+- All internal `log.info` calls demoted to `log.debug` to eliminate stdout noise during normal use
+
+### Technical Notes
+- Uses local minified AppBridge bundle (408KB) to avoid CDN Zod bundling issues
+- Serves app HTML from `/ui-app` endpoint instead of blob URLs to avoid iframe issues
+- SSE for real-time tool result streaming to browser
+
+## [2.1.2] - 2026-02-03
+
+### Changed
+- Added demo video and `pi.video` field to package.json for pi package browser.
+
+## [2.1.0] - 2026-02-02
+
+### Added
+- **Direct tool registration** - Promote specific MCP tools to first-class Pi tools via `directTools` config (per-server or global). Direct tools appear in the agent's tool list alongside builtins, so the LLM uses them without needing to search through the proxy first. Registers from cached metadata at startup — no server connections needed.
+- **`/mcp` interactive panel** - New TUI overlay replacing the text-based status dump. Shows server connection status, tool lists with direct/proxy toggles, token cost estimates, inline reconnect, and auth notices. Changes written to config on save.
+- **Auto-enriched proxy description** - The `mcp` proxy tool description now includes server names and tool counts from the metadata cache, so the LLM knows what's available without a search call (~30 extra tokens).
+- **`MCP_DIRECT_TOOLS` env var** - Subagent processes receive their direct tool configuration via environment variable, keeping subagents lean by default.
+- **First-run bootstrap** - Servers with `directTools` configured but no cache entry are connected during `session_start` to populate the cache. Direct tools become available after restart.
+- Config provenance tracking for correct write-back to user/project/import sources
+- Builtin name collision guard (skips direct tools that would shadow `read`, `write`, etc.)
+- Cross-server name deduplication for `prefix: "none"` and `prefix: "short"` modes
+
+## [2.0.1] - 2026-02-01
+
+### Fixed
+- Adapt execute signature to pi v0.51.0: add signal, onUpdate, ctx parameters
+
+## [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)
+
+## [1.5.0] - 2026-01-22
+
+### Changed
+- **BREAKING: `args` parameter is now a JSON string** - The `args` parameter which previously accepted an object now accepts a JSON string. This change was required for compatibility with Claude's Vertex AI API (`google-antigravity` provider) which rejects `patternProperties` in JSON schemas (generated by `Type.Record()`).
+
+### Added
+- **Type validation for args** - Parsed args are now validated to ensure they're a JSON object (not null, array, or primitive). Clear error messages for invalid input.
+- **`isError: true` on error responses** - JSON parse errors and type validation errors now properly set `isError: true` to indicate failure to the LLM.
+
+### Migration
+```typescript
+// Before (1.4.x)
+mcp({ tool: "my_tool", args: { key: "value" } })
+
+// After (1.5.0)
+mcp({ tool: "my_tool", args: '{"key": "value"}' })
+```
+
+## [1.4.1] - 2026-01-19
+
+### Changed
+
+- Status bar shows server count instead of tool count ("MCP: 5 servers")
+
+## [1.4.0] - 2026-01-19
+
+### Changed
+
+- **Non-blocking startup** - Pi starts immediately, MCP servers connect in background. First MCP call waits only if init isn't done yet.
+
+### Fixed
+
+- Tool metadata now includes `inputSchema` after `/mcp reconnect` (was missing, breaking describe and error hints)
+
+## [1.3.0] - 2026-01-19
+
+### Changed
+
+- **Parallel server connections** - All MCP servers now connect in parallel on startup instead of sequentially, significantly faster with many servers
+
+## [1.2.2] - 2026-01-19
+
+### Fixed
+
+- Installer now downloads from `main` branch (renamed from `master`)
+
+## [1.2.1] - 2026-01-19
+
+### Added
+
+- **npx installer** - Run `npx pi-mcp-adapter` to install (downloads files, installs deps, configures settings.json)
+
+## [1.1.0] - 2026-01-19
+
+### Changed
+
+- **Search includes schemas by default** - Search results now include parameter schemas, reducing tool calls needed (search + call instead of search + describe + call)
+- **Space-separated search terms match as OR** - `"navigate screenshot"` finds tools matching either word (like most search engines)
+- **Suppress server stderr by default** - MCP server logs no longer clutter terminal on startup
+- Use `includeSchemas: false` for compact output without schemas
+- Use `debug: true` per-server to show stderr when troubleshooting
+
+## [1.0.0] - 2026-01-19
+
+### Added
+
+- **Single unified `mcp` tool** with token-efficient architecture (~200 tokens vs ~15,000 for individual tools)
+- **Five operation modes:**
+  - `mcp({})` - Show server status
+  - `mcp({ server: "name" })` - List tools from a server
+  - `mcp({ search: "query" })` - Search tools by name/description
+  - `mcp({ describe: "tool_name" })` - Show tool details and parameter schema
+  - `mcp({ tool: "name", args: {...} })` - Call a tool
+- **Stdio transport** for local MCP servers (command + args)
+- **HTTP transport** with automatic fallback (StreamableHTTP → SSE)
+- **Config imports** from Cursor, Claude Code, Claude Desktop, VS Code, Windsurf, Codex
+- **Resource tools** - MCP resources exposed as callable tools
+- **OAuth support** - Token file-based authentication
+- **Bearer token auth** - Static or environment variable tokens
+- **Keep-alive connections** with automatic health checks and reconnection
+- **Schema on-demand** - Parameter schemas shown in `describe` mode and error responses
+- **Commands:**
+  - `/mcp` or `/mcp status` - Show server status
+  - `/mcp tools` - List all tools
+  - `/mcp reconnect` - Force reconnect all servers
+  - `/mcp-auth <server>` - Show OAuth setup instructions
+
+### Architecture
+
+- Tools stored in metadata map, not registered individually with Pi
+- MCP server validates arguments (no client-side schema conversion)
+- Reconnect callback updates metadata after auto-reconnect
+- Human-readable schema formatting for LLM consumption

package/resources/pi-agent/extensions/pi-mcp-adapter/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/resources/pi-agent/extensions/pi-mcp-adapter/README.md

@@ -0,0 +1,296 @@
+<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're paying that cost whether you use those tools or not. Connect a few servers and you've burned half your context window before the conversation starts.
+
+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. Servers only start when you actually use them.
+
+## Install
+
+```bash
+pi install npm:pi-mcp-adapter
+```
+
+Restart Pi after installation.
+
+## Quick Start
+
+Create `~/.pi/agent/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    }
+  }
+}
+```
+
+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" })
+```
+```
+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"}' })
+```
+
+Note: `args` is a JSON string, not an object.
+
+Two calls instead of 26 tools cluttering the context.
+
+## Config
+
+### Server Options
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "some-mcp-server"],
+      "lifecycle": "lazy",
+      "idleTimeout": 10
+    }
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `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 name |
+| `lifecycle` | `"lazy"` (default), `"eager"`, or `"keep-alive"` |
+| `idleTimeout` | Minutes before idle disconnect (overrides global) |
+| `exposeResources` | Expose MCP resources as tools (default: true) |
+| `directTools` | `true`, `string[]`, or `false` — register tools individually instead of through proxy |
+| `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) |
+| `directTools` | Global default for all servers (default: false). Per-server overrides this. |
+
+Per-server `idleTimeout` overrides the global setting.
+
+### Direct Tools
+
+By default, all MCP tools are accessed through the single `mcp` proxy tool. This keeps context small but means the LLM has to discover tools via search. If you want specific tools to show up directly in the agent's tool list — alongside `read`, `bash`, `edit`, etc. — add `directTools` to your config.
+
+Per-server:
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"],
+      "directTools": true
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "directTools": ["search_repositories", "get_file_contents"]
+    },
+    "huge-server": {
+      "command": "npx",
+      "args": ["-y", "mega-mcp@latest"]
+    }
+  }
+}
+```
+
+| Value | Behavior |
+|-------|----------|
+| `true` | Register all tools from this server as individual Pi tools |
+| `["tool_a", "tool_b"]` | Register only these tools (use original MCP names) |
+| Omitted or `false` | Proxy only (default) |
+
+To set a global default for all servers:
+
+```json
+{
+  "settings": {
+    "directTools": true
+  },
+  "mcpServers": {
+    "huge-server": {
+      "directTools": false
+    }
+  }
+}
+```
+
+Per-server `directTools` overrides the global setting. The example above registers direct tools for every server except `huge-server`.
+
+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. Restart Pi and they'll be available. To force it: `/mcp reconnect <server>` then restart.
+
+**Interactive configuration:** Run `/mcp` to open an interactive panel showing all servers with connection status, tools, and direct/proxy toggles. You can reconnect servers, initiate OAuth, and toggle tools between direct and proxy — all from one overlay. Changes are written to your config file; restart Pi to apply.
+
+**Subagent integration:** If you use the subagent extension, agents can request direct MCP tools in their frontmatter with `mcp:server-name` syntax. See the subagent README for details.
+
+### MCP UI Integration
+
+MCP servers can ship interactive UIs via the [MCP UI](https://github.com/MCP-UI-Org/mcp-ui) standard. When you call a tool that has a UI resource, the adapter opens it in a native macOS window via [Glimpse](https://github.com/hazat/glimpse) if available, otherwise falls back to the browser.
+
+**How it works:**
+
+1. Agent calls a tool like `launch_dashboard`
+2. The tool's metadata includes `_meta.ui.resourceUri` pointing to a UI resource
+3. pi-mcp-adapter fetches the UI HTML and opens it in an iframe
+4. The UI can call MCP tools and send messages back to the agent
+
+**Native rendering:** On macOS, if [Glimpse](https://github.com/hazat/glimpse) is installed (`pi install npm:glimpseui`), UIs open in a native WKWebView window instead of a browser tab. Set `MCP_UI_VIEWER=browser` to force the browser, or `MCP_UI_VIEWER=glimpse` to require native rendering.
+
+**Bidirectional communication:** The UI talks back. When it sends a prompt or intent, the message is stored and `triggerTurn()` wakes the agent. The agent retrieves messages via `mcp({ action: "ui-messages" })` and responds, enabling conversational UIs where the app and agent collaborate in real-time.
+
+**Session reuse:** When the agent calls the same tool again while its UI is already open, the adapter pushes the new result to the existing window instead of replacing it. This enables live updates — the agent can refine a chart, add data, or respond to user input without losing the current view. Different tools still replace the session as before.
+
+**Message types from UI:**
+
+| Type | Purpose |
+|------|---------|
+| `prompt` | User message that triggers an agent response |
+| `intent` | Structured action with name + params |
+| `notify` | Fire-and-forget notification |
+| `message` | Generic message payload |
+| (custom) | Any other type forwarded as intent |
+
+**Retrieving UI messages:**
+
+```
+mcp({ action: "ui-messages" })
+```
+
+Returns accumulated messages from UI sessions. Each message includes `type`, `sessionId`, `serverName`, `toolName`, and `timestamp`. Prompt messages include `prompt`, intent messages include `intent` and `params`.
+
+**Browser controls:**
+
+- **Cmd/Ctrl+Enter** — Complete and close
+- **Escape** — Cancel and close
+- **Done/Cancel buttons** — Same as keyboard shortcuts
+
+**Technical notes:**
+
+- Tool consent gates whether UIs can call MCP tools (never/once-per-server/always)
+- Works with both stdio and HTTP MCP servers
+- Uses a local 408KB AppBridge bundle (MCP SDK + Zod) for browser↔server communication
+
+### Local Example: Interactive Visualizer
+
+A minimal MCP UI example at `examples/interactive-visualizer` demonstrating charts, bidirectional messaging, and streaming. From that directory:
+
+```bash
+npm install
+npm run build
+npm run install-local
+```
+
+Restart pi, then ask the agent to show a chart — it calls `show_chart` and opens the UI in Glimpse (macOS) or the browser. Use `npm run uninstall-local` to remove the MCP entry.
+
+### Import Existing Configs
+
+Already have MCP set up elsewhere? Import it:
+
+```json
+{
+  "imports": ["cursor", "claude-code", "claude-desktop"],
+  "mcpServers": { }
+}
+```
+
+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"}' })` |
+| Connect | `mcp({ connect: "server-name" })` |
+| UI messages | `mcp({ action: "ui-messages" })` |
+
+Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. 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
+
+| Command | What it does |
+|---------|--------------|
+| `/mcp` | Interactive panel (server status, tool toggles, reconnect) |
+| `/mcp tools` | List all tools |
+| `/mcp reconnect` | Reconnect all servers |
+| `/mcp reconnect <server>` | Connect or reconnect a single server |
+| `/mcp-auth <server>` | OAuth setup |
+
+## How It Works
+
+- 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
+- Specific tools can be promoted from the proxy to first-class Pi tools via `directTools` config, so the LLM sees them directly instead of having to search
+
+## 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)