@compilr-dev/cli 0.5.0 → 0.5.2

package/dist/ui/overlay/impl/mcp-overlay-v2.js

@@ -0,0 +1,907 @@
+/**
+ * MCP Overlay V2
+ *
+ * Shows connected MCP servers and their tools.
+ * Extends TabbedListOverlayV2 for consistent UI.
+ *
+ * Features:
+ * - Single tab (all servers)
+ * - Server list with status and tool count
+ * - Detail view with tool list
+ * - Restart/disconnect actions
+ * - Add server form (with hot-reload)
+ * - Empty state with config file instructions
+ */
+import { TabbedListOverlayV2, BaseScreen, stay, pushScreen, popScreen, closeOverlay, isEscape, isCtrlC, isQuit, isEnter, isSpace, isTab, isShiftTab, isBackspace, isDelete, isLeftArrow, isRightArrow, isUpArrow, isDownArrow, isHome, isEnd, isCtrlA, isCtrlE, isPrintable, getPrintableChar, renderBorder, truncate, wrapText, } from '../../base/index.js';
+import { getMCPConfigPath, saveMCPServer, getExistingServerNames, } from '../../../settings/mcp-config.js';
+// =============================================================================
+// Constants
+// =============================================================================
+const PAGE_SIZE = 8;
+// =============================================================================
+// Detail Screen
+// =============================================================================
+class ServerDetailScreen extends BaseScreen {
+    item;
+    manager;
+    styles;
+    getWidth;
+    onRefresh;
+    message = null;
+    selectedToolIndex = 0;
+    toolScrollOffset = 0;
+    /** Max tools visible in the scrollable list area */
+    static TOOL_PAGE_SIZE = 8;
+    constructor(item, manager, styles, getWidth, onRefresh) {
+        super();
+        this.item = item;
+        this.manager = manager;
+        this.styles = styles;
+        this.getWidth = getWidth;
+        this.onRefresh = onRefresh;
+    }
+    getMinHeight() {
+        return 20;
+    }
+    render() {
+        const s = this.styles;
+        const cols = this.getWidth();
+        const border = renderBorder(cols, s);
+        const lines = [];
+        // Re-read status from client (may have changed after restart/disconnect)
+        const currentStatus = this.item.client.status;
+        const statusDisplay = formatStatus(currentStatus, s);
+        // Header
+        lines.push(border);
+        lines.push(` ${s.primaryBold(`MCP Server: ${this.item.name}`)}`);
+        lines.push('');
+        // Server info
+        lines.push(`  ${s.secondary('Status:')}    ${statusDisplay}`);
+        lines.push(`  ${s.secondary('Transport:')} ${this.item.transport} ${s.muted(`\u2014 ${this.item.transportDetail}`)}`);
+        lines.push('');
+        // Message (after restart/disconnect)
+        if (this.message) {
+            lines.push(`  ${s.secondary(this.message)}`);
+            lines.push('');
+        }
+        // Tools
+        const tools = this.item.tools;
+        if (tools.length > 0) {
+            lines.push(`  ${s.secondary(`Tools (${String(tools.length)}):`)}`);
+            // Clamp selection
+            if (this.selectedToolIndex >= tools.length) {
+                this.selectedToolIndex = tools.length - 1;
+            }
+            // Adjust scroll offset to keep selection visible
+            const pageSize = ServerDetailScreen.TOOL_PAGE_SIZE;
+            if (this.selectedToolIndex < this.toolScrollOffset) {
+                this.toolScrollOffset = this.selectedToolIndex;
+            }
+            else if (this.selectedToolIndex >= this.toolScrollOffset + pageSize) {
+                this.toolScrollOffset = this.selectedToolIndex - pageSize + 1;
+            }
+            // Render visible tools
+            const visibleEnd = Math.min(this.toolScrollOffset + pageSize, tools.length);
+            // Scroll indicator (top)
+            if (this.toolScrollOffset > 0) {
+                lines.push(`    ${s.muted(`\u2191 ${String(this.toolScrollOffset)} more above`)}`);
+            }
+            for (let i = this.toolScrollOffset; i < visibleEnd; i++) {
+                const tool = tools[i];
+                const isSelected = i === this.selectedToolIndex;
+                const prefix = isSelected ? s.primary('  \u25ba ') : '    ';
+                const toolName = truncate(tool.name, 30);
+                const desc = tool.description
+                    ? s.muted(` \u2014 ${truncate(tool.description, Math.max(cols - 42, 20))}`)
+                    : '';
+                const name = isSelected ? s.primary(toolName) : toolName;
+                lines.push(`${prefix}${name}${desc}`);
+            }
+            // Scroll indicator (bottom)
+            const remaining = tools.length - visibleEnd;
+            if (remaining > 0) {
+                lines.push(`    ${s.muted(`\u2193 ${String(remaining)} more below`)}`);
+            }
+        }
+        else if (currentStatus === 'connected') {
+            lines.push(`  ${s.muted('No tools discovered.')}`);
+        }
+        else {
+            lines.push(`  ${s.muted('Server not connected \u2014 tools unavailable.')}`);
+        }
+        lines.push('');
+        // Pad to consistent height
+        while (lines.length < 16) {
+            lines.push('');
+        }
+        // Footer
+        lines.push(border);
+        const footerHint = tools.length > 0
+            ? '\u2191\u2193/jk Navigate \u00b7 Enter Details \u00b7 r Restart \u00b7 d Disconnect \u00b7 q/Esc Back'
+            : 'r Restart \u00b7 d Disconnect \u00b7 q/Esc Back';
+        lines.push(s.muted(`  ${footerHint}`));
+        return lines;
+    }
+    handleKey(data) {
+        if (isCtrlC(data)) {
+            return closeOverlay({ viewed: true });
+        }
+        if (isEscape(data) || isQuit(data)) {
+            return popScreen();
+        }
+        const char = data.toString();
+        const tools = this.item.tools;
+        // Tool navigation — Up/Down/j/k
+        if (tools.length > 0) {
+            if (isUpArrow(data) || char === 'k') {
+                if (this.selectedToolIndex > 0) {
+                    this.selectedToolIndex--;
+                }
+                return stay(true);
+            }
+            if (isDownArrow(data) || char === 'j') {
+                if (this.selectedToolIndex < tools.length - 1) {
+                    this.selectedToolIndex++;
+                }
+                return stay(true);
+            }
+            // Enter — push tool detail screen
+            if (isEnter(data)) {
+                const selectedTool = tools[this.selectedToolIndex];
+                return pushScreen(new MCPToolDetailScreen(selectedTool, this.item.name, this.styles, this.getWidth));
+            }
+        }
+        // Restart
+        if (char === 'r') {
+            this.message = 'Restarting...';
+            this.onRefresh();
+            void (async () => {
+                try {
+                    const client = this.item.client;
+                    await client.disconnect();
+                    await client.connect();
+                    const newTools = await client.listTools();
+                    this.item.tools = newTools;
+                    this.item.toolCount = newTools.length;
+                    this.selectedToolIndex = 0;
+                    this.toolScrollOffset = 0;
+                    this.message = `Restarted \u2014 ${String(newTools.length)} tools discovered`;
+                }
+                catch {
+                    this.message = 'Restart failed';
+                }
+                this.onRefresh();
+            })();
+            return stay(false);
+        }
+        // Disconnect
+        if (char === 'd') {
+            this.message = 'Disconnecting...';
+            this.onRefresh();
+            void (async () => {
+                try {
+                    await this.item.client.disconnect();
+                    this.item.tools = [];
+                    this.item.toolCount = 0;
+                    this.selectedToolIndex = 0;
+                    this.toolScrollOffset = 0;
+                    this.message = 'Disconnected';
+                    this.onRefresh();
+                }
+                catch {
+                    this.message = 'Disconnect failed';
+                }
+                this.onRefresh();
+            })();
+            return stay(false);
+        }
+        return stay(false);
+    }
+}
+// =============================================================================
+// Tool Detail Screen
+// =============================================================================
+/**
+ * Full-screen detail view for a single MCP tool.
+ * Shows name, description (word-wrapped), and input schema parameters.
+ * Follows the same pattern as ToolDetailScreen in tools-overlay-v2.
+ */
+class MCPToolDetailScreen extends BaseScreen {
+    tool;
+    serverName;
+    styles;
+    getWidth;
+    constructor(tool, serverName, styles, getWidth) {
+        super();
+        this.tool = tool;
+        this.serverName = serverName;
+        this.styles = styles;
+        this.getWidth = getWidth;
+    }
+    render() {
+        const s = this.styles;
+        const cols = this.getWidth();
+        const border = renderBorder(cols, s);
+        const maxLineWidth = cols - 2;
+        const lines = [];
+        // Header
+        lines.push(border);
+        lines.push(`  ${s.primaryBold('MCP Tool Details')}`);
+        lines.push('');
+        // Tool name (prefixed with server name)
+        lines.push(`  ${s.muted('Name:')}      ${s.primaryBold(`mcp_${this.serverName}_${this.tool.name}`)}`);
+        lines.push(`  ${s.muted('Server:')}    ${this.serverName}`);
+        lines.push('');
+        // Description (word-wrapped, never truncated)
+        lines.push(`  ${s.muted('Description:')}`);
+        const description = this.tool.description ?? 'No description available.';
+        const wrappedDesc = wrapText(description, Math.min(maxLineWidth - 4, 70));
+        for (const line of wrappedDesc) {
+            lines.push(`    ${s.secondary(line)}`);
+        }
+        lines.push('');
+        // Input schema parameters
+        const props = this.tool.inputSchema.properties;
+        const required = new Set(this.tool.inputSchema.required ?? []);
+        if (props && Object.keys(props).length > 0) {
+            const entries = Object.entries(props);
+            // Sort: required first, then optional
+            entries.sort(([a], [b]) => {
+                const aReq = required.has(a);
+                const bReq = required.has(b);
+                if (aReq && !bReq)
+                    return -1;
+                if (!aReq && bReq)
+                    return 1;
+                return 0;
+            });
+            lines.push(`  ${s.muted('Parameters:')}`);
+            for (const [paramName, paramDef] of entries) {
+                const def = paramDef;
+                const paramType = typeof def.type === 'string' ? def.type : 'any';
+                const isRequired = required.has(paramName);
+                const reqLabel = isRequired ? s.warning('*') : ' ';
+                const typeStr = s.muted(`(${paramType})`);
+                lines.push(`    ${reqLabel} ${s.secondary(paramName)} ${typeStr}`);
+                // Parameter description (word-wrapped under the param name)
+                if (typeof def.description === 'string') {
+                    const paramDescWrapped = wrapText(def.description, Math.min(maxLineWidth - 10, 64));
+                    for (const pdLine of paramDescWrapped) {
+                        lines.push(`      ${s.muted(pdLine)}`);
+                    }
+                }
+            }
+            lines.push('');
+            lines.push(`    ${s.muted('* = required')}`);
+        }
+        else {
+            lines.push(`  ${s.muted('Parameters:')}  ${s.muted('None')}`);
+        }
+        lines.push('');
+        // Footer
+        lines.push(border);
+        lines.push(`  ${s.muted('q/Esc Back')}`);
+        return lines;
+    }
+    handleKey(data) {
+        if (isCtrlC(data)) {
+            return closeOverlay({ viewed: true });
+        }
+        if (isEscape(data) || isQuit(data)) {
+            return popScreen();
+        }
+        return stay(false);
+    }
+    getMinHeight() {
+        return 20;
+    }
+}
+/**
+ * Form screen for adding a new MCP server.
+ * Text fields accept character input; cycle fields toggle with Enter/Space.
+ * Follows the same navigation pattern as /config overlay.
+ */
+class AddServerScreen extends BaseScreen {
+    agent;
+    getManager;
+    styles;
+    getWidth;
+    onServerAdded;
+    onRefresh;
+    projectRoot;
+    formState;
+    existingNames;
+    constructor(agent, getManager, styles, getWidth, onServerAdded, onRefresh, projectRoot) {
+        super();
+        this.agent = agent;
+        this.getManager = getManager;
+        this.styles = styles;
+        this.getWidth = getWidth;
+        this.onServerAdded = onServerAdded;
+        this.onRefresh = onRefresh;
+        this.projectRoot = projectRoot;
+        this.existingNames = getExistingServerNames(projectRoot);
+        const items = [
+            { type: 'text', id: 'name', label: 'Name', value: '', hint: 'Unique server name (e.g., filesystem)' },
+            { type: 'cycle', id: 'transport', label: 'Transport', value: 'stdio', options: ['stdio', 'http'] },
+            { type: 'text', id: 'command', label: 'Command', value: '', hint: 'Command to run (e.g., npx)' },
+            { type: 'text', id: 'args', label: 'Args', value: '', hint: 'Space-separated arguments (optional)' },
+        ];
+        // Add scope toggle only when a project is bound
+        if (this.projectRoot) {
+            items.push({ type: 'cycle', id: 'scope', label: 'Scope', value: 'Global', options: ['Global', 'Project'] });
+        }
+        this.formState = {
+            items,
+            activeIndex: 0,
+            cursorPos: 0,
+            saving: false,
+            message: null,
+        };
+    }
+    getMinHeight() {
+        return 20;
+    }
+    // ── helpers ──────────────────────────────────────────────────────────────
+    get activeItem() { return this.formState.items[this.formState.activeIndex]; }
+    get isTextItem() { return this.activeItem.type === 'text'; }
+    get transport() {
+        const t = this.formState.items.find((i) => i.id === 'transport');
+        return t ? t.value : 'stdio';
+    }
+    get scope() {
+        const s = this.formState.items.find((i) => i.id === 'scope');
+        return s ? s.value : 'Global';
+    }
+    get itemCount() { return this.formState.items.length; }
+    // ── render ───────────────────────────────────────────────────────────────
+    render() {
+        const s = this.styles;
+        const cols = this.getWidth();
+        const border = renderBorder(cols, s);
+        const lines = [];
+        const labelWidth = 12;
+        // Header
+        lines.push(border);
+        lines.push(` ${s.primaryBold('Add MCP Server')}`);
+        lines.push('');
+        for (let i = 0; i < this.formState.items.length; i++) {
+            const item = this.formState.items[i];
+            const isActive = i === this.formState.activeIndex && !this.formState.saving;
+            const prefix = isActive ? s.primary(' \u276f ') : '   ';
+            const label = isActive
+                ? s.primary(item.label.padEnd(labelWidth))
+                : s.secondary(item.label.padEnd(labelWidth));
+            // Skip args/headers row when it doesn't apply
+            if (item.id === 'args' && this.transport === 'http')
+                continue;
+            if (item.type === 'text') {
+                if (isActive) {
+                    const before = item.value.slice(0, this.formState.cursorPos);
+                    const after = item.value.slice(this.formState.cursorPos);
+                    const cursor = s.primaryBold('\u2502');
+                    lines.push(`${prefix}${label}${before}${cursor}${after}`);
+                }
+                else {
+                    const display = item.value || s.muted(item.hint);
+                    lines.push(`${prefix}${label}${display}`);
+                }
+                if (item.error) {
+                    lines.push(`   ${''.padEnd(labelWidth)}${s.error(item.error)}`);
+                }
+            }
+            else {
+                // Cycle toggle — render all options, highlight current
+                const optionStr = item.options
+                    .map((opt) => (opt === item.value ? s.primary(opt) : s.muted(opt)))
+                    .join(s.muted(' / '));
+                lines.push(`${prefix}${label}${optionStr}`);
+            }
+        }
+        lines.push('');
+        // Status message
+        if (this.formState.message) {
+            lines.push(`  ${this.formState.saving ? s.warning(this.formState.message) : s.success(this.formState.message)}`);
+        }
+        // Pad to consistent height
+        while (lines.length < 16) {
+            lines.push('');
+        }
+        // Footer
+        lines.push(border);
+        const hint = this.isTextItem
+            ? '\u2191\u2193 Navigate \u00b7 Type to edit \u00b7 Enter Submit \u00b7 Esc Cancel'
+            : '\u2191\u2193 Navigate \u00b7 Space Toggle \u00b7 Enter Submit \u00b7 Esc Cancel';
+        lines.push(s.muted(`  ${hint}`));
+        return lines;
+    }
+    // ── key handling ─────────────────────────────────────────────────────────
+    handleKey(data) {
+        if (isCtrlC(data)) {
+            return closeOverlay({ viewed: true });
+        }
+        if (this.formState.saving) {
+            return stay(false);
+        }
+        if (isEscape(data)) {
+            return popScreen();
+        }
+        // Navigation — Up/Down (always available)
+        if (isUpArrow(data) || isShiftTab(data)) {
+            return this.navigate(-1);
+        }
+        if (isDownArrow(data) || isTab(data)) {
+            return this.navigate(1);
+        }
+        // Enter always submits, regardless of active field
+        if (isEnter(data)) {
+            return this.handleSubmit();
+        }
+        // ── Cycle items: Space toggles ──────────────────────────────────────
+        if (this.activeItem.type === 'cycle') {
+            if (isSpace(data)) {
+                return this.cycleValue();
+            }
+            // Cycle items don't accept other input
+            return stay(false);
+        }
+        // At this point activeItem is guaranteed to be 'text' (cycle returned early above)
+        return this.handleTextInput(data);
+        return stay(false);
+    }
+    // ── text input handling ───────────────────────────────────────────────────
+    handleTextInput(data) {
+        const item = this.formState.items[this.formState.activeIndex];
+        if (item.type !== 'text')
+            return stay(false);
+        if (isBackspace(data)) {
+            if (this.formState.cursorPos > 0) {
+                item.value = item.value.slice(0, this.formState.cursorPos - 1) + item.value.slice(this.formState.cursorPos);
+                this.formState.cursorPos--;
+                item.error = undefined;
+            }
+            return stay(true);
+        }
+        if (isDelete(data)) {
+            if (this.formState.cursorPos < item.value.length) {
+                item.value = item.value.slice(0, this.formState.cursorPos) + item.value.slice(this.formState.cursorPos + 1);
+                item.error = undefined;
+            }
+            return stay(true);
+        }
+        if (isLeftArrow(data)) {
+            if (this.formState.cursorPos > 0)
+                this.formState.cursorPos--;
+            return stay(true);
+        }
+        if (isRightArrow(data)) {
+            if (this.formState.cursorPos < item.value.length)
+                this.formState.cursorPos++;
+            return stay(true);
+        }
+        if (isHome(data) || isCtrlA(data)) {
+            this.formState.cursorPos = 0;
+            return stay(true);
+        }
+        if (isEnd(data) || isCtrlE(data)) {
+            this.formState.cursorPos = item.value.length;
+            return stay(true);
+        }
+        if (isPrintable(data)) {
+            const ch = getPrintableChar(data);
+            if (ch) {
+                item.value = item.value.slice(0, this.formState.cursorPos) + ch + item.value.slice(this.formState.cursorPos);
+                this.formState.cursorPos++;
+                item.error = undefined;
+            }
+            return stay(true);
+        }
+        return stay(false);
+    }
+    // ── navigation helpers ───────────────────────────────────────────────────
+    navigate(direction) {
+        let next = this.formState.activeIndex + direction;
+        // Skip hidden items (args when transport is http)
+        while (next >= 0 && next < this.itemCount) {
+            const item = this.formState.items[next];
+            if (item.id === 'args' && this.transport === 'http') {
+                next += direction;
+                continue;
+            }
+            break;
+        }
+        if (next < 0 || next >= this.itemCount) {
+            return stay(false);
+        }
+        this.formState.activeIndex = next;
+        // Set cursor to end of text value when entering a text field
+        const newItem = this.formState.items[next];
+        if (newItem.type === 'text') {
+            this.formState.cursorPos = newItem.value.length;
+        }
+        return stay(true);
+    }
+    cycleValue() {
+        const item = this.activeItem;
+        if (item.type !== 'cycle')
+            return stay(false);
+        const currentIdx = item.options.indexOf(item.value);
+        const nextIdx = (currentIdx + 1) % item.options.length;
+        item.value = item.options[nextIdx];
+        // When transport changes, update the command/url field labels
+        if (item.id === 'transport') {
+            this.onTransportChange();
+        }
+        return stay(true);
+    }
+    onTransportChange() {
+        const isHttp = this.transport === 'http';
+        const cmdField = this.formState.items.find((i) => i.id === 'command' || i.id === 'url');
+        if (cmdField && cmdField.type === 'text') {
+            cmdField.id = isHttp ? 'url' : 'command';
+            cmdField.label = isHttp ? 'URL' : 'Command';
+            cmdField.hint = isHttp
+                ? 'Server URL (e.g., http://localhost:3000/mcp)'
+                : 'Command to run (e.g., npx)';
+            cmdField.error = undefined;
+        }
+    }
+    getTextItem(id) {
+        const item = this.formState.items.find((i) => i.id === id);
+        return item?.type === 'text' ? item : undefined;
+    }
+    handleSubmit() {
+        const nameField = this.getTextItem('name');
+        const cmdField = this.getTextItem('command') ?? this.getTextItem('url');
+        if (!nameField || !cmdField)
+            return stay(false);
+        let hasError = false;
+        const transport = this.transport;
+        // Name validation
+        const name = nameField.value.trim();
+        if (!name) {
+            nameField.error = 'Name is required';
+            hasError = true;
+        }
+        else if (this.existingNames.has(name)) {
+            nameField.error = 'Name already exists';
+            hasError = true;
+        }
+        else if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+            nameField.error = 'Only letters, numbers, hyphens, underscores';
+            hasError = true;
+        }
+        // Command/URL validation
+        const commandOrUrl = cmdField.value.trim();
+        if (!commandOrUrl) {
+            cmdField.error = `${transport === 'stdio' ? 'Command' : 'URL'} is required`;
+            hasError = true;
+        }
+        if (hasError)
+            return stay(true);
+        // Build config entry
+        const entry = {};
+        if (transport === 'stdio') {
+            entry.command = commandOrUrl;
+            const argsField = this.getTextItem('args');
+            const argsStr = argsField?.value.trim();
+            if (argsStr) {
+                entry.args = argsStr.split(/\s+/);
+            }
+        }
+        else {
+            entry.url = commandOrUrl;
+        }
+        const scope = this.scope === 'Project' ? 'project' : 'global';
+        // Save and connect
+        this.formState.saving = true;
+        this.formState.message = 'Connecting...';
+        this.onRefresh();
+        void (async () => {
+            try {
+                // 1. Save to config file
+                saveMCPServer(name, entry, scope, this.projectRoot);
+                // 2. Get or create manager
+                const manager = await this.getManager();
+                // 3. Add server and connect
+                const client = await manager.addServer({
+                    name,
+                    transport: transport,
+                    command: entry.command,
+                    args: entry.args,
+                    url: entry.url,
+                });
+                // 4. Discover tools
+                let tools = [];
+                try {
+                    tools = await client.listTools();
+                }
+                catch {
+                    // Tools may not be available yet
+                }
+                // 5. Register tools with agent
+                if (this.agent && tools.length > 0) {
+                    const agentTools = await manager.discoverToolsFrom(name);
+                    this.agent.registerTools(agentTools);
+                }
+                // 6. Build server item for the list
+                const newItem = {
+                    tabId: 'all',
+                    name,
+                    status: client.status,
+                    transport,
+                    transportDetail: entry.command ?? entry.url ?? '',
+                    toolCount: tools.length,
+                    tools,
+                    client,
+                };
+                // 7. Notify parent overlay
+                this.onServerAdded(newItem);
+                this.formState.saving = false;
+                this.formState.message = `Added "${name}" \u2014 ${String(tools.length)} tools`;
+                this.onRefresh();
+            }
+            catch (err) {
+                this.formState.saving = false;
+                this.formState.message = `Failed: ${err instanceof Error ? err.message : 'Unknown error'}`;
+                this.onRefresh();
+            }
+        })();
+        return stay(true);
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function formatStatus(status, s) {
+    switch (status) {
+        case 'connected':
+            return s.success('connected');
+        case 'connecting':
+            return s.warning('connecting');
+        case 'error':
+            return s.error('error');
+        case 'disconnected':
+            return s.muted('disconnected');
+        default:
+            return s.muted(status);
+    }
+}
+async function buildServerItems(manager) {
+    const items = [];
+    for (const client of manager.getServers()) {
+        let tools = [];
+        try {
+            if (client.isConnected) {
+                tools = await client.listTools();
+            }
+        }
+        catch {
+            // Failed to list tools — show 0
+        }
+        // Determine transport info from the client name
+        // We don't have direct access to config, so use what we can
+        const transport = client.isConnected ? 'stdio/http' : 'unknown';
+        items.push({
+            tabId: 'all',
+            name: client.name,
+            status: client.status,
+            transport,
+            transportDetail: '',
+            toolCount: tools.length,
+            tools,
+            client,
+        });
+    }
+    return items;
+}
+// =============================================================================
+// MCP Overlay V2
+// =============================================================================
+export class MCPOverlayV2 extends TabbedListOverlayV2 {
+    type = 'inline';
+    id = 'mcp-overlay-v2';
+    manager;
+    agent;
+    getManager;
+    projectRoot;
+    initialized = false;
+    listMessage = null;
+    constructor(manager, agent, getManager, projectRoot) {
+        const tabs = [
+            { id: 'all', label: 'All' },
+        ];
+        super({
+            title: 'MCP Servers',
+            tabs,
+            items: [],
+            pageSize: PAGE_SIZE,
+            filterByTab: () => true,
+            getSearchText: (item) => `${item.name} ${item.status} ${item.tools.map((t) => t.name).join(' ')}`,
+            renderItem: (item, isSelected, styles) => {
+                const prefix = isSelected ? styles.primary(' \u25ba ') : '   ';
+                const namePadded = item.name.padEnd(20);
+                const statusPadded = formatStatus(item.status, styles).padEnd(20);
+                const toolInfo = item.status === 'connected'
+                    ? styles.muted(`${String(item.toolCount)} tools`)
+                    : styles.muted('\u2014');
+                const name = isSelected ? styles.primary(namePadded) : namePadded;
+                return `${prefix}${name} ${statusPadded} ${toolInfo}`;
+            },
+            footerHints: (searchMode) => {
+                if (searchMode) {
+                    return 'Type to filter \u00b7 \u2191\u2193/jk Navigate \u00b7 Enter Details \u00b7 Esc Exit search';
+                }
+                return '\u2191\u2193/jk \u00b7 / Search \u00b7 Enter Details \u00b7 a Add \u00b7 r Restart \u00b7 d Disconnect \u00b7 q/Esc Close';
+            },
+            emptyMessage: '', // We handle empty state in render()
+            noResultsMessage: 'No servers match the search.',
+            showCount: false,
+        });
+        this.manager = manager;
+        this.agent = agent;
+        this.getManager = getManager;
+        this.projectRoot = projectRoot;
+        this.minHeight = 18;
+    }
+    /**
+     * Load server data on first render.
+     */
+    async loadItems() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        if (!this.manager)
+            return;
+        const items = await buildServerItems(this.manager);
+        this.state.items = items;
+        this.state.filteredItems = [...items];
+    }
+    /**
+     * Override render to load items on first call and handle empty state.
+     */
+    render(context) {
+        this.styles = context.styles;
+        this.termWidth = context.width;
+        // Async load — render loading state first, then re-render
+        if (!this.initialized) {
+            void this.loadItems().then(() => {
+                this.renderCallback?.();
+            });
+            const s = this.getStyles();
+            const border = renderBorder(context.width, s);
+            return {
+                lines: [
+                    border,
+                    ` ${s.primaryBold('MCP Servers')}`,
+                    '',
+                    `  ${s.muted('Loading...')}`,
+                    '',
+                    border,
+                    s.muted('  q/Esc Close'),
+                ],
+                minHeight: 18,
+            };
+        }
+        // Empty state — show config instructions (but allow 'a' to add)
+        if (this.state.items.length === 0 && this.screenStack.size() <= 1) {
+            return this.renderEmptyState(context);
+        }
+        // Inject list message if present (shown after add)
+        const result = super.render(context);
+        if (this.listMessage) {
+            const s = this.getStyles();
+            // Insert message before the footer border
+            const msg = `  ${s.success(this.listMessage)}`;
+            result.lines.splice(-3, 0, msg);
+            // Clear message after a brief display
+            setTimeout(() => {
+                this.listMessage = null;
+                this.renderCallback?.();
+            }, 3000);
+        }
+        return result;
+    }
+    /**
+     * Render helpful empty state with config file instructions.
+     */
+    renderEmptyState(context) {
+        const s = this.getStyles();
+        const border = renderBorder(context.width, s);
+        const configPath = getMCPConfigPath();
+        const lines = [
+            border,
+            ` ${s.primaryBold('MCP Servers')} ${s.muted('(0 configured)')}`,
+            '',
+            `  ${s.muted('No MCP servers configured.')}`,
+            '',
+            `  ${s.secondary('Press')} ${s.primary('a')} ${s.secondary('to add a server, or edit the config file:')}`,
+            `  ${s.muted(configPath)}`,
+            '',
+            `  ${s.muted('{')}`,
+            `  ${s.muted('  "mcpServers": {')}`,
+            `  ${s.muted('    "filesystem": {')}`,
+            `  ${s.muted('      "command": "npx",')}`,
+            `  ${s.muted('      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]')}`,
+            `  ${s.muted('    }')}`,
+            `  ${s.muted('  }')}`,
+            `  ${s.muted('}')}`,
+            '',
+            border,
+            s.muted('  a Add \u00b7 q/Esc Close'),
+        ];
+        return { lines, minHeight: 18 };
+    }
+    /**
+     * Handle custom keys (a/r/d) on the list screen.
+     * Only intercepts when the screen stack is at the root list screen.
+     */
+    handleKey(key) {
+        const char = key.raw.toString();
+        // Only handle custom keys when on the list screen (not on detail/add screens)
+        if (this.screenStack.size() <= 1 && !this.state.searchMode) {
+            // Add server
+            if (char === 'a') {
+                const styles = this.getStyles();
+                const addScreen = new AddServerScreen(this.agent, this.getManager, styles, () => this.termWidth, (newItem) => {
+                    // Callback: add new server to list, refresh
+                    this.state.items.push(newItem);
+                    this.state.filteredItems = [...this.state.items];
+                }, () => {
+                    this.renderCallback?.();
+                }, this.projectRoot);
+                this.screenStack.push(addScreen);
+                return this.rerender();
+            }
+            // Restart/disconnect only when items exist
+            if (this.state.filteredItems.length > 0) {
+                const selectedItem = this.state.filteredItems[this.state.selectedIndex];
+                // Restart selected server
+                if (char === 'r') {
+                    void (async () => {
+                        try {
+                            const client = selectedItem.client;
+                            await client.disconnect();
+                            await client.connect();
+                            const tools = await client.listTools();
+                            selectedItem.tools = tools;
+                            selectedItem.toolCount = tools.length;
+                            selectedItem.status = client.status;
+                        }
+                        catch {
+                            selectedItem.status = selectedItem.client.status;
+                        }
+                        this.renderCallback?.();
+                    })();
+                    return this.rerender();
+                }
+                // Disconnect selected server
+                if (char === 'd') {
+                    void (async () => {
+                        try {
+                            await selectedItem.client.disconnect();
+                            selectedItem.tools = [];
+                            selectedItem.toolCount = 0;
+                            selectedItem.status = 'disconnected';
+                        }
+                        catch {
+                            selectedItem.status = selectedItem.client.status;
+                        }
+                        this.renderCallback?.();
+                    })();
+                    return this.rerender();
+                }
+            }
+        }
+        return super.handleKey(key);
+    }
+    createDetailScreen(item) {
+        if (!this.manager)
+            return null;
+        const styles = this.getStyles();
+        return new ServerDetailScreen(item, this.manager, styles, () => this.termWidth, () => {
+            // Refresh list items after restart/disconnect in detail screen
+            this.renderCallback?.();
+        });
+    }
+}