@syntrologie/adapt-mcp

Dynamically loads @modelcontextprotocol/ext-apps modules at runtime and establishes bidirectional communication channels between interactive MCP app cards and the host environment. Uses lazy module resolution to defer loading until cards are instantiated, enabling hot-swapping of app implementations without restarting the MCP server. Bridges host capabilities back to cards via a message-passing protocol that maps card interactions to host-side handlers.

Manages the full lifecycle of interactive MCP app cards — instantiation, initialization, message routing, and cleanup. Handles card state initialization with configuration parameters, routes incoming messages from the host to appropriate card handlers, and manages resource cleanup on card unload. Implements a registry pattern to track active card instances and their associated message channels, enabling selective card updates without affecting other running cards.

Exposes host-side capabilities (file system access, API calls, database queries, etc.) to MCP app cards through a message-based capability proxy system. Cards send capability requests as structured messages; the host intercepts these messages, executes the requested capability, and returns results back to the card. Uses a handler registry pattern where developers register capability handlers that map card requests to host implementations, enabling fine-grained access control and capability isolation.

Routes incoming messages from MCP app cards to appropriate handlers and manages response delivery back to the originating card. Implements a message queue with handler dispatch logic that matches message types to registered handlers, executes handlers with proper error handling, and returns responses or errors back through the message channel. Supports request-response correlation to ensure responses reach the correct card instance even when multiple cards send messages concurrently.

Accepts and applies configuration parameters to MCP app cards during instantiation, enabling cards to be customized without code changes. Validates configuration against a schema (if provided), merges configuration with defaults, and passes the resolved configuration to card initialization handlers. Supports hierarchical configuration with environment variable overrides, enabling deployment-time customization without modifying card code or configuration files.