Overview

Relevant source files

• README.md
• package-lock.json
• package.json

Purpose and Scope

TUUI (Tool Unitary User Interface) is a desktop Electron application that functions as a Model Context Protocol (MCP) client for orchestrating Large Language Model (LLM) interactions. This document provides a high-level architectural overview of the system, explaining how the main components interact and where key functionality resides in the codebase.

Scope: This page covers the overall system architecture, component organization, and fundamental data flows. For detailed information about specific subsystems, see:

• MCP integration details: MCP System
• LLM communication: Chat and LLM Integration
• User interface components: User Interface Framework
• Configuration management: Configuration and Settings

Application Identity

TUUI is defined in package.json1-10 with the following identity:

Property	Value
Name	tuui
App ID	com.tuui.app
Version	1.3.8
Schema Version	1.3
Description	Tool Unitary User Interface
Main Entry	dist/main/index.js
License	Apache-2.0

Sources: package.json1-10 README.md1-6

Architectural Foundation

Electron Process Model

TUUI follows the standard Electron multi-process architecture with clear separation of concerns:

Key Separation Principles:

• Main Process: System-level operations, MCP client management, file I/O, native OS integration
• Renderer Process: User interface, state management, user interactions
• IPC Layer: Bidirectional communication bridge via IPCs.ts and utils/index.ts

Sources: src/main/index.ts src/main/IPCs.ts src/renderer/utils/index.ts

Technology Stack

TUUI is built on the following core technologies, as defined in package.json49-70:

Technology	Version	Role
Electron	39.2.7	Desktop application framework
Vue 3	3.5.26	Reactive UI framework
Vuetify	3.11.6	Material Design UI components
TypeScript	5.9.3	Type-safe development
Pinia	3.0.4	State management
Vue Router	4.6.4	Client-side routing
@modelcontextprotocol/sdk	1.25.1	MCP protocol implementation
@anthropic-ai/mcpb	2.1.2	MCP bundle support
Vite	7.3.0	Build tool and dev server

Sources: package.json49-70 package.json72-99

Directory Structure

Sources: src/main/ src/renderer/ src/preload/

Core Functional Areas

1. Application Lifecycle Management

The main process entry point src/main/index.ts manages:

• Electron application initialization (app.whenReady())
• Main window creation (createWindow())
• Global shortcut registration
• Error window handling
• IPC handler initialization

2. MCP Client System

Located in src/main/mcp/ the MCP subsystem handles:

• init.ts: Client factory and initialization logic
• client.ts: Client pool and lifecycle management
• config.ts: Configuration file loading and watching
• dxt.ts: DXT/MCPB bundle handling

3. Inter-Process Communication

Two-way communication bridge:

• Main-side: src/main/IPCs.ts - Handler registry with dynamic capability-based registration
• Renderer-side: src/renderer/utils/index.ts - Type-safe IPC abstractions (Utils class)

4. User Interface Layer

Vue 3 application in src/renderer/:

• Screens: Route-level components (ChatScreen, McpScreen, AgentScreen, SettingScreen)
• Components: Reusable UI elements (MarkdownCard, ConfigCards, ElicitationCard)
• Stores: Pinia state management (useMcpStore, useMessageStore, useChatbotStore, useAgentStore)
• Router: Vue Router navigation

5. Configuration System

Configuration files in src/main/assets/config/:

• mcp.json: MCP server definitions (stdio, NPX, UVX, Docker, Remote)
• llm.json: LLM endpoint configurations (API keys, URLs, models)
• startup.json: Startup screen content
• popup.json: Popup prompt definitions

Sources: src/main/assets/config/mcp.json src/main/assets/config/llm.json

Data Flow Architecture

Request Flow Example (Tool Call):

1. User types message in ChatScreen component
2. useMessageStore updates conversation state
3. chatCompletions.ts invokes via Utils.invoke('msgToolsCall', ...)
4. Main process IPCs.ts routes to appropriate MCP client
5. MCP client executes tool via JSON-RPC to MCP server
6. Response flows back through IPC to renderer
7. useMessageStore updates with tool result
8. UI reactively displays updated conversation

Sources: src/renderer/utils/index.ts src/main/IPCs.ts src/renderer/stores/ src/renderer/composables/chatCompletions.ts

MCP Feature Support Matrix

TUUI implements the following MCP capabilities as documented in README.md28-39:

Feature	Status	Implementation Location
Tools	✅	src/main/mcp/client.ts - Tool discovery and execution
Prompts	✅	src/main/mcp/client.ts - Prompt template management
Resources	✅	src/main/mcp/client.ts - Resource access
Sampling	✅	src/renderer/components/SamplingCard.vue - LLM sampling requests
Elicitation	✅	src/renderer/components/ElicitationCard.vue - User input collection
Discovery	✅	src/renderer/screens/McpScreen.vue - MCP registry integration
MCPB	✅	src/main/mcp/dxt.ts - Bundle management
Roots	🔲	Not implemented (IDE-specific feature)

Sources: README.md28-39 src/main/mcp/

Configuration and Persistence

Runtime Configuration Flow

Configuration Precedence:

1. Default Configs: src/main/assets/config/ - Bundled with application
2. User Configs: Stored in LocalForage (IndexedDB) - Persisted across sessions
3. Runtime Overrides: Temporary in-memory modifications

Persistence Plugin: package.json64 - pinia-plugin-state-persistence automatically syncs Pinia stores to IndexedDB

Sources: src/main/assets/config/ src/main/Constants.ts src/renderer/stores/ package.json64

Development Workflow

Build Process

The application uses Vite for development and production builds as configured in package.json24-44:

Development Mode:

Production Build:

Build Pipeline:

1. vue-tsc --noEmit - TypeScript type checking
2. vite build - Compile renderer process to dist/renderer/
3. ESBuild compiles main process to dist/main/
4. electron-builder packages for target platform

Sources: package.json24-44 vite.config.ts buildAssets/builder/config.js

Security and IPC Boundary

TUUI maintains security through Electron's process isolation:

Security Boundaries:

• Renderer process cannot directly access Node.js APIs
• All privileged operations go through IPC handlers in main process
• Type definitions in src/preload/ provide compile-time safety
• Utils class abstracts IPC complexity and enforces type contracts

Sources: src/preload/ src/renderer/utils/index.ts src/main/IPCs.ts

Internationalization

TUUI supports multiple languages through Vue I18n as configured in package.json67:

Locale Files: src/renderer/locales/

• en.json - English translations
• zh.json - Chinese translations

Translation Key Domains:

• mcp.* - MCP management interface
• dxt.* - DXT bundle system
• chat.* - Chat interface
• agent.* - Agent configuration
• setting.* - Settings panels
• snackbar.* - Notification messages

Dynamic Locale Switching: The vue-i18n plugin allows runtime language changes without page reload.

Sources: src/renderer/locales/ package.json67

Next Steps

This overview provides the foundation for understanding TUUI's architecture. For deeper exploration:

• Application Structure: Package metadata, dependencies, and build system
• Architecture Details: Process separation and module organization
• Main Process: Application lifecycle and backend systems
• IPC System: Communication patterns and abstractions
• MCP Integration: MCP client implementation and server management
• Chat System: LLM orchestration and message handling
• UI Framework: Vue components and interface patterns
• Configuration: Settings management and persistence
• State Management: Pinia stores and reactive data

Sources: README.md package.json High-level system diagrams