@sammorrowdrums/mcpi-ext 0.1.0

package/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.git
+.gitignore
+*.md
+.pi

package/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    groups:
+      dev-dependencies:
+        dependency-type: development
+        update-types:
+          - minor
+          - patch
+      production-dependencies:
+        dependency-type: production
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

package/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  models: read
+
+jobs:
+  ci:
+    name: Lint, Build & Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: jdx/mise-action@v4
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Lint
+        run: mise run lint
+
+      - name: Lint Dockerfile
+        uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: Dockerfile
+
+      - name: Check formatting
+        run: mise run format:check
+
+      - name: Type-check
+        run: mise run check
+
+      - name: Build
+        run: mise run build
+
+      - name: Test
+        run: mise run test
+
+      - name: MCP integration smoke test
+        run: mise run test:integration

package/.hadolint.yaml

@@ -0,0 +1,6 @@
+# hadolint configuration
+# DL3008: Pin versions in apt-get — not practical for a dev/e2e image
+# SC1091: Can't follow sourced file (/etc/os-release) — false positive
+ignored:
+  - DL3008
+  - SC1091

package/.prettierignore

@@ -0,0 +1,4 @@
+dist/
+node_modules/
+aube-lock.yaml
+*.tsbuildinfo

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/AGENTS.md

@@ -0,0 +1,118 @@
+# AGENTS.md
+
+## Tooling
+
+This project uses **mise** for tool version management and **npm** for package management. If you are an AI agent or new contributor, read this first.
+
+### mise (tool version manager)
+
+- **What:** [mise](https://mise.jdx.dev/) manages tool versions (node) and project tasks. Think asdf + direnv + make in one tool.
+- **Why:** Reproducible dev environments. `mise.toml` pins exact tool versions so every contributor and CI run uses the same stack.
+- **Install:** `curl https://mise.run | sh` then activate: `eval "$(~/.local/bin/mise activate bash)"`
+- **Usage:**
+  - `mise install` — install all tools from `mise.toml`
+  - `mise run <task>` — run a project task (build, test, dev, check, start)
+  - `mise use <tool>@<version>` — add/update a tool version
+
+### mcpi (coding agent)
+
+- **What:** [mcpi](https://github.com/SamMorrowDrums/mcpi) is an extensible terminal coding agent (fork of pi). This project builds extensions for it.
+- **Extension pattern:** Export a default function receiving `ExtensionAPI`, register tools/commands/hooks.
+- **Load extension:** `mcpi --extension ./dist/index.js`
+
+## Dev Loop
+
+```sh
+mise install         # one-time: install node
+npm install          # install npm dependencies
+mise run build       # compile TypeScript
+mise run test        # run tests
+mise run dev         # watch mode for development
+mise run check       # type-check only
+mise run lint        # lint TypeScript files
+mise run format      # auto-format code with Prettier
+mise run format:check # check formatting (CI mode)
+```
+
+## Project Structure
+
+```
+src/
+  index.ts             Extension entry point (lifecycle hooks, wiring)
+  mcp/                 MCP client management (connections, tool discovery)
+  skills/              Skill registry, discovery, gating, tool proxies
+  tool-cli/            tool-cli RPC server, client, CLI binary, prompt
+  test-servers/        Test MCP servers (weather, echo)
+dist/                  Compiled output (gitignored)
+scripts/               Integration and smoke test scripts
+mise.toml              Tool versions and tasks
+package.json           Dependencies and npm scripts
+tsconfig.json          TypeScript configuration
+```
+
+## Architecture
+
+### Tiered MCP Tool Access
+
+The extension provides three tiers for exposing MCP tools to the agent:
+
+| Tier          | Mechanism                                                          | When Used                                        |
+| ------------- | ------------------------------------------------------------------ | ------------------------------------------------ |
+| 1 — Skills    | `deferred: true` + `tool_call` gate → tools unlocked by load_skill | MCP server ships skills                          |
+| 2 — tool-cli  | CLI progressive discovery via shell                                | Ad-hoc exploration, no skills                    |
+| 3 — Code Mode | search+execute, no HITL                                            | Read-only tools with structured output (planned) |
+
+### tool-cli Architecture
+
+tool-cli is a thin CLI binary that communicates with the extension via JSON-RPC 2.0 over HTTP. The agent uses it as a standard shell command, composable with pipes, grep, jq, loops, etc.
+
+```
+Agent (mcpi)
+  │
+  │  shell exec
+  ▼
+tool-cli <server> <tool> '{"args"}'
+  │
+  │  HTTP JSON-RPC (localhost:7179)
+  ▼
+ToolCliRpcServer (in extension process)
+  │
+  │  MCP protocol (stdio/HTTP)
+  ▼
+MCP Server(s)
+```
+
+**Key design points:**
+
+- **No auth (temporary)** — the RPC server binds to `127.0.0.1` only, limiting access to the local machine. This is acceptable for development but not a finished security posture — any local process can call the server and execute MCP tools. Future work should add a shared secret or token (e.g. passed via environment variable to the CLI) so only the intended agent process can make calls.
+- **Interception point for HITL** — the RPC server's `callTool` method is the single choke point for all tool execution. Future work can check tool annotations (`readOnlyHint`, `destructiveHint`) here and gate non-read-only calls through user confirmation before forwarding to the MCP server.
+- **Progressive discovery** — the agent discovers servers → tools → schemas incrementally, paying only the tokens it needs.
+- **Shell-native** — plain text output composes with grep, jq, xargs, pipes, loops. The agent can chain tool calls using standard bash idioms.
+
+## Code Quality
+
+- **ESLint** — flat config with `typescript-eslint` (strict + stylistic) and Prettier compat
+- **Prettier** — auto-formatting (double quotes, semicolons, trailing commas, 100 char width)
+- **CI** — GitHub Actions runs lint → format:check → type-check → build → test on every PR
+- **Dependabot** — automated dependency updates (npm + GitHub Actions)
+
+Run `mise run lint` and `mise run format` before committing. CI will reject PRs that fail any check.
+
+**Before pushing**, always run:
+
+```sh
+mise run lint        # lint must pass
+mise run test        # tests must pass
+mise run format:check # formatting must pass
+```
+
+## Decision Log
+
+We maintain a [DECISIONS.md](DECISIONS.md) file recording key architectural and design decisions. Keep it up to date when making significant choices — add a new numbered entry with date, context, decision, and rationale.
+
+## Conventions
+
+- ESM (`"type": "module"`)
+- Target: ES2022, module: Node16
+- Strict TypeScript
+- Tests with vitest (co-located `*.test.ts` files)

package/DECISIONS.md

@@ -0,0 +1,99 @@
+# Decision Log
+
+Record of key architectural and design decisions. Keep this up to date as decisions are made.
+
+## 001 — Extension, not fork
+
+**Date:** 2026-04-23
+**Context:** Should we fork pi to build the MCP agent harness, or use the extension API?
+**Decision:** Build as a pi extension. The extension API provides everything we need: `registerTool()`, `setActiveTools()`, `on("tool_result", ...)`, `exec()`, lifecycle hooks.
+**Rationale:** Everything in scope (skill-gated tool visibility, football CLI, code mode, output offloading) is policy and orchestration — deciding _when_ and _how_ to expose MCP tools to the model. That's extension territory. We'd only need to fork if we needed to change pi's tool dispatch, context assembly, or model loop.
+
+## 002 — Agent harness controls tool visibility, not MCP servers
+
+**Date:** 2026-04-23
+**Context:** How do MCP tools become visible to the model?
+**Decision:** The harness (pi extension) decides what tools the model sees. MCP servers just expose their tools and optionally their skills. The harness holds all discovered tools internally and only sends them to the model when a skill names them.
+**Rationale:** Maximal agent capability, minimal tokens. The model's context window isn't stuffed with every tool from every connected MCP server. Tools appear only when a skill provides the context for using them.
+
+## 003 — Tiered access model
+
+**Date:** 2026-04-23
+**Context:** How should the model access MCP tools?
+**Decision:** Three tiers of access, all complementary:
+
+| Tier               | Mechanism                                                    | When Used                              |
+| ------------------ | ------------------------------------------------------------ | -------------------------------------- |
+| 1 — Skills (#1)    | Skill loaded → `allowed-tools` exact-matched → tools visible | MCP server ships skills                |
+| 2 — Football (#2)  | CLI progressive discovery → HITL for writes                  | Ad-hoc exploration, no skills          |
+| 3 — Code Mode (#4) | search+execute → no HITL                                     | Read-only tools with structured output |
+
+**Rationale:** Different situations call for different access patterns. Skills give direct access with workflow knowledge. Football gives interactive access with safety. Code mode gives autonomous access to safe operations at scale.
+
+## 004 — Large tool output offloading
+
+**Date:** 2026-04-23
+**Context:** Tool responses can be thousands of tokens, wasting context window.
+**Decision:** Intercept tool results via `pi.on("tool_result", ...)`. If output exceeds ~500 tokens, write to a file and return a pointer to the model.
+**Rationale:** Controls output token cost the same way skills/football/code-mode control input token cost. The model can read the file if it needs the content.
+
+## 005 — MCP SDK and JSON config for server connections
+
+**Date:** 2026-04-23
+**Context:** How should the extension connect to MCP servers?
+**Decision:** Use `@modelcontextprotocol/sdk` (TypeScript MCP SDK) with a JSON config file at `~/.config/mcpi-ext/mcp.json` (overridable via `--mcp-config` flag). The config supports two transport types: `stdio` (spawns a child process) and `remote` (Streamable HTTP). A `McpClientManager` class connects to all configured servers on `session_start`, discovers tools via `tools/list`, handles `notifications/tools/list_changed`, and disconnects on `session_shutdown`.
+**Rationale:** The official MCP SDK is the canonical way to implement MCP clients. JSON config aligns with VS Code and Claude Code conventions for MCP server configuration. Supporting both stdio and remote covers local dev servers and cloud-hosted MCP endpoints. Tools are discovered and stored internally but NOT registered with pi — the access tiers (Skills #1, Football #2, Code Mode #4) decide when to expose tools to the model.
+
+## 006 — CI model access via GITHUB_TOKEN
+
+**Date:** 2026-04-23
+**Context:** Can Pi's `github-copilot` provider use the Actions `GITHUB_TOKEN` for model inference in CI?
+**Decision:** Yes. The GitHub Models API (GA since April 2025) grants model inference to the Actions `GITHUB_TOKEN` when the workflow declares `permissions: models: read`. Pi's `--provider github-copilot` uses this same API. The CI workflow declares this permission so future e2e tests can run Pi with model access without a PAT.
+**Rationale:** Using the built-in `GITHUB_TOKEN` avoids storing secrets for CI model access. The `models: read` scope is the minimum required — no write access needed. This enables full trajectory e2e tests in CI (connect to MCP servers, run Pi agent, verify results).
+
+## 007 — Custom skill registry for MCP skills, not Pi's native skill system
+
+**Date:** 2026-04-23
+**Context:** Should MCP-discovered skills use Pi's built-in `loadSkills`/`formatSkillsForPrompt` pipeline (writing SKILL.md files to disk) or a custom in-extension registry?
+**Decision:** Custom `SkillRegistry` + `load_skill` tool + `formatMcpSkillsForPrompt`, styled after Pi's native skill system but fully self-contained in the extension. Skills are discovered from MCP `skill://` resources and injected into the system prompt via the `before_agent_start` hook.
+**Rationale:** MCP skills live on remote servers, not on disk. Writing them to temp files would be fragile and unnecessary. The custom approach keeps MCP skills self-contained, gives us full control over the activation → tool gating flow, and avoids coupling to Pi's internal skill loader. The XML format matches Pi's `<available_skills>` pattern so models already know how to interact with it.
+
+## 008 — Cache-safe progressive tool disclosure via `deferred` flag
+
+**Date:** 2026-05-11
+**Context:** When `load_skill` called `setActiveTools()` to reveal new tools, the tools array sent to the model changed, invalidating prompt cache. Decision 008 previously accepted this trade-off.
+**Decision:** Use `deferred: true` on MCP tool proxies with provider-native support and extension-level gating:
+
+1. **Anthropic:** pi-mono maps `deferred: true` to `defer_loading: true` in the API payload. Deferred tools stay in the tools array but are hidden from the model's view. Optional `tool_reference` content blocks can explicitly enable them on demand.
+2. **OpenAI Responses:** pi-mono maps `deferred: true` to `defer_loading: true` and auto-injects `{"type": "tool_search"}` into the tools array. The model discovers deferred tools automatically via hosted server-side search — no explicit activation needed. (OpenAI's client-executed `tool_search_output` is the equivalent of Anthropic's `tool_reference`, but hosted search is sufficient for our use case.)
+3. **All providers (fallback):** The extension's `tool_call` hook blocks premature calls to gated tools and returns an error message naming the relevant skill. After `load_skill` fires, tools are marked as enabled and calls go through.
+
+**Rationale:** Both Anthropic and OpenAI natively support `defer_loading` (tested with Claude Opus 4.7 and GPT-5.4). The tools array and system prompt stay constant throughout the conversation — prompt cache is fully preserved. The `tool_call` hook provides a provider-agnostic enforcement layer for providers without native `defer_loading` support.
+
+## 009 — tool-cli uses JSON-RPC 2.0 over HTTP on a predefined port
+
+**Date:** 2026-04-24
+**Context:** The Football CLI (issue #2) needs a communication protocol between the thin CLI binary and the extension that manages MCP connections.
+**Decision:** JSON-RPC 2.0 over HTTP on `localhost:7179` (overridable via `TOOL_CLI_PORT` env var). The RPC server lives in the extension, started on `session_start` and stopped on `session_shutdown`. The CLI binary (`tool-cli`) is a thin client that uses `fetch` to call the server. No new dependencies — uses Node's `http` module for the server and global `fetch` for the client.
+**Rationale:** JSON-RPC 2.0 is a standard, simple protocol that maps cleanly to the four operations needed (listServers, listTools, describeTool, callTool). HTTP is the simplest transport for request/response. A predefined port avoids coordination complexity for now. The architecture supports future HITL confirmation for non-read-only tools — the RPC server's `callTool` method is the single choke point where tool annotations can be checked and destructive calls gated through user approval.
+
+## 010 — tool-cli has no auth (known limitation)
+
+**Date:** 2026-04-24
+**Context:** The tool-cli RPC server listens on `127.0.0.1:7179` with no authentication. Any local process can discover and execute MCP tools through it.
+**Decision:** Accept this for now as a development convenience. The server is localhost-only, which limits the blast radius to local processes, but this is not a finished security posture. Before production use, add a shared secret (e.g. a one-time token passed via environment variable from the extension to the CLI) so only the intended agent process can make calls.
+**Rationale:** Adding auth now would complicate the initial implementation without changing the threat model much — the agent already has shell access and could call MCP tools through other means. But as the tool matures and especially once HITL gating is added for destructive tools, unauthenticated access would let other local processes bypass those safety checks. Auth is a prerequisite for trustworthy HITL.
+
+## 011 — Code mode uses `isolated-vm` for sandbox execution
+
+**Date:** 2026-04-24
+**Context:** Code mode (#4) lets the model write JavaScript to chain read-only MCP tool calls. The generated code runs in a sandbox. Options evaluated: Node `vm` module, `isolated-vm`, Deno subprocess, Cloudflare workerd, Pydantic/Python subprocess, WASM.
+**Decision:** Use `isolated-vm` (V8 isolates in Node.js). Provides memory limits (128MB default), CPU timeouts (30s default), and V8-level isolation. Tool dispatch via `Reference` async callbacks — actual MCP calls execute on the host, never in the sandbox.
+**Rationale:** Code mode has no HITL (human-in-the-loop) since all tools are read-only, making sandbox security important. Node's `vm` module is documented as "not a security mechanism" and is escapable via prototype pollution. `isolated-vm` provides genuine V8-level isolation with ~15ms overhead — negligible vs MCP network I/O. Deno subprocess (400ms/call) and workerd are too slow or complex for interactive use.
+
+## 012 — Code mode uses `ctx.eval` instead of `compileModule` for execution
+
+**Date:** 2026-04-24
+**Context:** Initial implementation used `isolate.compileModule()` + `module.evaluate()` for running sandboxed code with top-level await. Discovery: `module.evaluate()` resolves prematurely when multiple sequential `Reference.apply()` calls use `{ result: { promise: true } }` — the module evaluation promise resolves after the first async reference call, not after all code completes.
+**Decision:** Use `ctx.eval()` with `{ promise: true, copy: true }` instead. Wrap user code in an async IIFE that returns the final result.
+**Rationale:** `ctx.eval` with `promise: true` correctly awaits the full async IIFE, including all sequential tool dispatch calls. This is critical for code mode's chaining use case where the model writes for-loops calling multiple tools sequentially.

package/Dockerfile

@@ -0,0 +1,39 @@
+FROM node:22-slim
+
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    ripgrep \
+    ca-certificates \
+    gnupg \
+  && rm -rf /var/lib/apt/lists/*
+
+# Docker CLI (for Docker-in-Docker via mounted socket)
+RUN install -m 0755 -d /etc/apt/keyrings \
+  && curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
+  && chmod a+r /etc/apt/keyrings/docker.gpg \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
+     https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
+     > /etc/apt/sources.list.d/docker.list \
+  && apt-get update \
+  && apt-get install -y --no-install-recommends docker-ce-cli \
+  && rm -rf /var/lib/apt/lists/*
+
+# uv (Python package manager — for running Python-based MCP servers)
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+WORKDIR /app
+
+COPY package.json ./
+RUN npm install --ignore-scripts
+
+COPY tsconfig.json ./
+COPY src ./src
+RUN npx tsc
+
+COPY scripts/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+ENTRYPOINT ["docker-entrypoint.sh"]

package/README.md

@@ -0,0 +1,278 @@
+# mcpi-ext
+
+> **Experimental.** This extension implements progressive MCP tool discovery via skills for [mcpi](https://github.com/SamMorrowDrums/mcpi) (an experimental pi fork). Please only use this to try out the experiment on skills over MCP. See [progressive tool discovery docs](https://github.com/SamMorrowDrums/mcpi/blob/main/docs/progressive-tool-discovery.md) for details.
+
+![Three figures in a dark, Sandman-esque realm — The Skill Dealer, The Nuclear Football, and Codey C. Maude — standing before swirling constellations of MCP tool connections](images/banner.webp)
+
+> _They will tell you that MCP has a context problem. That the protocol gives too many tools, that the model drowns in schemas it doesn't need, that the cost of knowing everything is losing the ability to do anything well._
+>
+> _They are wrong._
+>
+> _MCP doesn't have a context problem. It has an imagination problem. The protocol already contains everything you need — `skill://` resources, tool annotations, `outputSchema`, progressive discovery. The pieces are all there, lying in the open like runes on a hillside. You just have to read them._
+>
+> _What follows is the story of three who did._
+
+---
+
+Building custom [MCP](https://modelcontextprotocol.io/) support as [mcpi](https://github.com/SamMorrowDrums/mcpi) extensions. This project implements **tiered progressive discovery** — three complementary strategies for exposing MCP tools to an AI agent, each paying only the context tokens it needs.
+
+| Tier          | Aspect                   | Mechanism                                             |
+| ------------- | ------------------------ | ----------------------------------------------------- |
+| 1 — Skills    | **The Skill Dealer**     | `skill://` resources gate tools via `allowed-tools`   |
+| 2 — tool-cli  | **The Nuclear Football** | CLI progressive discovery via shell                   |
+| 3 — Code Mode | **Codey C. Maude**       | Sandboxed JS over read-only tools with `outputSchema` |
+
+---
+
+## I. The Skill Dealer
+
+![A shadowy figure behind a table of glowing cards, each card inscribed with the name of an MCP tool](images/the-skill-dealer.webp)
+
+> _The Skill Dealer does not give you what you ask for. The Skill Dealer gives you what you need — and nothing more._
+
+MCP servers can ship `skill://` resources: SKILL.md files with frontmatter declaring which tools a skill gates. On connection, the extension discovers all skills and registers their tools with `deferred: true` — present in pi's tool registry but excluded from both the tools array sent to the model and the system prompt.
+
+This approach is **cache-preserving**: the tools array and system prompt stay constant throughout the conversation, so prompt cache is never invalidated by skill activation.
+
+### How deferred tool gating works
+
+Three mechanisms work together:
+
+1. **`deferred: true`** — MCP tool proxies are registered with this flag. Pi's runtime keeps them in the internal registry for execution dispatch (via `resolveTool`) but excludes them from the tools array and system prompt sent to the model.
+
+2. **Provider-native `defer_loading`** — Pi's providers map `deferred: true` to the native API parameter. Both Anthropic and OpenAI support this (tested with Claude Opus 4.7 and GPT-5.4). On Anthropic, `defer_loading` keeps the tool in the grammar but hidden from the model's view — the skill body naming the tools is sufficient for the model to call them. On OpenAI Responses, pi-mono auto-injects `{"type": "tool_search"}` and the model searches/loads deferred tools server-side.
+
+3. **`tool_call` hook gating** — The extension registers a `tool_call` event handler that blocks premature calls to skill-gated tools. If the model tries to call a gated tool before loading its skill, the handler returns an error: _"Tool X requires loading a skill first. Call load_skill with: Y"_. This creates a natural feedback loop and serves as the provider-agnostic enforcement layer.
+
+When the model invokes `load_skill`:
+
+1. The skill's SKILL.md is read from the MCP server and returned as workflow instructions
+2. The skill's `allowedTools` are added to the `enabledTools` set, unblocking the `tool_call` gate
+3. The model can now call the tools — it discovers them from the skill body (which names them) and the provider's grammar
+
+```mermaid
+sequenceDiagram
+    participant Model
+    participant load_skill
+    participant SkillRegistry
+    participant MCP Server
+    participant tool_call gate
+
+    Model->>load_skill: load_skill("github-pr")
+    load_skill->>SkillRegistry: Look up skill
+    SkillRegistry-->>load_skill: skill metadata + allowed-tools
+    load_skill->>MCP Server: Read skill://github-pr
+    MCP Server-->>load_skill: SKILL.md body
+    load_skill->>tool_call gate: Enable allowed-tools
+    load_skill-->>Model: Return workflow instructions
+    Note over Model: Skill body names the tools.<br/>Model calls them via tool_use.
+    Model->>tool_call gate: create_pull_request(...)
+    tool_call gate-->>Model: ✓ Allowed (skill loaded)
+```
+
+This is self-referential enablement: **the MCP server itself declares how its tools should be discovered**. The harness holds all the tools as deferred. The skill decides which ones the model can access. The model gets instructions in one atomic operation, paying only the tokens for the skills it actually loads — and the prompt cache stays intact.
+
+The context window stays clean. The tools appear exactly when the model has the context to use them well. And prompt cache is preserved because neither the tools array nor the system prompt changes.
+
+Anthropic's [tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) solves a similar problem from the model side — deferring tool loading to avoid cache invalidation from large tool lists. Our approach uses Anthropic's native `defer_loading` parameter (when available) combined with extension-level `tool_call` gating for provider-agnostic safety. Where tool search has the model _pull_ tools on demand, skill invocation _pushes_ them: when `load_skill` fires, the skill's tools are unblocked and the model gets workflow instructions. The model doesn't search for tools — the right tools arrive because the skill declared them.
+
+> _"What you do not need to know," said the Skill Dealer, shuffling the deck, "you will not be burdened with knowing."_
+
+---
+
+## II. The Nuclear Football
+
+![A glowing briefcase marked 'tool-cli' being passed between hands in a dark corridor, trailing sparks of shell commands](images/nuclear-mcp-football.webp)
+
+> _The Football is not a weapon. The Football is the authority to use weapons. Whoever holds it can reach any server, call any tool, chain any result — but they must do so deliberately, one command at a time._
+
+`tool-cli` is a thin CLI binary that speaks JSON-RPC 2.0 to the extension over HTTP. The agent uses it like any shell command — composable with pipes, grep, jq, loops, and all the bash idioms it already knows.
+
+```mermaid
+flowchart TD
+    A["Agent (mcpi)"] -->|shell exec| B["tool-cli &lt;server&gt; &lt;tool&gt; '{args}'"]
+    B -->|"HTTP JSON-RPC (localhost:7179)"| C["ToolCliRpcServer (in extension)"]
+    C -->|"MCP protocol (stdio/HTTP)"| D["MCP Server(s)"]
+```
+
+Discovery is **progressive** — the agent pays only the tokens it needs:
+
+```sh
+tool-cli --help                              # What servers exist?
+tool-cli github                              # What tools does this server have?
+tool-cli github search_code                  # What's the schema for this tool?
+tool-cli github search_code '{"query":"auth"}' # Call it
+```
+
+And because it's shell-native, the agent gets bash superpowers for free:
+
+```sh
+# Chain tool calls
+tool-cli myserver list_items '{}' | jq -r '.[0].id' | \
+  xargs -I{} tool-cli myserver get_item '{"id":"{}"}'
+
+# Process collections
+for city in London Tokyo Paris; do
+  echo "=== $city ==="
+  tool-cli weather check_weather '{"city":"'"$city"'"}'
+done
+
+# Combine with the Unix toolbox
+tool-cli myserver export_csv '{"table":"users"}' | sort -t, -k2 | head -20
+```
+
+The RPC server is the single choke point for all tool execution — the natural interception point for human-in-the-loop confirmation on destructive operations.
+
+> _They pass the Football from hand to hand. It is heavy with potential. Every tool on every server is one command away — but you must type the command yourself._
+
+---
+
+## III. Codey C. Maude
+
+![A luminous figure composed of flowing code, sitting cross-legged in a V8 isolate bubble, reading structured data from floating JSON schemas](images/code-c-maude.webp)
+
+> _Codey does not ask permission. Codey does not need to. Everything Codey touches is read-only, every result is typed, and the sandbox cannot be escaped. Codey is safe by construction._
+
+Code Mode is for the tools that are **read-only** (`annotations.readOnlyHint === true`) and return **structured output** (`outputSchema` defined). These two properties together make a tool safe for autonomous use — it can't modify anything, and its results are machine-parseable.
+
+The model writes JavaScript that chains these tools:
+
+```javascript
+// Executed in a V8 isolate via isolated-vm
+const issues = await codemode.list_issues({ repo: "owner/repo", state: "open" });
+const critical = issues.filter((i) => i.labels.includes("critical"));
+const details = await Promise.all(critical.map((i) => codemode.get_issue({ number: i.number })));
+return details.map((d) => ({ title: d.title, assignee: d.assignee }));
+```
+
+The sandbox runs in `isolated-vm` — genuine V8-level isolation:
+
+- **128MB memory limit**, 30-second timeout
+- **No access** to filesystem, network, or Node.js APIs
+- Tool calls dispatch to the host via `Reference` callbacks — MCP execution happens outside the sandbox
+- ~15ms overhead, negligible vs network I/O
+
+Two tools expose this to the model:
+
+| Tool           | Purpose                                                                            |
+| -------------- | ---------------------------------------------------------------------------------- |
+| `code_search`  | Discover available tools — `codemode.listTools()`, `codemode.describeTools(names)` |
+| `code_execute` | Chain tool calls — write JS that calls `codemode.toolName(args)`                   |
+
+> _"I can see everything," Codey said, eyes reflecting infinite JSON. "I just can't touch it. That's the point. That's why they trust me."_
+
+---
+
+## The Architecture
+
+The three tiers are complementary. Skills give curated access with workflow knowledge. The Football gives interactive access with safety. Code Mode gives autonomous access to safe operations at scale.
+
+```mermaid
+flowchart TD
+    subgraph mcpi["mcpi (agent)"]
+        T1["load_skill\n(Tier 1 — Skills)"]
+        T2["tool-cli\n(Tier 2 — Football)"]
+        T3["code_search / code_execute\n(Tier 3 — Code Mode)"]
+        MCM["McpClientManager\n(MCP SDK — stdio & Streamable HTTP)"]
+        T1 --> MCM
+        T2 --> MCM
+        T3 --> MCM
+    end
+    MCM --> S1["MCP Server"]
+    MCM --> S2["MCP Server"]
+    MCM --> S3["MCP Server"]
+```
+
+The harness controls what the model sees. MCP servers just expose their tools and skills. The extension decides _when_ and _how_ to reveal them.
+
+> _MCP doesn't have a context problem. It never did. It was just waiting for someone to imagine the right way to read the runes._
+
+---
+
+## Quick Start
+
+### Install from npm
+
+```sh
+npm install @sammorrowdrums/mcpi @sammorrowdrums/mcpi-ext
+```
+
+Run mcpi with the extension:
+
+```sh
+npx mcpi --extension node_modules/@sammorrowdrums/mcpi-ext/dist/index.js \
+  --mcp-config ~/.config/mcpi-ext/mcp.json
+```
+
+### Local development
+
+```sh
+curl https://mise.run | sh                       # install mise
+eval "$(~/.local/bin/mise activate bash)"         # activate
+mise install                                      # install node
+npm install                                       # install dependencies
+mise run build                                    # build
+mise run test                                     # test
+```
+
+For local dev, override the `@sammorrowdrums/mcpi` dependency to point at your local mcpi clone:
+
+```json
+// package.json overrides (not committed)
+"devDependencies": {
+  "@sammorrowdrums/mcpi": "file:../path/to/mcpi/packages/coding-agent"
+}
+```
+
+Then load the extension from the built output:
+
+```sh
+mcpi --extension ./dist/index.js --mcp-config ~/.config/mcpi-ext/mcp.json
+```
+
+### MCP server configuration
+
+Create `~/.config/mcpi-ext/mcp.json` (or pass `--mcp-config /path/to/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "xxx"
+      }
+    },
+    "my-remote-server": {
+      "type": "remote",
+      "url": "https://my-mcp-server.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer xxx"
+      }
+    }
+  }
+}
+```
+
+Each server can be `stdio` (spawns a child process) or `remote` (Streamable HTTP). The extension connects to all configured servers on startup, discovers their tools, and gates them via skills.
+
+See [AGENTS.md](AGENTS.md) for full tooling docs, dev loop, and architecture details.
+
+## Project Structure
+
+```
+src/
+  index.ts             Extension entry point (lifecycle hooks, wiring)
+  mcp/                 MCP client management (connections, tool discovery)
+  skills/              Skill registry, discovery, gating, tool proxies
+  tool-cli/            tool-cli RPC server, client, CLI binary, prompt
+  code-mode/           V8 sandbox executor, eligibility, type hints
+  test-servers/        Test MCP servers (weather, echo)
+images/                Banner and character art
+```
+
+## License
+
+See repository for license details.