@sammorrowdrums/mcpi-ext 0.2.0 → 0.2.1

package/docs/code-mode.md

@@ -1,38 +0,0 @@
-# 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

@@ -1,57 +0,0 @@
-# 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

@@ -1,54 +0,0 @@
-# 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/eslint.config.js

@@ -1,27 +0,0 @@
-import eslint from "@eslint/js";
-import tseslint from "typescript-eslint";
-import eslintConfigPrettier from "eslint-config-prettier";
-
-export default tseslint.config(
-  eslint.configs.recommended,
-  ...tseslint.configs.strict,
-  ...tseslint.configs.stylistic,
-  eslintConfigPrettier,
-  {
-    languageOptions: {
-      parserOptions: {
-        projectService: true,
-        tsconfigRootDir: import.meta.dirname,
-      },
-    },
-    rules: {
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
-      ],
-    },
-  },
-  {
-    ignores: ["dist/", "node_modules/", "*.js", "scripts/"],
-  },
-);

package/mise.toml

@@ -1,53 +0,0 @@
-[tools]
-node = "22"
-
-[tasks.build]
-description = "Build TypeScript"
-run = "npx tsc"
-
-[tasks.dev]
-description = "Watch mode"
-run = "npx tsc --watch"
-
-[tasks.test]
-description = "Run tests"
-run = "npx vitest --run"
-
-[tasks.check]
-description = "Type-check without emitting"
-run = "npx tsc --noEmit"
-
-[tasks.lint]
-description = "Lint TypeScript files"
-run = "npx eslint ."
-
-[tasks.format]
-description = "Format code with Prettier"
-run = "npx prettier --write ."
-
-[tasks."format:check"]
-description = "Check code formatting"
-run = "npx prettier --check ."
-
-[tasks.start]
-description = "Run the built project"
-run = "node dist/index.js"
-
-[tasks.docker-build]
-description = "Build the Docker e2e image"
-run = "docker build -t mcpi-ext-e2e ."
-
-[tasks."test:integration"]
-description = "Run MCP integration smoke test"
-depends = ["build"]
-run = "node scripts/test-mcp-integration.mjs"
-
-[tasks."test:tool-cli"]
-description = "Run tool-cli smoke test (requires build)"
-depends = ["build"]
-run = "node scripts/test-tool-cli-smoke.mjs"
-
-[tasks."test:skill-integration"]
-description = "Run skill discovery integration test (requires build)"
-depends = ["build"]
-run = "npx vitest run src/skills/skill-integration.test.ts"

package/scripts/docker-entrypoint.sh

@@ -1,29 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-if [ -z "${GITHUB_TOKEN:-}" ]; then
-  echo "ERROR: GITHUB_TOKEN environment variable is required" >&2
-  exit 1
-fi
-
-if [ $# -eq 0 ]; then
-  echo "ERROR: No task provided. Pass the task as arguments." >&2
-  echo "Usage: docker run -e GITHUB_TOKEN=... IMAGE \"your task here\"" >&2
-  exit 1
-fi
-
-TASK="$*"
-
-PI_ARGS=(
-  -e /app/dist/index.js
-  --provider github-copilot
-  --mode json
-  -p
-  --no-session
-)
-
-if [ -n "${PI_MODEL:-}" ]; then
-  PI_ARGS+=(--model "$PI_MODEL")
-fi
-
-exec npx pi "${PI_ARGS[@]}" "$TASK"

package/scripts/test-echo-server.mjs

@@ -1,28 +0,0 @@
-#!/usr/bin/env node
-/**
- * Minimal MCP server for integration testing.
- * Exposes a single "echo" tool that returns its input.
- */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-
-const server = new McpServer({
-  name: "test-echo-server",
-  version: "0.1.0",
-});
-
-server.registerTool(
-  "echo",
-  {
-    description: "Echoes back the input message",
-    inputSchema: { message: z.string() },
-    annotations: { readOnlyHint: true },
-  },
-  async ({ message }) => ({
-    content: [{ type: "text", text: message }],
-  }),
-);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);

package/scripts/test-mcp-integration.mjs

