pi-codemcp 1.0.0 → 1.1.1

package/README.md

@@ -4,9 +4,11 @@ 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_search` ranks capabilities or pages through a compact inventory without loading full schemas.
+- `codemcp_inspect` returns exact typed SDK stubs only for selected calls.
 - `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.
+- `codemcp_manage_chains` lists chains or performs an explicitly confirmed enable, disable, revalidate, or delete.
 
 Intermediate results stay inside the sandbox. The model receives only the compact value returned by the program.
 
@@ -18,11 +20,12 @@ Cloudflare described a better pattern in [Code Mode: give agents an entire API i
 
 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.
+1. Search the combined catalog or page through a compact inventory.
+2. Inspect exact schemas only for the calls selected for the task.
+3. Type-check a compact Python plan before any upstream call happens.
+4. Execute dependent or parallel calls without model round-trips between them.
+5. Return only the final data the agent actually needs.
+6. 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.
 
@@ -39,6 +42,7 @@ pi-codemcp is deliberately opinionated about operational quality:
 - 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.
+- Bounded local telemetry uses fixed rollups rather than session event logs and appears in the `/codemcp` Stats tab.
 
 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.
 
@@ -68,6 +72,8 @@ Nested chains share the same deadline, cancellation signal, catalog snapshot, an
 
 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.
 
+There is deliberately no implicit “save last execution” state: the agent must submit the exact successfully tested code plus explicit input and output contracts. This keeps persistence reviewable and avoids saving the wrong attempt from a long session.
+
 ## Install
 
 ```bash
@@ -78,24 +84,136 @@ It reads Pi's existing `<agent-dir>/mcp.json` and supports stdio, Streamable HTT
 
 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
+## MCP configuration examples
+
+`pi-codemcp` reads the same MCP config Pi uses. Either shape is accepted:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    }
+  }
+}
+```
+
+or a root server map:
+
+```json
+{
+  "linear": {
+    "type": "http",
+    "url": "https://mcp.linear.app/mcp",
+    "auth": "oauth"
+  },
+  "grafana": {
+    "type": "sse",
+    "url": "https://grafana.example.com/sse",
+    "headers": {
+      "authorization": "Bearer ${GRAFANA_MCP_TOKEN}"
+    }
+  },
+  "disabled-example": {
+    "command": "example-server",
+    "disabled": true
+  }
+}
+```
+
+For stdio servers, pi-codemcp passes a small safe base environment plus variables listed in `MY_PI_CHILD_ENV_ALLOWLIST` or `MY_PI_MCP_ENV_ALLOWLIST`. Explicit `env` values in `mcp.json` are also passed. Remote headers can reference allowed environment variables with `${NAME}`. Pi-only fields such as `directTools`, `lifecycle`, `idleTimeout`, `enabled`, and `disabled` are understood locally and are not forwarded to FastMCP.
+
+## Settings JSON
+
+Settings live at `<agent-dir>/pi-codemcp/settings.json` and can also be edited in `/codemcp`:
+
+```json
+{
+  "version": 2,
+  "backgroundWarmup": true,
+  "cacheTtlHours": 24,
+  "executionTimeoutSeconds": 30,
+  "toolTimeoutSeconds": 30,
+  "maxCalls": 50,
+  "resultLimitKiB": 16,
+  "outputLimitKiB": 50,
+  "disabledTools": {
+    "linear": ["delete_issue"]
+  }
+}
+```
+
+The Python sidecar enforces catalog cache TTL, execution timeout, per-tool timeout, max MCP calls, result size, and disabled-tool policy. The TypeScript Pi layer uses `backgroundWarmup` and `outputLimitKiB` for session warmup and rendered-output truncation; the sidecar still validates those fields so the settings file has one strict shared schema. Version-one files are migrated when loaded, and the removed `outputLineLimit` field is omitted on the next save.
 
-The agent searches for a capability, receives the complete stub it needs, and executes a compact plan:
+## Search and execute flow
+
+The agent searches for a capability, inspects the selected exact stub when needed, 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.
+The same flow is available through the internal CLI for debugging:
+
+```bash
+uv run --project sidecar --frozen -m sidecar.cli search "issues assigned to me"
+uv run --project sidecar --frozen -m sidecar.cli execute --code-file plan.py
+```
+
+A direct one-shot plan can call multiple servers without model round trips between calls:
+
+```bash
+uv run --project sidecar --frozen -m sidecar.cli execute --code '
+number = await alpha.get_number({"seed": 41})
+saved = await beta.save_number({"value": number["value"]})
+return {"number": number["value"], "identifier": saved["identifier"]}
+'
+```
+
+Incomplete upstream schemas become recursive `JsonValue`, not `Any`; unknown values must be narrowed explicitly before typed use. For unfamiliar outputs, `inspect_json(value, samples=2, max_depth=3)` returns a byte-bounded structural summary, cardinality, field sizes, and samples. Preflight type errors happen before any upstream call is made, and oversized final results fail explicitly with the same actionable inspection data.
+
+## Saved-chain CLI flow
+
+Saved chains are JSON manifests with sandboxed code plus explicit input/output JSON Schemas. Project-scoped chains live under `<project>/.pi/pi-codemcp/chains`; global chains live under `<agent-dir>/pi-codemcp/chains`.
+
+```bash
+uv run --project sidecar --frozen -m sidecar.cli chain save save_number \
+  --description "Fetch and save one generated number." \
+  --code 'number = await alpha.get_number({"seed": input["seed"]})
+return await beta.save_number({"value": number["value"]})' \
+  --input-schema '{"type":"object","properties":{"seed":{"type":"integer"}},"required":["seed"],"additionalProperties":false}' \
+  --output-schema '{"type":"object","properties":{"saved":{"type":"boolean"},"identifier":{"type":"string"}},"required":["saved","identifier"],"additionalProperties":false}'
+
+uv run --project sidecar --frozen -m sidecar.cli chain list
+uv run --project sidecar --frozen -m sidecar.cli chain run save_number --input '{"seed":41}'
+uv run --project sidecar --frozen -m sidecar.cli chain revalidate save_number --scope project
+uv run --project sidecar --frozen -m sidecar.cli chain delete save_number --scope project
+```
+
+Revalidation checks the saved code against the current enabled catalog. Deletion refuses to remove chains still referenced by other chains. Disabling a project chain does not fall back to a same-named global chain; project scope continues to shadow global scope until the project manifest is deleted.
+
+## Output and result normalization
+
+When an upstream tool declares an output schema, pi-codemcp requires `structuredContent`, validates it, dumps it back to JSON-compatible values, and preserves declared structured string fields as strings. FastMCP-wrapped `result` strings are intentionally unwrapped and parsed because those wrappers commonly carry JSON payloads as text. When no output schema exists, single text responses that look like JSON objects, arrays, `null`, `true`, or `false` are normalized into native JSON values; non-JSON text remains a string.
+
+Execution results report explicit stages:
+
+- `preflight`: code did not run and no upstream call was made.
+- `runtime`: the sandbox or an upstream call failed after execution started.
+- `timeout` / `cancelled`: execution was stopped.
+- `result`: the call graph completed, but the returned value exceeded `resultLimitKiB`.
+
+Rendered Pi output is separately truncated by `outputLimitKiB`; the full oversized rendered value is not persisted.
 
 ## 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.
+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. Code Mode can only call the typed MCP tool and saved-chain facades exposed in the generated stubs.
 
-`/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.
+`/codemcp` configures servers, saved chains, per-tool policy, timeouts, call limits, output limits, cache TTL, and warmup, and shows bounded lifetime/recent telemetry in its Stats tab. 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.
+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. Preflight safety does not make upstream tools transactional: if a later call fails after earlier calls succeeded, pi-codemcp does not roll those upstream side effects back.
 
 ## Something failed? Please open an issue
 
@@ -122,19 +240,32 @@ just check
 just release-check
 ```
 
+Development and packaged runtime checks target Python 3.13. The sidecar metadata, `.python-version`, mypy, ty, and CI all align on that version.
+
 To test the checkout without loading an installed copy:
 
 ```bash
 pi -ne -e . --no-session
 ```
 
+The sidecar also has a stable internal CLI for development, debugging, and future runtime adapters:
+
+```bash
+uv run --project sidecar --frozen -m sidecar.cli serve --stdio
+uv run --project sidecar --frozen -m sidecar.cli status --agent-dir ~/.pi/agent
+uv run --project sidecar --frozen -m sidecar.cli search "linear issues"
+uv run --project sidecar --frozen -m sidecar.cli execute --code-file plan.py
+uv run --project sidecar --frozen -m sidecar.cli chain list
+uv run --project sidecar --frozen -m sidecar.cli doctor --agent-dir ~/.pi/agent
+```
+
 `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.
+Merging a release PR publishes the verified package to npm from `.github/workflows/release.yml` using trusted publishing and provenance. Quality gates the exact merge commit on Linux, macOS, and Windows; the publish job checks out its release tag, packs it with Bun, and uses npm only for the final OIDC-authenticated upload.
 
 ## Credits
 

package/extensions/index.ts

@@ -17,6 +17,7 @@ import {
   type ServerModalState,
   serverStatesFromStatus,
   showServerManagerModal,
+  statsStateFromSnapshot,
 } from "../src/modal.js";
 import { type CodeMcpSettings, saveCodeMcpSettings } from "../src/settings.js";
 import { registerCodeMcpTools } from "../src/tools.js";
@@ -32,10 +33,11 @@ export function createCodeMcpExtension(options: SidecarClientOptions = {}) {
       handler: async (_args, ctx) => {
         try {
           bindProjectChainScope(ctx, lifecycle, chains);
-          const [status, savedChains, settings] = await Promise.all([
+          const [status, savedChains, settings, stats] = await Promise.all([
             lifecycle.request("status", {}),
             chains.list(),
             Promise.resolve(lifecycle.loadSettings()),
+            lifecycle.request("stats", {}),
           ]);
           const servers = serverStatesFromStatus(status);
           if (ctx.mode !== "tui") {
@@ -47,6 +49,7 @@ export function createCodeMcpExtension(options: SidecarClientOptions = {}) {
             servers,
             chains: chainStatesFromViews(savedChains),
             settings,
+            stats: statsStateFromSnapshot(stats),
             onDiscover: async (server) =>
               requireServerStatus(
                 await lifecycle.request("discover", { server: server.name }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codemcp",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Typed, sandboxed Code Mode access to configured MCP servers for Pi",
   "type": "module",
   "packageManager": "bun@1.3.10",
@@ -41,14 +41,15 @@
     "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:python": "uv run --project sidecar pytest -c sidecar/pyproject.toml tests/python -q",
     "test:ts": "bun test tests/typescript",
     "typecheck": "tsc --noEmit"
   },
   "pi": {
     "extensions": [
       "./extensions/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/yolonir/pi-codemcp/main/media/preview.png"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0"
@@ -79,11 +80,11 @@
     }
   },
   "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",
+    "@biomejs/biome": "2.5.4",
+    "@earendil-works/pi-agent-core": "0.80.10",
+    "@earendil-works/pi-ai": "0.80.10",
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@earendil-works/pi-tui": "0.80.10",
     "@types/bun": "1.3.14",
     "typebox": "1.3.6",
     "typescript": "5.9.3"

package/sidecar/catalog_cache.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import hashlib
+import os
 import time
 from contextlib import suppress
 from typing import TYPE_CHECKING, Literal
@@ -68,7 +69,7 @@ class CatalogCache:
         with suppress(OSError):
             self.directory.chmod(0o700)
         path = self._path(server_name)
-        temporary = path.with_suffix(".tmp")
+        temporary = self.directory / f".{path.stem}.{os.getpid()}.{time.time_ns()}.tmp"
         entry = CachedServerCatalog(
             server_name=server_name,
             config_fingerprint=config_fingerprint,