How datdao1998/mcp-chainlit works
Project type and purpose
• This is a microservice-driven application that glues together:
– A Chainlit-based UI (chat front-end)
– An MCP server (event/command orchestrator over Server-Sent Events)
– A FastAPI “mcp_api” microservice (business logic & REST endpoints)
– A PostgreSQL database (persistent storage)
– External LLM service (OpenRouter) and custom tools (e.g. cat facts)
File structure
• Top-level:
– requirements.txt, README.md, chainlit.md – global docs & deps
– mcp_api/ – FastAPI app (app.py + controller, routers, schemas)
– mcp_server/ – MCP server & Chainlit UI (server.py, ui.py), setup, tools, DB init, .chainlit config
• Patterns & config:
– mcp_api follows an MVC-style split (routers → controllers → schemas)
– mcp_server uses Server-Sent Events (SSE) transport for MCP and Chainlit’s plugin system
– Docker-Compose under mcp_server/setup for Postgres
README for technical stack & workflow
• Python 3.x, FastAPI + Uvicorn, Chainlit framework, MCP CLI
• Postgres in Docker, DB initialized via resources/database/init.py
• Workflow:
1. Start FastAPI (port 8001)
2. Run MCP server (default port 8000, SSE)
3. Launch Chainlit UI (port 8090)
4. Use UI → MCP → plugins (FastAPI, DB utils, external LLM/tools)
Main components & interactions (
a. Frontend Layer
– Chainlit UI (ui.py)
– Interacts with MCP server via SSE/websocket plugin endpoints
b. Orchestrator Layer
– MCP Server (server.py + plugin manager)
– Exposes SSE endpoint (/messages) for UI
– Dispatches plugin calls to:
• FastAPI microservice (HTTP 8001)
• Local tools (get_cat_facts.py)
• Database utils (resources/database/utils.py)
• External LLM (OpenRouter API)
c. Microservice Layer
– FastAPI “mcp_api”
• Routers → Controllers → Schemas
• Exposes REST endpoints (e.g., /user)
• May also use Postgres (if configured)
d. Data Layer
– PostgreSQL (Docker-Compose)
– Initialized by init.py
e. External Services
– OpenRouter (LLM API)
– Any third-party APIs used by tools
Architectural patterns & design principles
• Microservices (separate FastAPI API)
• Event-driven plugin orchestration (MCP + SSE)
• MVC in the FastAPI service
• Clear separation of concerns: UI vs. orchestrator vs. services vs. data