@sammorrowdrums/mcpi-ext 0.1.0 → 0.2.0

package/.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
         run: mise run lint
 
       - name: Lint Dockerfile
-        uses: hadolint/hadolint-action@v3.1.0
+        uses: hadolint/hadolint-action@v3.3.0
         with:
           dockerfile: Dockerfile
 

package/README.md

@@ -1,6 +1,16 @@
 # 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.
+> **Experimental.** This extension implements progressive MCP tool discovery via skills for [mcpi](https://github.com/SamMorrowDrums/mcpi) (an experimental pi fork). See the [skills-as-groups proposal](https://github.com/modelcontextprotocol/experimental-ext-grouping/pull/13) for the proposed MCP spec addition, and the [progressive tool discovery docs](https://github.com/SamMorrowDrums/mcpi/blob/main/docs/progressive-tool-discovery.md) for implementation details.
+
+```sh
+npm install -g @sammorrowdrums/mcpi@latest @sammorrowdrums/mcpi-ext@latest @sammorrowdrums/tool-cli@latest
+mcpi --extension $(npm root -g)/@sammorrowdrums/mcpi-ext/dist/index.js \
+  --mcp-config ~/.config/mcpi-ext/mcp.json
+```
+
+See [Quick Start](#quick-start) for MCP server configuration.
+
+---
 
 ![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)
 
@@ -30,143 +40,85 @@ Building custom [MCP](https://modelcontextprotocol.io/) support as [mcpi](https:
 
 > _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.
+MCP servers ship `skill://` resources — SKILL.md files declaring which tools a skill gates. The extension discovers skills on connection and registers their tools with `deferred: true`: present in the registry for dispatch but hidden from the model and the prompt. **Cache is preserved** — neither the tools array nor the system prompt ever changes.
 
-### How deferred tool gating works
+When the model calls `load_skill`, the skill's instructions arrive and its tools are unblocked. The model discovers tools from the skill body and can call them immediately. The MCP server itself declares how its tools should be discovered.
 
-Three mechanisms work together:
+📖 [**How it works →**](docs/skills.md) — deferred gating, `defer_loading` provider support, `tool_call` hook enforcement.
 
-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.
+> _"What you do not need to know," said the Skill Dealer, shuffling the deck, "you will not be burdened with knowing."_
 
-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.
+![Skills enabling MCP tools — the model loads a skill and gains access to gated tools](images/skills-enabling-mcp-tools.png)
 
-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`:
+## II. The Nuclear Football
 
-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
+![A glowing briefcase marked 'tool-cli' being passed between hands in a dark corridor, trailing sparks of shell commands](images/nuclear-mcp-football.webp)
 
-```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)
-```
+> _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._
 
-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.
+[`tool-cli`](https://github.com/SamMorrowDrums/tool-cli) is a thin CLI binary that speaks JSON-RPC to the extension. The agent uses it like any shell command — composable with pipes, grep, jq, loops. Discovery is progressive: server list → tool list → schema → call. Each step pays only the tokens it needs.
 
-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.
+📖 [**How it works →**](docs/tool-cli.md) — architecture, progressive discovery, shell composability.
+📦 [**Standalone package →**](https://github.com/SamMorrowDrums/tool-cli) — `ToolProvider` interface, server, and implementor guidance for other languages.
 
-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.
+> _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._
 
-> _"What you do not need to know," said the Skill Dealer, shuffling the deck, "you will not be burdened with knowing."_
+![tool-cli in action — progressive discovery piped through grep](images/tool-cli-grep.png)
 
 ---
 
-## 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)"]
-```
+## III. Codey C. Maude
 
-Discovery is **progressive** — the agent pays only the tokens it needs:
+![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)
 
-```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
-```
+> _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._
 
-And because it's shell-native, the agent gets bash superpowers for free:
+Code Mode targets **read-only** tools with **structured output**. The model writes JavaScript that chains MCP tool calls inside a V8 isolate — memory-limited, time-limited, no filesystem or network access. Perfect for pagination loops, aggregation, and joins across many calls.
 
-```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
-```
+📖 [**How it works →**](docs/code-mode.md) — sandbox isolation, eligibility, tool dispatch.
 
-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.
+> _"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."_
 
-> _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._
+![Code Mode in action — chaining MCP tools in a V8 sandbox to build a histogram](images/code-mode-histogram.png)
 
 ---
 
-## III. Codey C. Maude
+## When to Use Each Tier
 
-![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)
+> _They asked the three: "Why are there three of you? Isn't one enough?"_
+>
+> _The Skill Dealer laid down a card. "When you know the ritual — the steps, the order, the tools that belong together — you come to me. I give you the ceremony whole."_
+>
+> _The Football's briefcase clicked open. "When you need one answer, quickly, and you know what you're looking for — you reach for me. I'm a shell command. I compose."_
+>
+> _Codey smiled, cross-legged in the isolate. "And when the answer is buried in nine pages of data, when you need loops and math and joins across a thousand records — you write the code, and I run it. Safely."_
+>
+> _"Three is not redundancy," said the Skill Dealer. "Three is completeness."_
 
-> _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._
+**The Skill Dealer** — when there's a curated workflow for the domain task. "Triage these 20 issues" means loading the triage skill, which gives you the right tools _plus_ the workflow instructions (dedup checks, labeling conventions, close criteria). Re-deriving that from raw tool calls is wasteful and error-prone.
 
-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 Nuclear Football** — one-shot or exploratory calls, especially when piping through Unix tools. `tool-cli github search_code '{"query":"auth"}' | jq '.items[].path'` — one call, pipe to jq, done. Also perfect for discovering what's on a server you haven't used before.
 
-The model writes JavaScript that chains these tools:
+**Codey C. Maude** — when you need real computation across many calls: pagination loops, aggregation, joining results, math. 876 issues across 9 pages, counting labels per issue, summing into a histogram — that's a loop with state. Doing it via tool-cli would mean 9 separate calls plus shell-side aggregation. Fragile. Codey does it in one sandbox execution.
 
-```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 }));
-```
+### A single task using all three
 
-The sandbox runs in `isolated-vm` — genuine V8-level isolation:
+> _"Triage the backlog of github/github-mcp-server: find stale bugs older than 90 days with no recent activity, summarize patterns, and close obvious duplicates."_
 
-- **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
+1. **Codey** paginated all open bug issues, filtered by `updated < 90d ago`, grouped by label and keyword to find clusters. Computation across many pages — this is what sandboxes are for.
 
-Two tools expose this to the model:
+2. **The Football** spot-checked suspect issues. `tool-cli github get_issue '{"number":42}'` piped through `jq` to eyeball specific fields. Quick, ad-hoc, composable.
 
-| Tool           | Purpose                                                                            |
-| -------------- | ---------------------------------------------------------------------------------- |
-| `code_search`  | Discover available tools — `codemode.listTools()`, `codemode.describeTools(names)` |
-| `code_execute` | Chain tool calls — write JS that calls `codemode.toolName(args)`                   |
+3. **The Skill Dealer** loaded `triage-issues` to actually close the duplicates — following the project's triage workflow with correct labels, comment templates, and close reasons. The ceremony, performed correctly.
 
-> _"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 rule of thumb is simple: skill for workflows, tool-cli for one-shots, code_execute for computation. The three are not competing. They are collaborating._
 
 ---
 
 ## 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)"]
@@ -185,66 +137,62 @@ flowchart TD
 
 The harness controls what the model sees. MCP servers just expose their tools and skills. The extension decides _when_ and _how_ to reveal them.
 
+### Every call flows through the harness
+
+All three tiers route MCP tool calls back through the extension process. This is a subtle but important property: even when the model writes sandboxed JavaScript (Code Mode) or shells out to `tool-cli`, the actual MCP call happens in the harness. This means:
+
+- **Every tool invocation appears in the agent log** — skills, tool-cli one-shots, and Code Mode sandbox calls alike. Full observability without instrumentation.
+- **Human-in-the-loop can be added at one point** — the `McpClientManager` is the single choke point. Future work can check tool annotations (`readOnlyHint`, `destructiveHint`) and gate destructive calls through user confirmation, regardless of which tier initiated 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:
+### 1. Install
 
 ```sh
-npx mcpi --extension node_modules/@sammorrowdrums/mcpi-ext/dist/index.js \
-  --mcp-config ~/.config/mcpi-ext/mcp.json
+npm install -g @sammorrowdrums/mcpi@latest @sammorrowdrums/mcpi-ext@latest @sammorrowdrums/tool-cli@latest
 ```
 
-### Local development
+### 2. Configure MCP servers
 
-```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:
+Create `~/.config/mcpi-ext/mcp.json`:
 
 ```json
-// package.json overrides (not committed)
-"devDependencies": {
-  "@sammorrowdrums/mcpi": "file:../path/to/mcpi/packages/coding-agent"
+{
+  "mcpServers": {
+    "github": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server:skill-discovery",
+        "stdio"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "xxx"
+      }
+    }
+  }
 }
 ```
 
-Then load the extension from the built output:
+Replace `xxx` with your [GitHub personal access token](https://github.com/settings/tokens). See [github/github-mcp-server](https://github.com/github/github-mcp-server) for the standard server.
 
-```sh
-mcpi --extension ./dist/index.js --mcp-config ~/.config/mcpi-ext/mcp.json
-```
-
-### MCP server configuration
+> **Note:** The `skill-discovery` tag includes experimental `skill://` resources that enable Tier 1 progressive discovery. The standard `ghcr.io/github/github-mcp-server` image works too — tool-cli (Tier 2) and Code Mode (Tier 3) function with any MCP server, but skill-gated tool activation requires `skill://` resources.
 
-Create `~/.config/mcpi-ext/mcp.json` (or pass `--mcp-config /path/to/config.json`):
+You can add more servers — both `stdio` (spawns a process) and `remote` (Streamable HTTP) are supported:
 
 ```json
 {
   "mcpServers": {
-    "github": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "xxx"
-      }
-    },
+    "github": { "...": "..." },
     "my-remote-server": {
       "type": "remote",
       "url": "https://my-mcp-server.example.com/mcp",
@@ -256,7 +204,28 @@ Create `~/.config/mcpi-ext/mcp.json` (or pass `--mcp-config /path/to/config.json
 }
 ```
 
-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.
+### 3. Run
+
+```sh
+mcpi --extension $(npm root -g)/@sammorrowdrums/mcpi-ext/dist/index.js \
+  --mcp-config ~/.config/mcpi-ext/mcp.json
+```
+
+### Local development
+
+```sh
+git clone https://github.com/SamMorrowDrums/mcpi-ext.git
+cd mcpi-ext
+npm install
+npm run build
+npm test
+```
+
+Then run with your local build:
+
+```sh
+mcpi --extension ./dist/index.js --mcp-config ~/.config/mcpi-ext/mcp.json
+```
 
 See [AGENTS.md](AGENTS.md) for full tooling docs, dev loop, and architecture details.
 
@@ -270,7 +239,8 @@ src/
   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
+docs/                  Detailed mechanism documentation
+images/                Banner, character art, and screenshots
 ```
 
 ## License

