@eovidiu/pi-extensions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ovidiu
+
+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,379 @@
+# @eovidiu/pi-extensions
+
+Personal [Pi](https://pi.dev) extension package.
+
+This repository currently contains one extension: **`mcp-bridge`**, an explicit opt-in MCP compatibility bridge for Pi.
+
+> Security note: Pi extensions run as local TypeScript with your user permissions. MCP servers started by this extension also run with your user permissions. Review the source and every MCP server command before enabling it.
+
+## Why this exists
+
+Pi intentionally does not ship built-in MCP support. The usual Pi approach is to integrate tools directly through skills, CLI wrappers, or extensions.
+
+This package is a compatibility bridge for users who already have trusted MCP server configs in other tools and want to reuse them from Pi without giving up Pi's explicit opt-in model.
+
+The bridge never starts newly discovered MCP servers automatically. Discovery only records servers as disabled. A server must be explicitly enabled before its process starts or its tools are exposed to Pi.
+
+## Features
+
+- Discovers MCP server configs from common Claude Desktop, Claude Code, and Codex locations.
+- Syncs discovered servers into a Pi-owned config file: `~/.pi/mcp.json`.
+- Preserves manually added Pi MCP server entries.
+- Preserves existing `enabled` values across resyncs.
+- Defaults newly discovered servers to `enabled: false`.
+- Starts only explicitly enabled MCP stdio servers.
+- Initializes MCP sessions and calls `tools/list`.
+- Converts a conservative MCP JSON Schema subset into Pi/typebox tool schemas.
+- Registers supported MCP tools as Pi tools.
+- Forwards Pi tool calls to MCP `tools/call`.
+- Stops and deactivates tools on disable, restart, session shutdown, and reload.
+- Supports interactive `/mcp-enable` and `/mcp-disable` selectors in Pi's TUI.
+- Supports project-local `.pi/mcp.json` overrides.
+- Supports `allowServers`, `denyServers`, and `maxOutputChars` hardening settings.
+- Writes detailed redacted diagnostics to `~/.pi/mcp-bridge.log` instead of stdout.
+
+## Installation
+
+### Local development install
+
+```bash
+pi install /Users/fameftimie/work/pi-extensions
+```
+
+After editing the extension, run this inside Pi:
+
+```text
+/reload
+```
+
+### Temporary one-off load
+
+```bash
+pi -e /Users/fameftimie/work/pi-extensions
+```
+
+Use this for quick testing only. A normal `pi install` is better for ongoing use because the package remains in Pi's resource set.
+
+### npm install, after publishing
+
+```bash
+pi install npm:@eovidiu/pi-extensions
+```
+
+To pin a published version:
+
+```bash
+pi install npm:@eovidiu/pi-extensions@0.1.0
+```
+
+## Quick start
+
+1. Install the package.
+2. Start or reload Pi.
+3. Sync detected MCP configs:
+
+```text
+/mcp-sync
+```
+
+4. Inspect what was found:
+
+```text
+/mcp-status
+```
+
+5. Enable trusted servers explicitly.
+
+Interactive TUI selector:
+
+```text
+/mcp-enable
+```
+
+Direct enable by name:
+
+```text
+/mcp-enable claude_desktop__filesystem
+```
+
+6. Ask Pi to use one of the registered MCP-backed tools.
+
+7. Disable servers when you no longer need them.
+
+Interactive TUI selector:
+
+```text
+/mcp-disable
+```
+
+Direct disable by name:
+
+```text
+/mcp-disable claude_desktop__filesystem
+```
+
+## Commands
+
+| Command | Behavior |
+|---|---|
+| `/mcp-sync` | Rescan known Claude/Codex MCP config locations and update `~/.pi/mcp.json`. Newly discovered servers remain disabled. Enabled servers are started/registered after sync. |
+| `/mcp-status` | Show tracked servers, enabled/disabled state, connection summary, config paths, and log path. |
+| `/mcp-enable` | In interactive Pi sessions, rescan configs and open a selector for disabled detected servers. Selected servers are enabled, started, and registered. |
+| `/mcp-enable <server>` | Enable one server directly, then start/register enabled MCP tools. |
+| `/mcp-disable` | In interactive Pi sessions, open a selector for currently enabled servers. Selected servers are disabled, stopped, and their tools are deactivated. |
+| `/mcp-disable <server>` | Disable one server directly, stop it, and deactivate its tools. |
+| `/mcp-restart` | Restart all enabled MCP servers. |
+| `/mcp-restart <server>` | Restart one MCP server. |
+
+Interactive selectors use Pi's `ctx.ui.select()` API. They work in TUI/RPC-capable interactive contexts. In non-UI print/JSON mode, the extension avoids dialogs and reports direct command usage instead.
+
+## Config files
+
+### Global config
+
+The extension owns this file:
+
+```text
+~/.pi/mcp.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "autoStart": false,
+  "servers": {
+    "claude_desktop__filesystem": {
+      "enabled": false,
+      "managedBy": "pi-mcp-bridge",
+      "source": "claude-desktop",
+      "sourceName": "filesystem",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/work"],
+      "env": {}
+    }
+  },
+  "maxOutputChars": 20000
+}
+```
+
+Rules:
+
+- Managed discovered entries have `managedBy: "pi-mcp-bridge"`.
+- Managed entries may be updated or removed by `/mcp-sync` when source configs change.
+- Manual entries without that `managedBy` value are preserved.
+- Existing managed `enabled` values are preserved during sync.
+- Newly discovered managed entries are always added with `enabled: false`.
+
+### Project override
+
+A project can provide an override at:
+
+```text
+.pi/mcp.json
+```
+
+Project entries override global entries with the same server name for the current working directory. Project settings can also provide policy controls:
+
+```json
+{
+  "version": 1,
+  "autoStart": false,
+  "servers": {},
+  "allowServers": ["claude_desktop__filesystem", "codex__*"],
+  "denyServers": ["*production*"],
+  "maxOutputChars": 20000
+}
+```
+
+Use project overrides carefully. Review `.pi/mcp.json` before running Pi in repositories you do not trust.
+
+## Discovery sources
+
+The extension probes common locations for MCP server definitions.
+
+### Claude Desktop
+
+```text
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+### Claude Code
+
+```text
+~/.claude.json
+~/.claude/settings.json
+~/.config/claude-code/config.json
+~/.config/claude-code/settings.json
+```
+
+### Codex
+
+```text
+~/.codex/config.toml
+~/.codex/config.json
+~/.config/codex/config.toml
+~/.config/codex/config.json
+```
+
+Supported config maps include common `mcpServers`, `mcp_servers`, and `mcpServersConfig` shapes. Unsupported or malformed entries are skipped and logged.
+
+## Implementation details
+
+The extension is implemented as a Pi package with this manifest in `package.json`:
+
+```json
+{
+  "keywords": ["pi-package", "pi-extension", "mcp"],
+  "pi": {
+    "extensions": ["./extensions/mcp-bridge"]
+  }
+}
+```
+
+Main modules:
+
+| File | Purpose |
+|---|---|
+| `extensions/mcp-bridge/index.ts` | Pi extension entry point. Registers lifecycle hooks and slash commands. Starts/stops enabled servers and registers tools. |
+| `config-discovery.ts` | Finds and parses known third-party MCP config files. Normalizes discovered server definitions. |
+| `config-sync.ts` | Reads/writes `~/.pi/mcp.json`, merges discovered servers, preserves manual entries, validates names, and performs atomic writes. |
+| `mcp-client.ts` | Starts MCP stdio server processes, initializes MCP clients, lists tools, forwards calls, and stops processes. |
+| `schema-conversion.ts` | Converts supported MCP JSON Schema input schemas to Pi/typebox schemas. |
+| `tool-registration.ts` | Generates Pi tool names, registers MCP-backed tools, truncates large outputs, and deactivates tools when servers stop. |
+| `logger.ts` | Writes redacted diagnostic logs to `~/.pi/mcp-bridge.log`. |
+| `types.ts` | Shared config and discovery types. |
+
+### Startup/session lifecycle
+
+On `session_start`:
+
+1. Discover external MCP configs.
+2. Sync discovered servers into `~/.pi/mcp.json`.
+3. Read the effective config, including optional project overrides.
+4. Stop servers that are no longer enabled.
+5. Start enabled servers only.
+6. Register supported tools from running servers.
+7. Notify a short summary in the TUI.
+
+On `session_shutdown`:
+
+1. Deactivate all registered MCP-backed tools.
+2. Stop all running MCP server processes.
+
+### Enable/disable lifecycle
+
+`/mcp-enable` with no argument:
+
+1. Runs discovery/sync first so newly detected servers appear.
+2. Reads the global config.
+3. Lists disabled servers.
+4. Opens a selector in interactive Pi sessions.
+5. Enables selected servers in `~/.pi/mcp.json`.
+6. Starts enabled servers and registers tools.
+
+`/mcp-disable` with no argument:
+
+1. Reads the effective config.
+2. Lists enabled servers.
+3. Opens a selector in interactive Pi sessions.
+4. Disables selected servers in `~/.pi/mcp.json`.
+5. Stops selected servers and deactivates their tools.
+
+Direct commands, such as `/mcp-enable <server>` and `/mcp-disable <server>`, skip the selector.
+
+### Tool naming
+
+Generated Pi tool names are prefixed with `mcp_` and include the normalized source/server/tool identity. Example:
+
+```text
+mcp_claude_desktop_filesystem_read_file
+```
+
+If a generated name collides, the registrar appends a deterministic short suffix.
+
+### Schema conversion
+
+The initial schema converter intentionally supports a conservative subset:
+
+- object schemas
+- required fields
+- strings
+- numbers
+- integers
+- booleans
+- arrays
+- nested objects
+- simple string enums
+
+Unsupported complex schemas are skipped for that specific MCP tool rather than crashing the extension.
+
+### Output handling
+
+MCP tool outputs can be large. The extension respects `maxOutputChars` and truncates returned tool text so Pi conversations do not balloon unexpectedly.
+
+### Logging and secrets
+
+The extension does not log to stdout because Pi owns stdout/TUI rendering. Detailed diagnostics go to:
+
+```text
+~/.pi/mcp-bridge.log
+```
+
+Logs redact common secret-bearing keys such as token, key, secret, password, auth, and credential. Still, avoid storing literal secrets in config files when possible.
+
+## Examples and fixtures
+
+- `examples/mcp.json.example` — example global Pi MCP config.
+- `examples/project-mcp.override.example.json` — example project override.
+- `fixtures/` — known third-party config shapes used by tests.
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run checks:
+
+```bash
+npm run typecheck
+npm test
+```
+
+Preview npm package contents before publishing:
+
+```bash
+npm pack --dry-run
+```
+
+## Publishing
+
+For a scoped public npm package:
+
+```bash
+npm run typecheck
+npm test
+npm pack --dry-run
+npm publish --access public
+```
+
+The package includes only the files listed in `package.json`'s `files` field.
+
+## Security checklist before enabling a server
+
+1. Run `/mcp-status` and inspect the server name, source, and command.
+2. Open `~/.pi/mcp.json` and review `command`, `args`, and `env`.
+3. Prefer environment variable references over literal secret values.
+4. Use `allowServers` and `denyServers` for project-level hardening.
+5. Review project-local `.pi/mcp.json` files before using Pi in untrusted repositories.
+6. Disable servers you are not actively using.
+
+See `SECURITY.md` for the short-form security policy.
+
+## License
+
+MIT. See `LICENSE`.

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security
+
+Pi extensions execute with your user permissions. MCP servers started by this package also execute with your user permissions.
+
+Before enabling an MCP server:
+
+1. Review the command and arguments in `~/.pi/mcp.json`.
+2. Prefer environment-variable references over literal secrets.
+3. Use `enabled: false` until you intentionally want to start a server.
+4. Use `allowServers` / `denyServers` to restrict startup when needed.
+5. Review project-local `.pi/mcp.json` files before running Pi in untrusted repositories.
+
+This extension redacts common secret key names in logs, but you should still avoid storing literal secrets in config files.

package/examples/mcp.json.example

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "autoStart": false,
+  "servers": {
+    "claude_desktop__filesystem": {
+      "enabled": false,
+      "managedBy": "pi-mcp-bridge",
+      "source": "claude-desktop",
+      "sourceName": "filesystem",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/fameftimie/work"],
+      "env": {}
+    },
+    "manual__example": {
+      "enabled": false,
+      "source": "manual",
+      "sourceName": "example",
+      "command": "example-mcp-server",
+      "args": [],
+      "env": {}
+    }
+  }
+}

package/examples/project-mcp.override.example.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "autoStart": false,
+  "maxOutputChars": 20000,
+  "allowServers": ["claude_desktop__filesystem", "codex__playwright"],
+  "denyServers": ["*production*"],
+  "servers": {
+    "manual__project_local": {
+      "enabled": false,
+      "source": "manual",
+      "sourceName": "project-local",
+      "command": "example-mcp-server",
+      "args": [],
+      "env": {}
+    }
+  }
+}

package/extensions/mcp-bridge/README.md

@@ -0,0 +1,51 @@
+# mcp-bridge
+
+Explicit opt-in MCP compatibility bridge for Pi.
+
+Current implementation covers Phase 1 through Phase 4:
+
+- discovers MCP config candidates from Claude Desktop, Claude Code, and Codex
+- syncs supported server entries into `~/.pi/mcp.json`
+- preserves manually added Pi MCP server entries
+- preserves `enabled` values for previously discovered managed entries
+- defaults newly discovered servers to `enabled: false`
+- writes a redacted debug log to `~/.pi/mcp-bridge.log`
+- provides explicit enable/disable controls with server-name validation and completions
+- serializes in-process config mutations to avoid command-handler races
+- starts enabled MCP stdio servers only
+- initializes MCP client sessions and lists tools
+- converts a conservative JSON Schema subset to Pi/typebox tool schemas
+- registers supported MCP tools as Pi tools
+- forwards Pi tool calls to MCP `tools/call`
+- stops/deactivates tools on disable, restart, and session shutdown
+- supports project-local `.pi/mcp.json` overrides
+- supports `allowServers`, `denyServers`, and `maxOutputChars`
+- includes fixtures/tests for hardening
+
+## Commands
+
+```text
+/mcp-sync
+/mcp-status
+/mcp-enable [server]
+/mcp-disable [server]
+/mcp-restart
+```
+
+`/mcp-enable <server>` updates `~/.pi/mcp.json` and immediately attempts to start that enabled server. In interactive Pi sessions, `/mcp-enable` with no argument rescans detected MCP configs, opens a small selector for disabled servers, and enables the selected servers. `/mcp-disable <server>` stops the server and deactivates its Pi tools. In interactive Pi sessions, `/mcp-disable` with no argument opens a small selector for enabled servers and disables the selected servers. `/mcp-restart` restarts one enabled server or all enabled servers.
+
+## Config hardening
+
+Optional settings in `~/.pi/mcp.json` or project-local `.pi/mcp.json`:
+
+```json
+{
+  "allowServers": ["claude_desktop__filesystem", "codex__*"],
+  "denyServers": ["*production*"],
+  "maxOutputChars": 20000
+}
+```
+
+## Safety invariant
+
+Installing or reloading this extension must never execute newly discovered MCP server commands. Discovered servers are synced as disabled by default and must be explicitly enabled before future bridge phases may start them.

package/extensions/mcp-bridge/config-discovery.ts

@@ -0,0 +1,143 @@
+import { access, readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import TOML from "@iarna/toml";
+import { MANAGED_BY, type DiscoveredMcpServer, type DiscoveryEvent, type DiscoveryResult, type McpSource } from "./types.js";
+
+interface Candidate {
+  source: McpSource;
+  path: string;
+  format: "json" | "toml";
+}
+
+const CANDIDATES: Candidate[] = [
+  { source: "claude-desktop", path: "~/Library/Application Support/Claude/claude_desktop_config.json", format: "json" },
+  { source: "claude-code", path: "~/.claude.json", format: "json" },
+  { source: "claude-code", path: "~/.claude/settings.json", format: "json" },
+  { source: "claude-code", path: "~/.config/claude-code/config.json", format: "json" },
+  { source: "claude-code", path: "~/.config/claude-code/settings.json", format: "json" },
+  { source: "codex", path: "~/.codex/config.toml", format: "toml" },
+  { source: "codex", path: "~/.codex/config.json", format: "json" },
+  { source: "codex", path: "~/.config/codex/config.toml", format: "toml" },
+  { source: "codex", path: "~/.config/codex/config.json", format: "json" },
+];
+
+export function expandHome(path: string): string {
+  return path === "~" ? homedir() : path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+}
+
+export async function discoverMcpServers(): Promise<DiscoveryResult> {
+  const servers: Record<string, DiscoveredMcpServer> = {};
+  const events: DiscoveryEvent[] = [];
+
+  for (const candidate of CANDIDATES) {
+    const path = expandHome(candidate.path);
+    try {
+      await access(path, constants.R_OK);
+      events.push({ path, source: candidate.source, status: "found" });
+    } catch {
+      events.push({ path, source: candidate.source, status: "missing" });
+      continue;
+    }
+
+    let parsed: unknown;
+    try {
+      const text = await readFile(path, "utf8");
+      parsed = candidate.format === "toml" ? TOML.parse(text) : JSON.parse(text);
+      events.push({ path, source: candidate.source, status: "parsed" });
+    } catch (error) {
+      events.push({ path, source: candidate.source, status: "parse-error", message: errorMessage(error) });
+      continue;
+    }
+
+    const maps = findMcpServerMaps(parsed);
+    if (maps.length === 0) {
+      events.push({ path, source: candidate.source, status: "unsupported", message: "No mcpServers or mcp_servers map found" });
+      continue;
+    }
+
+    let accepted = 0;
+    for (const map of maps) {
+      for (const [sourceName, rawServer] of Object.entries(map)) {
+        const normalized = normalizeServer(candidate.source, sourceName, rawServer, path);
+        if (!normalized) continue;
+        servers[makeServerKey(candidate.source, sourceName)] = normalized;
+        accepted++;
+      }
+    }
+
+    events.push({
+      path,
+      source: candidate.source,
+      status: accepted > 0 ? "contains-mcp" : "unsupported",
+      message: accepted > 0 ? `${accepted} MCP server(s)` : "MCP map found, but no supported server entries",
+    });
+  }
+
+  return { servers, events };
+}
+
+function findMcpServerMaps(value: unknown, depth = 0): Array<Record<string, unknown>> {
+  if (!value || typeof value !== "object" || Array.isArray(value) || depth > 5) return [];
+  const obj = value as Record<string, unknown>;
+  const maps: Array<Record<string, unknown>> = [];
+
+  for (const key of ["mcpServers", "mcp_servers", "mcpServersConfig"]) {
+    const maybe = obj[key];
+    if (maybe && typeof maybe === "object" && !Array.isArray(maybe)) {
+      maps.push(maybe as Record<string, unknown>);
+    }
+  }
+
+  for (const child of Object.values(obj)) {
+    if (child && typeof child === "object") {
+      maps.push(...findMcpServerMaps(child, depth + 1));
+    }
+  }
+
+  return maps;
+}
+
+function normalizeServer(source: McpSource, sourceName: string, raw: unknown, configPath: string): DiscoveredMcpServer | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const obj = raw as Record<string, unknown>;
+  const command = typeof obj.command === "string" ? obj.command : undefined;
+  if (!command) return null;
+
+  const args = Array.isArray(obj.args) ? obj.args.filter((arg): arg is string => typeof arg === "string") : [];
+  const env = normalizeEnv(obj.env);
+
+  return {
+    enabled: false,
+    managedBy: MANAGED_BY,
+    source,
+    sourceName,
+    command,
+    args,
+    env,
+    configPath,
+  };
+}
+
+function normalizeEnv(raw: unknown): Record<string, string> {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof value === "string") out[key] = value;
+    else if (typeof value === "number" || typeof value === "boolean") out[key] = String(value);
+  }
+  return out;
+}
+
+function makeServerKey(source: McpSource, sourceName: string): string {
+  return `${normalizeName(source)}__${normalizeName(sourceName)}`;
+}
+
+function normalizeName(value: string): string {
+  return value.replace(/[^A-Za-z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").toLowerCase() || "server";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}