@@ -1,59 +0,0 @@
-#!/usr/bin/env node
-/**
- * Integration smoke test: connect to the test-echo-server via stdio,
- * discover tools, call the echo tool, disconnect, exit 0.
- */
-import { McpClientManager } from "../dist/mcp/client-manager.js";
-
-const manager = new McpClientManager();
-
-try {
-  await manager.connectAll(
-    {
-      mcpServers: {
-        "test-echo": {
-          type: "stdio",
-          command: "node",
-          args: ["scripts/test-echo-server.mjs"],
-        },
-      },
-    },
-    (msg) => console.log(msg),
-  );
-
-  const servers = manager.getConnectedServers();
-  if (servers.length !== 1) {
-    throw new Error(`Expected 1 server, got ${servers.length}`);
-  }
-
-  const tools = manager.getTools();
-  console.log(`Discovered ${tools.length} tool(s): ${tools.map((t) => t.name).join(", ")}`);
-
-  const echoTool = tools.find((t) => t.name === "echo");
-  if (!echoTool) {
-    throw new Error('Expected to find "echo" tool');
-  }
-
-  // Call the tool via the client
-  const client = manager.getClient("test-echo");
-  if (!client) throw new Error("No client for test-echo");
-
-  const result = await client.callTool({
-    name: "echo",
-    arguments: { message: "hello from integration test" },
-  });
-
-  const text = result.content?.[0]?.text;
-  if (text !== "hello from integration test") {
-    throw new Error(`Unexpected echo result: ${JSON.stringify(result)}`);
-  }
-  console.log(`Echo tool returned: "${text}"`);
-
-  await manager.disconnectAll();
-  console.log("Integration test passed ✓");
-  process.exit(0);
-} catch (err) {
-  console.error("Integration test failed:", err);
-  await manager.disconnectAll().catch(() => {});
-  process.exit(1);
-}

package/scripts/test-tool-cli-smoke.mjs

@@ -1,93 +0,0 @@
-#!/usr/bin/env node
-/**
- * Smoke test: start RPC server with the weather test server,
- * exercise every tool-cli command via the CLI binary, then shut down.
- *
- * Tests the full wiring: ToolProvider → ToolCliServer → tool-cli CLI.
- */
-import { McpClientManager } from "../dist/mcp/client-manager.js";
-import { ToolCliServer } from "@sammorrowdrums/tool-cli/server";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const execFileAsync = promisify(execFile);
-
-// Resolve the tool-cli binary from node_modules/.bin
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const CLI = join(__dirname, "..", "node_modules", ".bin", "tool-cli");
-
-const manager = new McpClientManager();
-let server;
-
-async function run(...args) {
-  const { stdout } = await execFileAsync("node", [CLI, ...args], {
-    encoding: "utf-8",
-    env: {
-      ...process.env,
-      TOOL_CLI_PORT: String(server.getPort()),
-      TOOL_CLI_TOKEN: token,
-    },
-  });
-  console.log(`$ tool-cli ${args.join(" ")}`);
-  console.log(stdout);
-  return stdout;
-}
-
-let token;
-
-try {
-  await manager.connectOne("weather", {
-    type: "stdio",
-    command: "node",
-    args: ["dist/test-servers/weather-stdio.js"],
-  });
-
-  // Bridge McpClientManager to ToolProvider
-  const provider = {
-    getServerNames: () => manager.getConnectedServers(),
-    getTools: (s) => manager.getToolsForServer(s),
-    async callTool(s, tool, args) {
-      const client = manager.getClient(s);
-      if (!client) throw new Error(`No client for "${s}"`);
-      const result = await client.callTool({ name: tool, arguments: args });
-      return {
-        content: result.content,
-        isError: result.isError === true ? true : undefined,
-        structuredContent: result.structuredContent,
-      };
-    },
-  };
-
-  server = new ToolCliServer(provider);
-  const startResult = await server.start(console.log);
-  token = startResult.token;
-
-  // --help: list servers
-  const help = await run("--help");
-  if (!help.includes("weather")) throw new Error("--help missing weather server");
-
-  // <server>: list tools
-  const tools = await run("weather");
-  if (!tools.includes("check_weather_for_city"))
-    throw new Error("tool list missing check_weather_for_city");
-
-  // <server> <tool>: describe
-  const desc = await run("weather", "check_weather_for_city");
-  if (!desc.includes("city")) throw new Error("describe missing city param");
-
-  // <server> <tool> <args>: call
-  const result = await run("weather", "check_weather_for_city", '{"city":"London"}');
-  if (!result.includes("London")) throw new Error("call result missing London");
-
-  await server.stop();
-  await manager.disconnectAll();
-  console.log("Smoke test passed ✓");
-  process.exit(0);
-} catch (err) {
-  console.error("Smoke test failed:", err);
-  await server?.stop().catch(() => {});
-  await manager.disconnectAll().catch(() => {});
-  process.exit(1);
-}

