How samanhappy/mcphub works
Project Type & Purpose
• MCPHub is a full-stack web application that provides a centralized dashboard (React/Vite/Tailwind) and a REST/SSE API server (Node.js/Express/TypeScript) for managing multiple external MCP (Model Context Protocol) servers. It also supports “Smart Routing” via vector embeddings stored in PostgreSQL with pgvector, and it can run as a Docker container behind Nginx.
Main Components
a. Frontend (React App)
• Served from frontend/
• Components, pages, services call API on /api/*, /mcp/*, /sse/*
• AuthContext, ThemeContext, ToastContext manage global state
b. Backend API Server
• Entry point: src/server.ts & src/index.ts
• Routing layer: src/routes/index.ts (express.Router)
• Controllers: src/controllers/*Controller.ts
• Services: src/services/*Service.ts
• DB Layer: TypeORM entities & repositories under src/db/
• Middlewares: auth, error handling (src/middlewares/)
• SSE Service: sseService streams MCP server output to clients
• Vector Search Service: vectorSearchService + OpenAI client + pgvector
c. Database
• PostgreSQL with pgvector extension
• Entities: VectorEmbedding, User, etc.
• Repositories: custom vector repo + base repo
d. External MCP Servers
• Defined in mcp_settings.json
• Spawned/managed via child processes SDK (src/clients/openapi.ts)
• Can be accessed via HTTP/SSE by backend
e. External Embedding Service
• OpenAI or any embedding provider called from vectorSearchService
f. Deployment & Infrastructure
• Dockerfile + entrypoint.sh
• Nginx reverse proxy (example nginx.conf.example)
• CI/CD workflows: GitHub Actions, Dependabot
Relationships & Data Flows
• User → Browser (UI)
• UI → Backend API (HTTP/HTTPS)
• UI ← SSE Stream (Real-time logs & MCP responses)
• Backend → PostgreSQL (queries, vector store)
• Backend → OpenAI Embedding API (vectorization)
• Backend → External MCP Servers (child process stdio or SSE)
• Backend ← CLI (bin/cli.js) for scripting or batch tasks
• Docker Container encapsulates frontend+backend; sits behind Nginx
Architectural Patterns & Design Principles
• Layered (Controller → Service → Repository)
• Dependency Injection via imported modules
• Configuration-driven (mcp_settings.json, environment variables)
• Stream-based processing for real-time data (SSE)
• Modular React hooks & context for separation of concerns
• Use rectangles for logical components (UI, API server, services)
• UI → API (REST calls)
• API → DB (SQL/vector queries)
• API → External services (HTTP calls, child process streams)
• API → UI (SSE streams)
• UI (blue), API server (green), Database (orange), External (gray)