#Architecture

MoMCP-TUI follows a modular architecture with clear separation of concerns.

#High-Level Architecture

MoMCP-TUI is organized into four layers. The TUI Layer handles all user interaction through Textual, including the chat interface, modal dialogs, and command palette. The Core Layer contains the LLM client for communicating with model APIs, the MCP manager for orchestrating tool servers, and the config manager. The MCP Layer manages connections to local (stdio) and remote (HTTP) tool servers. The Utility Layer provides cross-cutting concerns like token compression, cancellation, clipboard access, and internationalization.

graph TB
    subgraph "TUI Layer (Textual)"
        A[MomcpTUI App] --> B[Chat UI]
        A --> C[Modal Dialogs]
        A --> D[Command Palette]
    end

    subgraph "Core Layer"
        A --> E[LLM Client]
        A --> F[MCP Manager]
        A --> G[Config Manager]
    end

    subgraph "MCP Layer"
        F --> H[MCP Servers]
        H --> I[stdio transport]
        H --> J[HTTP transport]
    end

    subgraph "Utility Layer"
        A --> K[Compression]
        A --> L[Cancellation]
        A --> M[Clipboard]
        A --> N[Locale]
    end

    E -->|HTTP/SSE| O[LLM Provider API]

#Request Flow

When you send a message, the TUI appends it to the conversation history and passes the full context along with available tool definitions to the LLM client. The LLM streams back its thinking process and response in real-time. If the model decides a tool is needed, it emits a tool call event — the TUI routes this to the MCP manager, which executes the tool on the appropriate server and feeds the result back to the LLM. This loop can repeat up to 12 times for complex multi-step tasks.

sequenceDiagram
    participant U as User
    participant T as TUI
    participant L as LLM Client
    participant M as MCP Manager
    participant S as MCP Server

    U->>T: Type message
    T->>T: Append to history
    T->>L: Send messages + tools
    L-->>T: Stream: thinking delta
    L-->>T: Stream: content delta
    alt Tool call needed
        L-->>T: Tool call event
        T->>M: Execute tool
        M->>S: MCP call_tool
        S-->>M: Result
        M-->>T: Result
        T->>L: Tool result
        L-->>T: Final response
    end
    T-->>U: Display response

#Threading Model

MoMCP-TUI uses a multi-thread architecture:

The MCP manager runs its own asyncio event loop in a daemon thread, using run_coroutine_threadsafe to bridge sync/async boundaries.

#Key Design Decisions

1. Sync-first TUI: The Textual app runs synchronously; LLM calls happen in background threads
2. Async MCP: MCP servers use asyncio for concurrent tool calls
3. Token-based compression: Conversations are compressed when they exceed max_context_tokens
4. Whitelist security: File access is restricted to explicitly allowed paths