package/src/code-mode/code-mode-integration.test.ts

@@ -1,135 +0,0 @@
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { McpClientManager } from "../mcp/client-manager.js";
-import { CodeModeManager } from "./index.js";
-
-/**
- * Integration test: connect to the test weather server, verify code mode
- * eligibility, type hint generation, and sandboxed execution with real
- * MCP tool calls returning structuredContent.
- */
-describe("code mode integration (weather server)", () => {
-  const manager = new McpClientManager();
-  const codeMode = new CodeModeManager();
-
-  beforeAll(async () => {
-    await manager.connectAll({
-      mcpServers: {
-        "test-weather": {
-          type: "stdio",
-          command: "node",
-          args: ["dist/test-servers/weather-stdio.js"],
-        },
-      },
-    });
-
-    codeMode.initialize(manager);
-  });
-
-  afterAll(async () => {
-    await manager.disconnectAll();
-  });
-
-  it("discovers eligible tools with readOnlyHint + outputSchema", () => {
-    const eligible = codeMode.getEligibleTools();
-    expect(eligible.length).toBeGreaterThanOrEqual(2);
-    const names = eligible.map((t) => t.name).sort();
-    expect(names).toContain("check_weather_for_city");
-    expect(names).toContain("check_weekly_forecast_for_city");
-    expect(names).toContain("echo");
-  });
-
-  it("generates type hints for eligible tools", () => {
-    const hints = codeMode.getTypeHints();
-    expect(hints).toContain("declare const codemode");
-    expect(hints).toContain("check_weather_for_city");
-    expect(hints).toContain("check_weekly_forecast_for_city");
-    expect(hints).toContain("echo");
-    expect(hints).toContain("listTools");
-  });
-
-  it("reports as active", () => {
-    expect(codeMode.isActive).toBe(true);
-  });
-
-  it("generates system prompt section", () => {
-    const section = codeMode.formatSystemPromptSection();
-    expect(section).toContain("<code_mode>");
-    expect(section).toContain("code_search");
-    expect(section).toContain("code_execute");
-    expect(section).toContain("declare const codemode");
-  });
-
-  it("executes code that calls a single tool", async () => {
-    const result = await codeMode.executeCode(`
-      const weather = await codemode.check_weather_for_city({ city: "Tokyo" });
-      return weather;
-    `);
-
-    expect(result.error).toBeUndefined();
-    expect(result.result).toHaveProperty("temperature", 26);
-    expect(result.result).toHaveProperty("conditions", "Sunny");
-    expect(result.result).toHaveProperty("humidity", 55);
-  });
-
-  it("executes code that chains multiple tool calls", async () => {
-    const result = await codeMode.executeCode(`
-      const cities = ["London", "Tokyo"];
-      const results = [];
-      for (const city of cities) {
-        const w = await codemode.check_weather_for_city({ city });
-        results.push({ city, temp: w.temperature });
-      }
-      return results;
-    `);
-
-    expect(result.error).toBeUndefined();
-    expect(result.result).toEqual([
-      { city: "London", temp: 14 },
-      { city: "Tokyo", temp: 26 },
-    ]);
-  });
-
-  it("executes code that uses listTools", async () => {
-    const result = await codeMode.executeCode(`
-      const tools = await codemode.listTools();
-      return tools.sort();
-    `);
-
-    expect(result.error).toBeUndefined();
-    const names = result.result as string[];
-    expect(names).toContain("check_weather_for_city");
-    expect(names).toContain("echo");
-  });
-
-  it("executes code that calls echo tool", async () => {
-    const result = await codeMode.executeCode(`
-      const r = await codemode.echo({ message: "hello code mode" });
-      return r;
-    `);
-
-    expect(result.error).toBeUndefined();
-    expect(result.result).toEqual({ echo: "hello code mode" });
-  });
-
-  it("handles tool errors gracefully", async () => {
-    const result = await codeMode.executeCode(`
-      const w = await codemode.check_weather_for_city({ city: "Atlantis" });
-      return w;
-    `);
-
-    // Atlantis isn't in the data — server returns text-only content (no structuredContent)
-    // The executor should still return something (parsed text or raw string)
-    expect(result.error).toBeUndefined();
-    expect(result.result).toBeDefined();
-  });
-
-  it("search mode works for tool discovery", async () => {
-    const result = await codeMode.searchTools(`
-      const tools = await codemode.listTools();
-      return tools;
-    `);
-
-    expect(result.error).toBeUndefined();
-    expect(Array.isArray(result.result)).toBe(true);
-  });
-});

