MBro

Magg implements a hub-and-spoke proxy architecture that connects to multiple backend MCP servers and exposes their tools through a single aggregated MCP interface. It uses a MaggServer class that manages ServerManager instances for each connected backend, routes tool calls to appropriate servers based on configurable prefixes (e.g., calc_add, pw_screenshot), and maintains full MCP protocol semantics including notifications, progress updates, and resource management. The system dynamically discovers and registers tools from all connected servers without requiring manual tool definition.

MBRO is an interactive terminal REPL client that connects to MCP servers and provides real-time tab completion for tool names, arguments, and available resources. It implements a command processing system that parses user input, introspects connected MCP servers to extract tool schemas and documentation, and renders formatted output with syntax highlighting. The browser maintains connection state across multiple MCP servers and automatically generates contextual help based on tool schemas without requiring manual documentation maintenance.

MBRO maintains independent connection state for each MCP server, tracking authentication tokens, tool schemas, resource lists, and connection status separately. The connection manager handles concurrent requests to multiple servers without blocking, implements per-server timeout and retry logic, and provides connection pooling for HTTP-based servers. Each server connection is isolated — failures in one server don't affect others, and authentication credentials are stored per-server.

Magg provides a comprehensive CLI interface (magg.cli:main) for starting servers, managing configurations, handling authentication, and managing kits. The CLI supports subcommands for server startup (with transport mode selection), configuration validation, authentication token generation, kit installation/updates, and server status monitoring. Commands are composable and support both interactive and scripted usage, with detailed help text and error messages.

Magg automatically introspects connected MCP servers to extract tool schemas (argument types, descriptions, required fields) and generates documentation without manual maintenance. The introspection system queries each server's tool list on connection, caches schemas for performance, and provides schema-based validation and help text generation. Documentation is automatically formatted for display in MBRO with argument descriptions, type information, and usage examples extracted from schemas.

Magg abstracts MCP communication through FastMCP framework, supporting three transport modes: stdio (direct process pipes for desktop clients), HTTP (REST API for web/remote access), and hybrid (both simultaneously). The transport layer is selected at server startup and handles serialization, deserialization, and protocol framing for each mode. Stdio mode uses JSON-RPC over stdin/stdout for low-latency local communication, HTTP mode exposes MCP as REST endpoints with request/response marshaling, and hybrid mode runs both transports in parallel with shared state.

Magg uses watchdog-based file system monitoring to detect changes to configuration files (server definitions, tool prefixes, authentication settings) and automatically reloads them without server restart. The ConfigManager class watches the configuration directory, detects file modifications, validates new configuration against schema, and applies changes to running ServerManager instances. This enables adding/removing backend MCP servers, changing tool prefixes, or updating authentication settings in real-time while maintaining active client connections.

Magg implements a BearerAuthManager class that validates JWT tokens in HTTP requests and stdio connections, enforcing authentication before tool access. The system generates and validates bearer tokens with configurable expiration, supports multiple authentication backends, and integrates with the MCP protocol's authentication handshake. Authentication can be enabled per-server or globally, and tokens are validated on every tool call without caching.

Magg provides a KitManager that packages MCP server definitions, tool configurations, and dependencies into distributable 'kits'. Kits are versioned bundles containing server startup commands, tool prefix mappings, authentication settings, and documentation. The system supports kit installation, updates, and removal through CLI commands, with automatic dependency resolution and configuration merging. Kits can be stored locally or fetched from remote repositories.

Magg implements a message routing layer that intercepts MCP protocol messages, determines the target backend server based on tool name prefixes, and forwards requests to the appropriate ServerManager instance. The proxy maintains per-server connection state, handles response aggregation, and manages error handling for individual server failures. Routing decisions are made based on configurable prefix mappings (e.g., 'calc_' routes to calculator server), with fallback to default server if no prefix matches.

Magg's ServerManager class handles the complete lifecycle of backend MCP server connections: spawning processes (for stdio mode), establishing HTTP connections, monitoring health status, and graceful shutdown. The system tracks connection state, detects server crashes or disconnections, and implements automatic reconnection with exponential backoff. Health monitoring uses periodic heartbeat messages or HTTP health checks to detect unresponsive servers without blocking client requests.

MBRO implements an output formatting system that renders MCP tool responses with syntax highlighting, structured data formatting, and terminal-aware layout. The system detects response content types (JSON, text, binary), applies appropriate formatters, and uses ANSI color codes for syntax highlighting. Complex nested structures are formatted with indentation and collapsible sections, while binary data is displayed as hex dumps or base64 encoding. The formatter respects terminal width and wraps long lines appropriately.

MBRO implements a command processing system that parses user input into structured MCP tool calls, validates arguments against tool schemas, and provides helpful error messages for invalid input. The parser supports multiple input formats (natural language-like commands, JSON, YAML), performs type coercion based on schema definitions, and suggests corrections for typos or missing arguments. Input validation happens before sending requests to MCP servers, reducing round-trip latency for invalid calls.