@pi-unipi/mcp 0.1.14 → 2.0.0

package/README.md

@@ -1,32 +1,45 @@
 # @pi-unipi/mcp
 
-MCP (Model Context Protocol) server management extension for Pi coding agent. Browse a catalog of 7,800+ MCP servers, add them interactively, and use their tools seamlessly within pi.
+Browse a catalog of 7,800+ MCP servers, add them interactively, and use their tools in Pi. MCP (Model Context Protocol) servers expose external capabilities — GitHub operations, database queries, file system access — as tools the agent can call.
 
-## Features
-
-- **Browse Catalog**: Search and discover MCP servers from the awesome-mcp-servers collection
-- **Interactive Add**: Split-pane overlay with server browser + JSON config editor
-- **Settings Management**: Enable/disable, edit, delete servers with scope switching
-- **Config Hierarchy**: Global defaults with project-level overrides
-- **Auto-Discovery**: Tools from MCP servers are automatically registered as pi tools
-- **Offline Support**: Bundled seed catalog with 49 curated servers as fallback
+The add command opens a split-pane overlay: server browser on the left, JSON config editor on the right. Pick a server, edit its config, save. Tools from added servers are automatically registered as Pi tools with the pattern `{serverName}__{toolName}`.
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `/unipi:mcp-add` | Open browse + editor overlay to add MCP servers |
+| `/unipi:mcp-add` | Open browse and editor overlay to add MCP servers |
 | `/unipi:mcp-settings` | Interactive settings with enable/disable/edit |
 | `/unipi:mcp-sync` | Force sync server catalog from GitHub |
 | `/unipi:mcp-status` | Text summary of all configured servers |
 
-## Setup
+### Setup Flow
+
+1. Run `/unipi:mcp-add`
+2. Browse or search the server catalog
+3. Edit the config in the right pane
+4. Save and restart Pi to activate
+
+## Special Triggers
+
+When MCP is installed, all workflow skills get access to MCP server tools. Tools are named `{serverName}__{toolName}` — for example, `github__search_code` or `filesystem__read_file`.
 
-1. Install as part of the unipi extension suite
-2. Add MCP servers via `/unipi:mcp-add` or manually edit config files
-3. Restart pi to activate newly added servers
+MCP registers with the info-screen dashboard, showing server count, active servers, and total tools. The footer subscribes to `MCP_SERVER_STARTED`, `MCP_SERVER_STOPPED`, and `MCP_SERVER_ERROR` events to display MCP status.
 
-## Configuration
+## Agent Tools
+
+MCP tools are registered dynamically based on configured servers. Once a server is added and Pi restarts, its tools become available to the agent.
+
+Example tool calls:
+```
+github__search_code({ query: "authentication middleware" })
+github__list_pull_requests({ state: "open" })
+filesystem__read_file({ path: "/home/user/config.json" })
+```
+
+The agent doesn't need to know about MCP directly — tools appear in its tool list with the server prefix.
+
+## Configurables
 
 ### File Locations
 
@@ -63,47 +76,21 @@ MCP (Model Context Protocol) server management extension for Pi coding agent. Br
 
 ### Config Merge Rules
 
-1. Server exists only in global → loaded normally
-2. Server exists only in project → loaded normally
-3. Server exists in both → **project wins entirely**
-4. `"enabled": false` in project metadata → **disabled** even if defined globally
+1. Server exists only in global — loaded normally
+2. Server exists only in project — loaded normally
+3. Server exists in both — project wins entirely
+4. `"enabled": false` in project metadata — disabled even if defined globally
 
-## Tool Naming
+## Troubleshooting
 
-MCP tools are registered with the pattern `{serverName}__{toolName}`:
-- `github__search_code`
-- `filesystem__read_file`
-- `brave-search__brave_web_search`
+**Server won't start:** Check `/unipi:mcp-status` for errors, verify the command exists on your system.
 
-## Architecture
+**Tools not appearing:** Ensure the server is running and supports the MCP protocol.
 
-```
-packages/mcp/
-├── src/
-│   ├── index.ts              # Extension entry, command registration
-│   ├── types.ts              # TypeScript interfaces
-│   ├── config/
-│   │   ├── schema.ts         # Defaults and validation
-│   │   ├── manager.ts        # Config read/merge/write
-│   │   └── sync.ts           # Catalog fetch and caching
-│   ├── bridge/
-│   │   ├── client.ts         # MCP JSON-RPC client (stdio)
-│   │   ├── translator.ts     # MCP tool → pi tool
-│   │   └── registry.ts       # Server lifecycle management
-│   └── tui/
-│       ├── add-overlay.ts    # /unipi:mcp-add UI
-│       └── settings-overlay.ts # /unipi:mcp-settings UI
-├── data/
-│   └── seed-servers.json     # Offline fallback catalog (49 servers)
-├── skills/mcp/
-│   └── SKILL.md              # Agent instructions
-├── package.json
-└── README.md
-```
+**Config issues:** Validate JSON syntax and check file permissions.
 
-## Troubleshooting
+**Sync issues:** Run `/unipi:mcp-sync`, check network. The seed catalog (49 servers) is available offline as fallback.
+
+## License
 
