# filiksyos/mcp-chat-ui architecture

> Architecture diagram of the GitHub repository filiksyos/mcp-chat-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/filiksyos/mcp-chat-ui
- Repository: https://github.com/filiksyos/mcp-chat-ui

## Overview

##### Project type and purpose
- This is a full-stack React/TypeScript chat UI boilerplate for Model Context Protocol (MCP) servers.
- Purpose: let developers spin up a WebSocket-based chat interface that drives AI “agents” (via OpenAI Agents SDK + OpenRouter) and MCP “tools” (e.g., chart generator, custom math tool), with hot-reload UI, Google OAuth, and interactive previews.

##### File structure
- Top-level “client/” directory holds the React UI.
- Organized by feature: components/chat, components/chart, components/preview, components/ui, lib, store (Redux slices).
- Uses Vite for bundling (vite.config.ts), TypeScript, ESLint, CSS, public assets.
- “src/server/” directory holds the Node/TypeScript WebSocket server and MCP orchestration layers:
- auth.ts, auth_google.ts – OAuth handlers
- ws_server.ts, ws_connection.ts – WebSocket handshake and per-client connections
- mcp.ts – tool and external MCP server registration
- local_html_server.ts – optional static preview server
- “src/agents/” – definitions of agent orchestration logic and system prompts
- “src/tools/” – auto-registered MCP tools (chart, math, etc.)
- Configuration and metadata: .env.template, mcp.json, package.json, tsconfig.json

##### README for technical stack and workflows
- Frontend: React + TypeScript + Vite, Redux slices for state, WebSocket client (ws_client.ts) connects to backend, charting via custom Chart components.
- Backend: Node.js + TypeScript + ws, OpenAI Agents SDK driving agents via OpenRouter API, MCP server conventions.
- Extensibility: register tools via Copilot; external MCP servers via mcp.json.
- Google OAuth integration for user sign-in.

a. Main components:
1. Frontend UI
- React App
- Redux store (chatSessionSlice, profileSlice)
- WS client library
- Components: Chat, Chart, Preview, GoogleAuth, UI library
2. Backend MCP Server
- WebSocket Server
- Connection manager
- Agent orchestrator
- MCP tool registry
- OAuth endpoints
- Local HTML preview server
3. External services
- OpenRouter LLM provider
- Google OAuth
- External MCP servers (from mcp.json)
b. Relationships & interactions:
- Browser <—WS—> MCP Server
- On chat input: UI dispatch → WS client → Server
- Server routes to Agent orchestrator → may call Tools or external MCP → returns responses
- Server sends messages back over WebSocket → UI updates store → re-renders Chat/Chart/Preview
- GoogleAuth flow: UI ↔ OAuth endpoint on Server ↔ Google
- Static HTML preview: UI fetches preview from local_html_server
c. Architectural patterns / design principles:
- Event-driven messaging (WebSocket)
- Separation of concerns: UI vs. orchestration vs. tools
- Plugin-style tool registry (auto-discover tools folder)
- Redux for predictable state management
- Agent/Tool pipelines via OpenAI Agents SDK
d. Key technologies/frameworks:
- Frontend: React, Redux, Vite, TypeScript
- Backend: Node.js, ws, OpenAI Agents SDK, TypeScript
- LLM access: OpenRouter API
- Authentication: Google OAuth
- Tooling: Copilot for codegen, mcp.json for external servers

