How gavingz/xiaozhi-client works
Project type and purpose
• This is an open-source CLI + server tool (“xiaozhi-client”) that:
– Acts as a bridge between a user (via CLI or Web UI) and one or more MCP endpoints (JSON-RPC servers),
– Can itself be exposed as an MCP server over stdio or HTTP/SSE,
– Hosts a React-based Web UI for configuration.
• Key indicators: heavy TypeScript/Node code under src/, CLI entrypoints (cli.ts), server modules (WebServer.ts, ProxyMCPServer.ts), plus a /web folder for React.
Main components
A. CLI Layer
– cli.ts, command handlers, services (ProcessManager, DaemonManager, ServiceManager)
– Reads/writes config (ConfigAdapter) in workspace directory
– Invokes ServerFactory to start/stop background services
B. Core Server Layer
– UnifiedMCPServer / ProxyMCPServer: manages JSON-RPC connections to remote endpoints
– Transports: HTTPAdapter, WebSocketAdapter, StdioAdapter
– Adapters: MCPClientAdapter, ConfigAdapter
– Services: MCPServiceManager, MCPService, health-checks, performance monitor
C. Web UI Server
– WebServerStandalone or WebServer: serves static React assets, provides configuration REST/SSE/WS endpoints
– React front-end (under /web/src), connecting via WebSocket/SSE to server
D. External/Local MCP Endpoints
– Remote Xiaozhi AI MCP endpoints (wss://… )
– Local MCP server processes (e.g. calculator.js) spawned by ProxyMCPServer
E. Docker / Deployment & Config
– Dockerfile, docker-compose.yml, docker-start.sh for container orchestration
– Mounted config directory (~/xiaozhi-client)
Relationships and data flows
• User → CLI (stdin/args) → CLI Layer → Core Server Layer
• CLI Layer ↔ ConfigStore (reads/writes xiaozhi.config.json)
• Core Server Layer ↔ Remote MCP Servers (over WebSocket or HTTP JSON-RPC)
• Core Server Layer ↔ Local MCP Server processes (spawned child processes, stdio JSON-RPC)
• Core Server Layer ↔ Web UI Server (push config/state via SSE/WebSocket)
• Web UI (browser) ↔ WebServer (HTTP/WS/SSE) for UI actions and real-time status
• Optionally: Core Server Layer exposes itself as MCP Server to other clients via stdio or HTTP/SSE
Architectural patterns & design principles
• Modular layering: CLI, Core, Adapters/Transports, Services, UI
• Adapter pattern: abstracting JSON-RPC transport (WS, HTTP, stdio)
• Dependency injection in CLI (Container.ts)
• Process isolation: each MCP server runs as separate child process
• Config-driven: behavior controlled entirely via JSON config or UI