-- **Server won't start**: Check `/unipi:mcp-status` for errors, verify command exists
-- **Tools not appearing**: Ensure server is running, check MCP protocol support
-- **Config issues**: Validate JSON syntax, check file permissions
-- **Sync issues**: Run `/unipi:mcp-sync`, check network, seed catalog available offline
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/mcp",
-  "version": "0.1.14",
+  "version": "2.0.0",
   "description": "MCP server management extension for Pi coding agent — browse, add, configure, and use MCP servers",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -4,7 +4,7 @@
  * Registers commands, handles session lifecycle, wires up MCP server management.
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import {
   UNIPI_EVENTS,
   MODULES,
@@ -27,8 +27,7 @@ let registry: ServerRegistry | null = null;
 
 /** Get info registry from global */
 function getInfoRegistry() {
-  const g = globalThis as any;
-  return g.__unipi_info_registry;
+  return globalThis.__unipi_info_registry;
 }
 
 /** Get the server registry (for commands) */
@@ -178,7 +177,7 @@ export default function (pi: ExtensionAPI) {
   // /unipi:mcp-status — text summary of all servers
   pi.registerCommand(`unipi:${MCP_COMMANDS.STATUS}`, {
     description: "Show status of all configured MCP servers",
-    handler: async (_args: string, ctx: any) => {
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
       const reg = getRegistry();
       if (!reg) {
         ctx.ui.notify("MCP extension not initialized", "warning");
@@ -226,7 +225,7 @@ export default function (pi: ExtensionAPI) {
   // /unipi:mcp-sync — force catalog sync
   pi.registerCommand(`unipi:${MCP_COMMANDS.SYNC}`, {
     description: "Sync MCP server catalog from GitHub",
-    handler: async (_args: string, ctx: any) => {
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
       try {
         ctx.ui.notify("Syncing MCP catalog from GitHub...", "info");
         const catalog = await syncCatalog();
@@ -250,7 +249,7 @@ export default function (pi: ExtensionAPI) {
   // /unipi:mcp-add — add server overlay
   pi.registerCommand(`unipi:${MCP_COMMANDS.ADD}`, {
     description: "Add an MCP server (browse catalog or custom config)",
-    handler: async (_args: string, ctx: any) => {
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
       if (!ctx.hasUI) {
         ctx.ui.notify("MCP Add requires an interactive UI.", "warning");
         return;
@@ -278,7 +277,7 @@ export default function (pi: ExtensionAPI) {
   // /unipi:mcp-settings — settings overlay
   pi.registerCommand(`unipi:${MCP_COMMANDS.SETTINGS}`, {
     description: "Manage MCP server settings",
-    handler: async (_args: string, ctx: any) => {
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
       if (!ctx.hasUI) {
         ctx.ui.notify("MCP Settings requires an interactive UI.", "warning");
         return;
@@ -312,7 +311,7 @@ export default function (pi: ExtensionAPI) {
   // /unipi:mcp-reload — restart all MCP servers
   pi.registerCommand(`unipi:${MCP_COMMANDS.RELOAD}`, {
     description: "Reload all MCP servers (restart with current config)",
-    handler: async (_args: string, ctx: any) => {
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
       const reg = getRegistry();
       if (!reg) {
         ctx.ui.notify("MCP extension not initialized", "warning");

package/src/tui/add-overlay.ts

@@ -16,8 +16,10 @@ import {
   Key,
   matchesKey,
   truncateToWidth,
+  type TUI,
   visibleWidth,
 } from "@mariozechner/pi-tui";
+import type { Theme, KeybindingsManager } from "@mariozechner/pi-coding-agent";
 import type { CatalogEntry, CatalogData, McpConfig, McpMetadata } from "../types.js";
 import { loadCatalog } from "../config/sync.js";
 import {
@@ -106,9 +108,9 @@ export function renderMcpAddOverlay(params?: {
   onComplete?: () => void;
 }) {
   return (
-    tui: any,
-    theme: any,
-    _kb: any,
+    tui: TUI,
+    theme: Theme,
+    _kb: KeybindingsManager,
     done: (result: { saved: boolean } | null) => void,
   ) => {
     const scope = params?.scope ?? "global";
@@ -141,13 +143,13 @@ export function renderMcpAddOverlay(params?: {
     }
 
     const editorTheme: EditorTheme = {
-      borderColor: (s: any) => theme.fg("accent", s),
+      borderColor: (s: string) => theme.fg("accent", s),
       selectList: {
-        selectedPrefix: (t: any) => theme.fg("accent", t),
-        selectedText: (t: any) => theme.fg("accent", t),
-        description: (t: any) => theme.fg("muted", t),
-        scrollInfo: (t: any) => theme.fg("dim", t),
-        noMatch: (t: any) => theme.fg("warning", t),
+        selectedPrefix: (t: string) => theme.fg("accent", t),
+        selectedText: (t: string) => theme.fg("accent", t),
+        description: (t: string) => theme.fg("muted", t),
+        scrollInfo: (t: string) => theme.fg("dim", t),
+        noMatch: (t: string) => theme.fg("warning", t),
       },
     };
     const editor = new Editor(tui, editorTheme);

package/src/tui/settings-overlay.ts

@@ -5,7 +5,8 @@
  * edit, delete, scope switching, and sync trigger.
  */
 
-import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import { Key, matchesKey, truncateToWidth, type TUI, visibleWidth } from "@mariozechner/pi-tui";
+import type { Theme, KeybindingsManager } from "@mariozechner/pi-coding-agent";
 import type { ServerState } from "../types.js";
 import {
   loadMcpConfig,
@@ -49,9 +50,9 @@ export function renderMcpSettingsOverlay(params?: {
   onComplete?: () => void;
 }) {
   return (
-    tui: any,
-    theme: any,
-    _kb: any,
+    tui: TUI,
+    theme: Theme,
+    _kb: KeybindingsManager,
     done: (result: { action?: string } | null) => void,
   ) => {
     const registry = params?.registry;