package/src/code-mode/eligibility.test.ts

@@ -1,60 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { McpTool } from "../mcp/index.js";
-import { isEligibleForCodeMode } from "./eligibility.js";
-
-function makeTool(overrides: Partial<McpTool> = {}): McpTool {
-  return {
-    name: "test_tool",
-    description: "A test tool",
-    inputSchema: { type: "object", properties: {} },
-    serverName: "test-server",
-    ...overrides,
-  };
-}
-
-describe("isEligibleForCodeMode", () => {
-  it("returns true when readOnlyHint is true and outputSchema is defined", () => {
-    const tool = makeTool({
-      annotations: { readOnlyHint: true },
-      outputSchema: { type: "object", properties: { result: { type: "string" } } },
-    });
-    expect(isEligibleForCodeMode(tool)).toBe(true);
-  });
-
-  it("returns false when readOnlyHint is false", () => {
-    const tool = makeTool({
-      annotations: { readOnlyHint: false },
-      outputSchema: { type: "object", properties: {} },
-    });
-    expect(isEligibleForCodeMode(tool)).toBe(false);
-  });
-
-  it("returns false when readOnlyHint is missing", () => {
-    const tool = makeTool({
-      annotations: {},
-      outputSchema: { type: "object", properties: {} },
-    });
-    expect(isEligibleForCodeMode(tool)).toBe(false);
-  });
-
-  it("returns false when annotations is undefined", () => {
-    const tool = makeTool({
-      annotations: undefined,
-      outputSchema: { type: "object", properties: {} },
-    });
-    expect(isEligibleForCodeMode(tool)).toBe(false);
-  });
-
-  it("returns false when outputSchema is missing", () => {
-    const tool = makeTool({
-      annotations: { readOnlyHint: true },
-      outputSchema: undefined,
-    });
-    expect(isEligibleForCodeMode(tool)).toBe(false);
-  });
-
-  it("returns false when both readOnlyHint and outputSchema are missing", () => {
-    const tool = makeTool();
-    expect(isEligibleForCodeMode(tool)).toBe(false);
-  });
-});

package/src/code-mode/eligibility.ts

@@ -1,16 +0,0 @@
-import type { McpClientManager, McpTool } from "../mcp/index.js";
-
-/**
- * A tool is eligible for code mode when:
- * 1. annotations.readOnlyHint === true — does not modify its environment
- * 2. outputSchema is defined — results are typed and parseable
- */
-export function isEligibleForCodeMode(tool: McpTool): boolean {
-  const annotations = tool.annotations as { readOnlyHint?: boolean } | undefined;
-  return annotations?.readOnlyHint === true && tool.outputSchema != null;
-}
-
-/** Get all tools eligible for code mode across all connected MCP servers. */
-export function getEligibleTools(mcpManager: McpClientManager): McpTool[] {
-  return mcpManager.getTools().filter(isEligibleForCodeMode);
-}