##### Key elements to capture
- WebSocket communication as the glue
- Agent orchestrator and tool registry pattern
- Extensibility via mcp.json and tools folder
- State management boundaries
- Third-party services (LLM, OAuth)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Frontend (React App)"
        direction TB
        App["App.tsx"]:::frontend
        Main["main.tsx"]:::frontend
        subgraph "Redux Store"
            direction TB
            ChatSession["chatSessionSlice.ts"]:::store
            Profile["profileSlice.ts"]:::store
            StoreIndex["index.ts"]:::store
        end
        WSClient["ws_client.ts"]:::lib
        subgraph "UI Components"
            direction TB
            ChatUI["Chat Components"]:::component
            ChartUI["Chart Components"]:::component
            PreviewUI["HTMLPreview.tsx"]:::component
            GoogleAuthUI["GoogleAuth.tsx"]:::component
            UILib["UI Library Components"]:::component
        end
        Prompts["prompts/index.ts"]:::config
        ViteConfig["vite.config.ts"]:::config
        IndexHTML["index.html"]:::config
        PublicAssets["public/*"]:::config
    end

    subgraph "Backend (Node.js Server)"
        direction TB
        Entry["index.ts"]:::backend
        WSServer["ws_server.ts"]:::backend
        WSConnection["ws_connection.ts"]:::backend
        subgraph "Auth Handlers"
            Auth["auth.ts"]:::backend
            AuthGoogle["auth_google.ts"]:::backend
        end
        MCPRegistry["mcp.ts"]:::backend
        PreviewServer["local_html_server.ts"]:::backend
        subgraph "Agent Orchestrator"
            Agents["chart_agent.ts (+others)"]:::backend
        end
        subgraph "Instructions"
            SysPrompt["system_prompt.ts"]:::backend
            ChartPrompt["chart_agent_system_prompt.ts"]:::backend
            CodingPrompt["coding_agent_instructions.ts"]:::backend
        end
        subgraph "Tools"
            ChartTool["data_chart_generator_tool.ts"]:::tools
            MathTool["custom_math_calculations_tool.ts"]:::tools
        end
        subgraph "Utils"
            AgentsHelper["agents_helper.ts"]:::tools
            ChatSessionUtil["chat_session.ts"]:::tools
            ExternalMCP["external_mcp.ts"]:::tools
        end
        Config[".env.template, mcp.json, tsconfig.json, package.json"]:::config
    end

    subgraph External
        direction TB
        Browser["Browser"]:::external
        OpenRouter["OpenRouter LLM"]:::external
        GoogleSvc["Google OAuth Service"]:::external
        ExternalMCPServ["External MCP Servers"]:::external
    end

    Browser -->|"Uses WS Client"| WSClient
    WSClient -->|"WebSocket"| WSServer
    WSServer --> WSConnection
    WSConnection -->|"Dispatch to"| Agents
    Agents -->|"Uses prompts"| SysPrompt
    Agents -->|"Calls LLM"| OpenRouter
    Agents -->|"Invokes Tools"| ChartTool
    Agents -->|"Invokes Tools"| MathTool
    Agents -->|"External MCP"| ExternalMCPServ
    WSConnection -->|"Sends Response"| Browser
    Browser -->|"HTTP OAuth"| AuthGoogle
    AuthGoogle -->|"OAuth Flow"| GoogleSvc
    Browser -->|"Fetch Preview"| PreviewServer
    WSClient -->|"Updates"| StoreIndex
    StoreIndex --> ChatSession
    StoreIndex --> Profile
    StoreIndex --> ChatUI
    StoreIndex --> ChartUI
    StoreIndex --> PreviewUI

    classDef frontend fill:#D6E9FE,stroke:#0366D6;
    classDef backend fill:#E6F4EA,stroke:#22863A;
    classDef external fill:#F1F8FF,stroke:#A0AABF,stroke-dasharray:5 5;
    classDef store fill:#FFEEDD,stroke:#D73A49;
    classDef lib fill:#F0FFF4,stroke:#22863A;
    classDef component fill:#FFF5B1,stroke:#C18D00;
    classDef config fill:#F5F5F5,stroke:#999999;
    classDef tools fill:#FBEFFF,stroke:#6F42C1;

    click App "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/src/App.tsx"
    click Main "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/src/main.tsx"
    click ChatSession "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/src/store/slices/chatSessionSlice.ts"
    click Profile "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/src/store/slices/profileSlice.ts"
    click StoreIndex "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/src/store/index.ts"
    click WSClient "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/src/lib/ws_client.ts"
    click ChatUI "https://github.com/filiksyos/mcp-chat-ui/tree/main/client/src/components/chat/"
    click ChartUI "https://github.com/filiksyos/mcp-chat-ui/tree/main/client/src/components/chart/"
    click PreviewUI "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/src/components/preview/HTMLPreview.tsx"
    click GoogleAuthUI "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/src/components/common/GoogleAuth.tsx"
    click UILib "https://github.com/filiksyos/mcp-chat-ui/tree/main/client/src/components/ui/"
    click Prompts "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/src/prompts/index.ts"
    click ViteConfig "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/vite.config.ts"
    click IndexHTML "https://github.com/filiksyos/mcp-chat-ui/blob/main/client/index.html"
    click PublicAssets "https://github.com/filiksyos/mcp-chat-ui/tree/main/client/public/"
    click Entry "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/index.ts"
    click WSServer "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/server/ws_server.ts"
    click WSConnection "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/server/ws_connection.ts"
    click Auth "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/server/auth.ts"
    click AuthGoogle "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/server/auth_google.ts"
    click MCPRegistry "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/server/mcp.ts"
    click PreviewServer "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/server/local_html_server.ts"
    click Agents "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/agents/chart_agent.ts"
    click SysPrompt "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/instructions/system_prompt.ts"
    click ChartPrompt "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/instructions/chart_agent_system_prompt.ts"
    click CodingPrompt "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/instructions/coding_agent_instructions.ts"
    click ChartTool "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/tools/data_chart_generator_tool.ts"
    click MathTool "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/tools/custom_math_calculations_tool.ts"
    click AgentsHelper "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/utils/agents_helper.ts"
    click ChatSessionUtil "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/utils/chat_session.ts"
    click ExternalMCP "https://github.com/filiksyos/mcp-chat-ui/blob/main/src/utils/external_mcp.ts"
```
