mcphub.nvim

Manages both local STDIO-based MCP servers and remote HTTP/SSE servers through a central MCPHub.Hub class that orchestrates an external Node.js service (mcp-hub) while maintaining Lua-native server support within Neovim. Implements process spawning, health monitoring, graceful shutdown, and real-time state synchronization across multiple Neovim instances using event-driven architecture.

Provides plugin-specific adapters that transform MCP tools, resources, and prompts into native formats for Avante.nvim, CodeCompanion.nvim, and CopilotChat.nvim. Uses an extension system that maps MCP capabilities to plugin-specific APIs (e.g., @{mcp} mentions for CodeCompanion, use_mcp_tool functions for Avante) with real-time synchronization of available tools and granular auto-approval mechanisms.

Manages MCP prompt templates with support for variable substitution and context-aware rendering. Implements a system for defining reusable prompts with placeholders that are filled from tool outputs, editor state, or user input. Supports prompt composition (combining multiple prompts) and conditional rendering based on context. Integrates with CodeCompanion.nvim for slash-command based prompt invocation.

Implements comprehensive error handling for server startup failures, connection errors, tool execution failures, and configuration issues. Provides detailed error messages with diagnostic information (logs, stack traces, version mismatches) that help developers identify and resolve problems. Includes automatic recovery mechanisms like connection retries with exponential backoff and graceful degradation when servers become unavailable.

Enables developers to write MCP servers directly in Lua that execute within the Neovim process without external dependencies. Servers are defined using Lua tables with tool and resource definitions, eliminating the need for separate Node.js processes while maintaining full MCP protocol compliance. Integrates with Neovim's Lua runtime for direct access to editor state and plugin APIs.

Provides a Neovim UI for browsing, searching, and installing MCP servers from a centralized marketplace. Implements a marketplace view that displays server metadata (description, author, tags), handles dependency resolution, and manages installation into the local configuration. Uses HTTP requests to fetch marketplace data and file I/O to persist configurations.

Maintains consistent MCP server state across multiple Neovim instances using an event-driven architecture where the external mcp-hub service broadcasts state changes to all connected clients. Implements event subscriptions for server status, tool availability, and resource updates with automatic reconnection and conflict resolution. Uses WebSocket or HTTP polling for real-time updates.

Manages MCP server configuration through TOML/YAML files with strict schema validation and version compatibility checking. Implements a configuration system that validates server definitions against a schema, checks Node.js and plugin version compatibility (currently enforcing mcp-hub 4.1.0+ and plugin 5.13.0+), and provides clear error messages for misconfigurations. Supports environment variable substitution and inheritance patterns.

Provides a Neovim-native UI (using Lua-based UI components) for viewing server status, testing tools interactively, browsing available resources, and configuring auto-approval policies. Implements a main view showing all servers with status indicators, a marketplace view for discovery, and tool testing interfaces that allow developers to invoke tools with custom parameters and inspect responses without leaving the editor.

Implements a flexible auto-approval system that supports approval decisions at multiple levels: global (all tools), per-server, and per-tool. Supports custom Lua functions for dynamic approval logic that can inspect tool names, parameters, and context before deciding whether to auto-approve, require manual approval, or deny execution. Integrates with chat plugins' approval mechanisms to provide consistent behavior across different interfaces.

Executes MCP tools asynchronously without blocking the Neovim UI, with support for streaming responses that are progressively rendered as data arrives. Implements callback-based execution patterns that integrate with Neovim's event loop, allowing long-running tools to provide incremental results. Handles tool timeouts, cancellation, and error recovery gracefully.

Provides mechanisms for accessing MCP resources through URI-based retrieval, with support for embedding resources directly into chat contexts. Implements resource caching to avoid redundant fetches, URI validation, and content type detection. Resources can be text, binary, or structured data, with automatic formatting for different chat plugin contexts (e.g., markdown for Avante, structured references for CodeCompanion).