pi-codemcp 0.1.0

package/.python-version

@@ -0,0 +1 @@
+3.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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/README.md

@@ -0,0 +1,143 @@
+# pi-codemcp
+
+Fast, typed, sandboxed **Code Mode for every MCP server configured in Pi**.
+
+Instead of putting every upstream MCP tool definition into the model context, pi-codemcp gives the agent a small interface for discovery, execution, and reuse:
+
+- `codemcp_search` finds relevant tools and returns only their typed SDK stubs.
+- `codemcp_execute` runs one sandboxed Python call graph across one or many MCP servers.
+- `codemcp_save_chain` turns a repeated call graph into a reusable native Pi tool.
+
+Intermediate results stay inside the sandbox. The model receives only the compact value returned by the program.
+
+## Why Code Mode?
+
+MCP has an uncomfortable scaling property: the more tools an agent can use, the more tool schemas compete with the actual task for context. Multi-step work also tends to bounce every intermediate result through the model, adding tokens, latency, and opportunities for mistakes.
+
+Cloudflare described a better pattern in [Code Mode: give agents an entire API in 1,000 tokens](https://blog.cloudflare.com/code-mode-mcp/): expose a small search-and-execute surface, let the model write code against a typed SDK, and execute that code in a sandbox. Their work reports a fixed tool footprint and dramatic context savings for very large APIs. The open-source implementation lives in [`@cloudflare/codemode`](https://github.com/cloudflare/agents/tree/main/packages/codemode).
+
+pi-codemcp applies that idea on the **client side** to the MCP servers you already use in Pi:
+
+1. Search the combined catalog without loading every schema into context.
+2. Type-check a compact Python plan before any upstream call happens.
+3. Execute dependent or parallel calls without model round-trips between them.
+4. Return only the final data the agent actually needs.
+5. Save stable plans as native tools and reuse them without rewriting the call graph.
+
+That can make complex MCP workflows faster and substantially more token-efficient. Exact savings depend on the servers, schemas, model, and task.
+
+## Built for daily use, not a demo
+
+I built this because I care a lot about software that is genuinely fast, efficient, and predictable enough to use every day. Too many AI extensions look good in a short demo but become slow, noisy, fragile, or effectively unusable in real work.
+
+pi-codemcp is deliberately opinionated about operational quality:
+
+- Pi startup does not wait for Python or MCP servers.
+- Each upstream connection is lazy and independent.
+- Tool catalogs are cached per server and invalidated independently.
+- Agent-written code is type-checked before execution.
+- Time, memory, call count, and output size are bounded.
+- Failures are explicit; there are no silent retries or compatibility fallbacks.
+- Tool output is compact by default and expands with Pi's normal `Ctrl+O` UI.
+
+There is always room to make it faster and more reliable. If something is not working well, please report it rather than silently giving up on the extension.
+
+## Saved MCP chains
+
+Any successful MCP call graph can become a reusable tool with an explicit input and output JSON Schema.
+
+A saved chain is exposed in two forms from one manifest:
+
+```text
+mcp_chain_weekly_digest(...)   # native Pi tool
+chains.weekly_digest(...)      # typed call inside Code Mode
+```
+
+Chains can call upstream MCP tools, other saved chains, or themselves recursively. This enables reusable composition such as:
+
+```python
+issues = await chains.collect_open_issues({"assignee": input["assignee"]})
+result = await slack.post_message({
+    "channel": input["channel"],
+    "text": issues["summary"],
+})
+return {"posted": result["ok"], "count": issues["count"]}
+```
+
+Nested chains share the same deadline, cancellation signal, catalog snapshot, and total call budget. Every nested input and output is runtime-validated. Recursion is supported but bounded. Dependency fingerprints mark chains stale when a referenced contract changes.
+
+New manifests default to project scope under `<project>/.pi/pi-codemcp/chains`; explicitly global chains live under `<agent-dir>/pi-codemcp/chains`. A project chain overrides a same-named global chain without deleting it. Manifests contain sandboxed code and schemas, never credentials or execution results. `/codemcp` labels both scopes and can revalidate, enable, disable, or delete chains.
+
+## Install
+
+```bash
+pi install npm:pi-codemcp
+```
+
+It reads Pi's existing `<agent-dir>/mcp.json` and supports stdio, Streamable HTTP, SSE, bearer authentication, and FastMCP-managed OAuth. Open `/codemcp` to manage servers, per-tool policy, saved chains, cache, and execution limits.
+
+Package users do not need Python, uv, Bun, or just. A pinned uv binary bootstraps the locked Python 3.13 runtime under Pi's writable agent directory on first use; the first bootstrap needs network access unless already cached.
+
+## Agent workflow
+
+The agent searches for a capability, receives the complete stub it needs, and executes a compact plan:
+
+```python
+issues = await linear.list_issues({"assignee": "me", "limit": 50})
+return {"count": len(issues), "ids": [issue["identifier"] for issue in issues]}
+```
+
+Incomplete upstream schemas become recursive `JsonValue`, not `Any`; unknown values must be narrowed explicitly before typed use.
+
+## Safety and limits
+
+FastMCP owns MCP transports, runtime validation, and OAuth. [Pydantic Monty](https://github.com/pydantic/monty) type-checks and executes agent-written Python without host filesystem, environment, network, or subprocess access.
+
+`/codemcp` configures servers, saved chains, per-tool policy, timeouts, call limits, output limits, cache TTL, and warmup. Server, chain, tool-policy, and setting toggles stay local and instantaneous until one `Ctrl+S` batch save/reload. Discovery, revalidation, and deletion remain explicit immediate actions. The sandbox also has a fixed memory ceiling; executions are serialized per Pi session. There are no automatic retries or cross-service rollback.
+
+Enabled tools retain their upstream permissions. Saved chains never bypass server or per-tool policy and are checked against the current enabled catalog whenever they run.
+
+## Something failed? Please open an issue
+
+Please do not assume your failure is too specific or not worth reporting. Platform differences, strange schemas, slow startup, confusing rendering, OAuth problems, and rough edges are exactly the reports that make this project better.
+
+Open an issue at <https://github.com/yolonir/pi-codemcp/issues>.
+
+You can ask your coding agent to do the work:
+
+```text
+Reproduce this pi-codemcp problem, redact all credentials and private data,
+collect the pi-codemcp version, Pi version, OS/architecture, MCP transport,
+minimal configuration shape, exact error, and relevant logs, then open a
+GitHub issue at https://github.com/yolonir/pi-codemcp/issues.
+```
+
+If the agent cannot create the issue, ask it to prepare the title and body for you. I would much rather receive an incomplete report than have someone hit a problem, abandon the package, and never say anything. I will read the issues and work through them.
+
+## Local development
+
+```bash
+just init
+just check
+just release-check
+```
+
+To test the checkout without loading an installed copy:
+
+```bash
+pi -ne -e . --no-session
+```
+
+`just check` runs lockfile checks, TypeScript, Biome, Bun tests, Ruff, mypy, ty, and pytest. `just release-check` additionally packs the npm artifact, installs it into a clean consumer directory, and runs the packaged sidecar without a system uv on `PATH`.
+
+## Releases
+
+Release Please derives versions and release notes from Conventional Commit titles on `main`: `fix:` publishes a patch, `feat:` publishes a minor, and a `!` or `BREAKING CHANGE:` publishes a major. It maintains the release PR, `CHANGELOG.md`, `package.json`, version tag, and GitHub Release.
+
+Merging a release PR publishes the verified package to npm from `.github/workflows/release.yml` using npm trusted publishing and provenance. The publish job checks out the release tag and runs the package's full prepublish and clean-install gates before uploading it.
+
+## Credits
+
+The core search-and-execute philosophy is inspired by Cloudflare's Code Mode work. pi-codemcp is an independent implementation for Pi that composes arbitrary configured MCP servers through FastMCP and a Pydantic Monty sandbox.
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,188 @@
+import { join } from "node:path";
+import {
+  CONFIG_DIR_NAME,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { SavedChainManager } from "../src/chains.js";
+import { setMcpServersEnabled } from "../src/config.js";
+import { summarizeError } from "../src/errors.js";
+import { CodeMcpLifecycle } from "../src/lifecycle.js";
+import type { SidecarClientOptions } from "../src/mcp-client.js";
+import {
+  type ChainModalState,
+  chainStatesFromViews,
+  type ChainEnabledChange as ModalChainEnabledChange,
+  type ServerEnabledChange,
+  type ServerModalState,
+  serverStatesFromStatus,
+  showServerManagerModal,
+} from "../src/modal.js";
+import { type CodeMcpSettings, saveCodeMcpSettings } from "../src/settings.js";
+import { registerCodeMcpTools } from "../src/tools.js";
+
+export function createCodeMcpExtension(options: SidecarClientOptions = {}) {
+  return function codeMcpExtension(pi: ExtensionAPI): void {
+    const lifecycle = new CodeMcpLifecycle(options);
+    const chains = new SavedChainManager(pi, lifecycle);
+    registerCodeMcpTools(pi, lifecycle, chains);
+
+    pi.registerCommand("codemcp", {
+      description: "Manage CodeMCP servers, saved chains, tools, and settings",
+      handler: async (_args, ctx) => {
+        try {
+          bindProjectChainScope(ctx, lifecycle, chains);
+          const [status, savedChains, settings] = await Promise.all([
+            lifecycle.request("status", {}),
+            chains.list(),
+            Promise.resolve(lifecycle.loadSettings()),
+          ]);
+          const servers = serverStatesFromStatus(status);
+          if (ctx.mode !== "tui") {
+            if (ctx.hasUI) ctx.ui.notify(formatStatusSummary(servers), "info");
+            return;
+          }
+
+          await showServerManagerModal(ctx, {
+            servers,
+            chains: chainStatesFromViews(savedChains),
+            settings,
+            onDiscover: async (server) =>
+              requireServerStatus(
+                await lifecycle.request("discover", { server: server.name }),
+                server.name,
+              ),
+            onSaveChanges: (updated, serverChanges, chainChanges) =>
+              saveManagerChanges(lifecycle, chains, updated, serverChanges, chainChanges),
+            onResolveUnsaved: async () => {
+              const choice = await ctx.ui.select("Unsaved CodeMCP changes", [
+                "Save",
+                "Discard",
+                "Cancel",
+              ]);
+              if (choice === "Save") return "save";
+              if (choice === "Discard") return "discard";
+              return "cancel";
+            },
+            onRevalidateChain: async (chain) => {
+              await chains.revalidate(chain.name, chain.scope);
+              return chainStatesFromViews(await chains.list());
+            },
+            onDeleteChain: async (chain) =>
+              chainStatesFromViews(await chains.delete(chain.name, chain.scope)),
+          });
+        } catch (error) {
+          ctx.ui.notify(summarizeError(error), "error");
+        }
+      },
+    });
+
+    pi.on("session_start", (_event, ctx) => {
+      bindProjectChainScope(ctx, lifecycle, chains);
+      chains.activatePersisted();
+      for (const error of chains.startupErrors) ctx.ui.notify(error, "warning");
+      let settings: CodeMcpSettings;
+      try {
+        settings = lifecycle.loadSettings();
+      } catch (error) {
+        ctx.ui.notify(`CodeMCP settings failed: ${summarizeError(error)}`, "warning");
+        return;
+      }
+      if (!settings.backgroundWarmup) return;
+      void lifecycle.warmup().catch((error: unknown) => {
+        ctx.ui.notify(`CodeMCP background warmup failed: ${summarizeError(error)}`, "warning");
+      });
+    });
+
+    pi.on("session_shutdown", async () => {
+      await lifecycle.shutdown();
+    });
+  };
+}
+
+export async function saveManagerChanges(
+  lifecycle: Pick<CodeMcpLifecycle, "configPath" | "settingsPath" | "loadSettings" | "reload">,
+  chains: Pick<SavedChainManager, "applyEnabled">,
+  updated: CodeMcpSettings,
+  serverChanges: readonly ServerEnabledChange[],
+  chainChanges: readonly ModalChainEnabledChange[],
+): Promise<{
+  settings: CodeMcpSettings;
+  servers: ServerModalState[];
+  chains: ChainModalState[];
+}> {
+  const previousSettings = lifecycle.loadSettings();
+  let serverConfigChanged = false;
+  try {
+    saveCodeMcpSettings(lifecycle.settingsPath, updated);
+    if (serverChanges.length > 0) {
+      setMcpServersEnabled(
+        lifecycle.configPath,
+        serverChanges.map((change) => ({ name: change.name, enabled: change.enabled })),
+      );
+      serverConfigChanged = true;
+      await lifecycle.reload();
+    }
+    const applied = await chains.applyEnabled(
+      chainChanges.map((change) => ({
+        name: change.name,
+        scope: change.scope,
+        enabled: change.enabled,
+      })),
+    );
+    return {
+      settings: lifecycle.loadSettings(),
+      servers: serverStatesFromStatus(applied.status),
+      chains: chainStatesFromViews(applied.chains),
+    };
+  } catch (error) {
+    saveCodeMcpSettings(lifecycle.settingsPath, previousSettings);
+    if (serverConfigChanged) {
+      setMcpServersEnabled(
+        lifecycle.configPath,
+        serverChanges.map((change) => ({
+          name: change.name,
+          enabled: change.previousEnabled,
+        })),
+      );
+    }
+    try {
+      await lifecycle.reload();
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        "CodeMCP save failed and runtime rollback also failed",
+      );
+    }
+    throw error;
+  }
+}
+
+export default createCodeMcpExtension();
+
+function requireServerStatus(
+  status: Record<string, unknown>,
+  serverName: string,
+): ServerModalState {
+  const server = serverStatesFromStatus(status).find((candidate) => candidate.name === serverName);
+  if (!server) throw new Error(`CodeMCP returned no status for ${serverName}`);
+  return server;
+}
+
+function bindProjectChainScope(
+  ctx: Pick<ExtensionCommandContext, "cwd" | "isProjectTrusted">,
+  lifecycle: CodeMcpLifecycle,
+  chains: SavedChainManager,
+): void {
+  const projectChainsPath = ctx.isProjectTrusted()
+    ? join(ctx.cwd, CONFIG_DIR_NAME, "pi-codemcp", "chains")
+    : undefined;
+  lifecycle.configureProjectChains(projectChainsPath);
+  chains.configureProject(projectChainsPath);
+}
+
+function formatStatusSummary(servers: ServerModalState[]): string {
+  const enabled = servers.filter((server) => server.enabled).length;
+  const tools = servers.reduce((total, server) => total + server.toolCount, 0);
+  return `CodeMCP: ${enabled}/${servers.length} servers · ${tools} enabled tools`;
+}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "pi-codemcp",
+  "version": "0.1.0",
+  "description": "Typed, sandboxed Code Mode access to configured MCP servers for Pi",
+  "type": "module",
+  "packageManager": "bun@1.3.10",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yolonir/pi-codemcp.git"
+  },
+  "homepage": "https://github.com/yolonir/pi-codemcp#readme",
+  "bugs": {
+    "url": "https://github.com/yolonir/pi-codemcp/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "mcp",
+    "code-mode"
+  ],
+  "files": [
+    "extensions/index.ts",
+    "src/*.ts",
+    "sidecar/*.py",
+    "sidecar/pyproject.toml",
+    "sidecar/uv.lock",
+    ".python-version",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "just check",
+    "check:ts": "bun run typecheck && bun run lint && bun run test:ts",
+    "format": "biome check --write .",
+    "lint": "biome check .",
+    "prepublishOnly": "just check && just release-check",
+    "test": "bun run test:ts && bun run test:python",
+    "test:python": "uv run --project sidecar pytest tests/python -q",
+    "test:ts": "bun test tests/typescript",
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0"
+  },
+  "optionalDependencies": {
+    "@manzt/uv-darwin-arm64": "0.8.13",
+    "@manzt/uv-darwin-x64": "0.8.13",
+    "@manzt/uv-linux-arm64": "0.8.13",
+    "@manzt/uv-linux-x64": "0.8.13",
+    "@manzt/uv-win32-arm64": "0.8.13",
+    "@manzt/uv-win32-ia32": "0.8.13",
+    "@manzt/uv-win32-x64": "0.8.13"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.3",
+    "@earendil-works/pi-agent-core": "0.80.7",
+    "@earendil-works/pi-ai": "0.80.7",
+    "@earendil-works/pi-coding-agent": "0.80.7",
+    "@earendil-works/pi-tui": "0.80.7",
+    "@types/bun": "1.3.14",
+    "typebox": "1.3.6",
+    "typescript": "5.9.3"
+  }
+}

