How filiksyos/mcp-chat-ui works
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)