package/docs/code-mode.md

@@ -0,0 +1,38 @@
+# Tier 3 — Codey C. Maude (Code Mode)
+
+Code Mode targets 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.
+
+## How it works
+
+The model writes JavaScript that chains MCP tool calls. The code runs in a V8 isolate via `isolated-vm`:
+
+```javascript
+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 }));
+```
+
+## Sandbox 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
+
+## Tools
+
+| Tool           | Purpose                                                                            |
+| -------------- | ---------------------------------------------------------------------------------- |
+| `code_search`  | Discover available tools — `codemode.listTools()`, `codemode.describeTools(names)` |
+| `code_execute` | Chain tool calls — write JS that calls `codemode.toolName(args)`                   |
+
+## When to use
+
+Code Mode shines when you need real computation across many calls: pagination loops, aggregation, joining results, math. For example:
+
+- 876 issues across 9 pages, counting labels per issue, building a histogram
+- For each open PR, fetch reviews and compute average time-to-first-review
+- Paginate all items, filter, group, and summarize
+
+See [DECISIONS.md #011–012](../DECISIONS.md) for implementation decisions.

package/docs/skills.md

@@ -0,0 +1,57 @@
+# Tier 1 — The Skill Dealer
+
+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`.
+
+## How deferred tool gating works
+
+Three mechanisms work together to keep tools hidden until the right moment — while preserving prompt cache:
+
+### 1. `deferred: true`
+
+MCP tool proxies are registered with this flag. mcpi keeps them in the tools array (so providers can include them in grammar/dispatch) but excludes them from the system prompt. The tools array stays static throughout the conversation — prompt cache is never invalidated.
+
+### 2. Provider-native `defer_loading`
+
+mcpi's providers map `deferred: true` to their native deferred loading mechanism:
+
+- **Anthropic** — `defer_loading: true` hides the tool from the model's view while keeping it in the grammar.
+- **OpenAI Responses** — `defer_loading: true` with auto-injected `{"type": "tool_search"}` enables server-side tool discovery.
+
+Both tested with Claude Opus 4.7 and GPT-5.4. Since the tools array never changes, prompt cache is preserved on both providers.
+
+### 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 enforcement layer across all providers — including those without native `defer_loading` support.
+
+## Flow
+
+```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)
+```
+
+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.
+
+## See also
+
+- [skills-as-groups MCP spec proposal](https://github.com/modelcontextprotocol/experimental-ext-grouping/pull/13)
+- [DECISIONS.md #008](../DECISIONS.md) — cache-safe progressive tool disclosure

package/docs/tool-cli.md

@@ -0,0 +1,54 @@
+# Tier 2 — The Nuclear Football (tool-cli)
+
+`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.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A["Agent (mcpi)"] -->|shell exec| B["tool-cli <server> <tool> '{args}'"]
+    B -->|"HTTP JSON-RPC (random port, token auth)"| C["ToolCliServer (from @sammorrowdrums/tool-cli)"]
+    C -->|"MCP protocol (stdio/HTTP)"| D["MCP Server(s)"]
+```
+
+The RPC server lives in the extension process, started on `session_start` and stopped on `session_shutdown`. The CLI binary uses `fetch` to call it.
+
+## Progressive discovery
+
+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
+```
+
+## Shell composability
+
+```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
+```
+
+## Security
+
+The server uses token-based auth and dynamic port allocation (provided by [`@sammorrowdrums/tool-cli`](https://github.com/SamMorrowDrums/tool-cli)):
+
+1. `start()` binds to a random port and generates a 32-byte session token
+2. Returns `{ port, token }` — the extension sets these as env vars via `pi.setEnv()`
+3. Every request must include `Authorization: Bearer <token>` — rejected with 401 otherwise
+
+This enables concurrent sessions and prevents random processes from calling MCP tools. The RPC server is the single choke point for all tool execution — the natural interception point for future human-in-the-loop confirmation on destructive operations.
+
+See [tool-cli security docs](https://github.com/SamMorrowDrums/tool-cli#security) and [DECISIONS.md #010](../DECISIONS.md).

package/mise.toml

@@ -3,19 +3,7 @@ node = "22"
 
 [tasks.build]
 description = "Build TypeScript"
-run = [
-  "npx tsc",
-  "chmod +x dist/tool-cli/cli.js",
-]
-
-[tasks."install:tool-cli"]
-description = "Symlink tool-cli binary for local use"
-depends = ["build"]
-run = [
-  "ln -sf ../../dist/tool-cli/cli.js node_modules/.bin/tool-cli",
-  "mkdir -p ~/.local/bin",
-  "ln -sf $PWD/dist/tool-cli/cli.js ~/.local/bin/tool-cli",
-]
+run = "npx tsc"
 
 [tasks.dev]
 description = "Watch mode"

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@sammorrowdrums/mcpi-ext",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@sammorrowdrums/tool-cli": "^0.3.0",
     "isolated-vm": "^6.1.2",
     "typebox": "^1.1.31",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@sammorrowdrums/mcpi": ">=0.70.0"
+    "@sammorrowdrums/mcpi": ">=0.70.9"
   },
   "devDependencies": {
-    "@sammorrowdrums/mcpi": "file:../../../repos/pi-mono/packages/coding-agent",
     "@eslint/js": "^10.0.1",
+    "@sammorrowdrums/mcpi": "^0.70.9",
     "@types/node": "^25.6.0",
     "eslint": "^10.2.1",
     "eslint-config-prettier": "^10.1.8",
@@ -39,8 +40,5 @@
   "license": "MIT",
   "main": "./dist/index.js",
   "type": "module",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "tool-cli": "./dist/tool-cli/cli.js"
-  }
+  "types": "./dist/index.d.ts"
 }