package/sidecar/__init__.py

@@ -0,0 +1 @@
+"""FastMCP/Pydantic-Monty sidecar for pi-codemcp."""

package/sidecar/catalog_cache.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import hashlib
+import time
+from contextlib import suppress
+from typing import TYPE_CHECKING, Literal
+
+from mcp import types as mcp_types
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from .json_types import JSON_OBJECT_ADAPTER, JsonObject
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+CACHE_VERSION: Literal[1] = 1
+DEFAULT_MAX_AGE_SECONDS = 24 * 60 * 60
+
+
+class CachedServerCatalog(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    version: Literal[1] = CACHE_VERSION
+    server_name: str
+    config_fingerprint: str
+    updated_at: float
+    tools: list[JsonObject]
+
+
+class CatalogCache:
+    def __init__(
+        self,
+        directory: Path,
+        *,
+        max_age_seconds: float = DEFAULT_MAX_AGE_SECONDS,
+    ) -> None:
+        self.directory = directory
+        self.max_age_seconds = max_age_seconds
+
+    def load(
+        self,
+        server_name: str,
+        config_fingerprint: str,
+    ) -> list[mcp_types.Tool] | None:
+        path = self._path(server_name)
+        try:
+            entry = CachedServerCatalog.model_validate_json(path.read_text(encoding="utf-8"))
+        except (FileNotFoundError, OSError, ValidationError, ValueError):
+            return None
+        if entry.server_name != server_name:
+            return None
+        if entry.config_fingerprint != config_fingerprint:
+            return None
+        if time.time() - entry.updated_at > self.max_age_seconds:
+            return None
+        try:
+            return [mcp_types.Tool.model_validate(tool) for tool in entry.tools]
+        except ValidationError:
+            return None
+
+    def save(
+        self,
+        server_name: str,
+        config_fingerprint: str,
+        tools: list[mcp_types.Tool],
+    ) -> None:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        with suppress(OSError):
+            self.directory.chmod(0o700)
+        path = self._path(server_name)
+        temporary = path.with_suffix(".tmp")
+        entry = CachedServerCatalog(
+            server_name=server_name,
+            config_fingerprint=config_fingerprint,
+            updated_at=time.time(),
+            tools=[
+                JSON_OBJECT_ADAPTER.validate_python(
+                    tool.model_dump(mode="json", by_alias=True, exclude_none=True)
+                )
+                for tool in tools
+            ],
+        )
+        temporary.write_text(entry.model_dump_json(), encoding="utf-8")
+        temporary.chmod(0o600)
+        temporary.replace(path)
+
+    def _path(self, server_name: str) -> Path:
+        digest = hashlib.sha256(server_name.encode("utf-8")).hexdigest()[:20]
+        return self.directory / f"{digest}.json"