mcphub/QWEN.md

MCPHub Project Overview

Project Summary

MCPHub is a centralized hub server for managing multiple Model Context Protocol (MCP) servers. It allows organizing these servers into flexible Streamable HTTP (SSE) endpoints, supporting access to all servers, individual servers, or logical server groups. It provides a web dashboard for monitoring and managing servers, along with features like authentication, group-based access control, and Smart Routing using vector semantic search.

Technology Stack

Backend

• Language: TypeScript (Node.js)
• Framework: Express
• Key Libraries:
  • @modelcontextprotocol/sdk: Core library for MCP interactions.
  • typeorm: ORM for database interactions.
  • pg & pgvector: PostgreSQL database and vector support.
  • jsonwebtoken & bcryptjs: Authentication (JWT) and password hashing.
  • openai: For embedding generation in Smart Routing.
  • Various utility and validation libraries (e.g., dotenv, express-validator, uuid).

Frontend

• Framework: React (via Vite)
• Language: TypeScript
• UI Library: Tailwind CSS
• Routing: react-router-dom
• Internationalization: i18next
• Component Structure: Modular components and pages within frontend/src.

Infrastructure

• Build Tool: pnpm (package manager and script runner).
• Containerization: Docker (Dockerfile provided).
• Process Management: Not explicitly defined in core files, but likely managed by Docker or host system.

Key Features

• MCP Server Management: Configure, start, stop, and monitor multiple upstream MCP servers via stdio, SSE, or Streamable HTTP protocols.
• Centralized Dashboard: Web UI for server status, group management, user administration, and logs.
• Flexible Endpoints:
  • Global MCP/SSE endpoint (/mcp, /sse) for all enabled servers.
  • Group-based endpoints (/mcp/{group}, /sse/{group}).
  • Server-specific endpoints (/mcp/{server}, /sse/{server}).
  • Smart Routing endpoint (/mcp/$smart, /sse/$smart) using vector search.
• Authentication & Authorization: JWT-based user authentication with role-based access control (admin/user).
• Group Management: Logical grouping of servers for targeted access and permission control.
• Smart Routing (Experimental): Uses pgvector and OpenAI embeddings to semantically search and find relevant tools across all connected servers.
• Configuration: Managed via mcp_settings.json.
• Logging: Server logs are captured and viewable via the dashboard.
• Marketplace Integration: Access to a marketplace of MCP servers (servers.json).

Project Structure

C:\code\mcphub\
├───src\                  # Backend source code (TypeScript)
├───frontend\             # Frontend source code (React/TypeScript)
│   ├───src\
│       ├───components\   # Reusable UI components
│       ├───pages\        # Top-level page components
│       ├───contexts\     # React contexts (Auth, Theme, Toast)
│       ├───layouts\      # Page layouts
│       ├───utils\        # Frontend utilities
│       └───...
├───dist\                 # Compiled backend output
├───frontend\dist\        # Compiled frontend output
├───tests\                # Backend tests
├───docs\                 # Documentation
├───scripts\              # Utility scripts
├───bin\                  # CLI entry points
├───assets\               # Static assets (e.g., images for README)
├───.github\              # GitHub workflows
├───.vscode\              # VS Code settings
├───mcp_settings.json     # Main configuration file for MCP servers and users
├───servers.json          # Marketplace server definitions
├───package.json          # Node.js project definition, dependencies, and scripts
├───pnpm-lock.yaml        # Dependency lock file
├───tsconfig.json         # TypeScript compiler configuration (Backend)
├───README.md             # Project documentation
├───Dockerfile            # Docker image definition
└───...

Building and Running

Prerequisites

• Node.js (>=18.0.0 or >=20.0.0)
• pnpm
• Python 3.13 (for some upstream servers and uvx)
• Docker (optional, for containerized deployment)
• PostgreSQL with pgvector (optional, for Smart Routing)

Local Development

1. Clone the repository.
2. Install dependencies: pnpm install.
3. Start development servers: pnpm dev.
   • This runs pnpm backend:dev (Node.js with tsx watch) and pnpm frontend:dev (Vite dev server) concurrently.
   • Access the dashboard at http://localhost:5173 (Vite default) or the configured port/path.

Production Build

1. Install dependencies: pnpm install.
2. Build the project: pnpm build.
   • This runs pnpm backend:build (TypeScript compilation to dist/) and pnpm frontend:build (Vite build to frontend/dist/).
3. Start the production server: pnpm start.
   • This runs node dist/index.js.

Docker Deployment

• Pull the image: docker pull samanhappy/mcphub.
• Run with default settings: docker run -p 3000:3000 samanhappy/mcphub.
• Run with custom config: docker run -p 3000:3000 -v ./mcp_settings.json:/app/mcp_settings.json -v ./data:/app/data samanhappy/mcphub.
• Access the dashboard at http://localhost:3000.

Configuration

The main configuration file is mcp_settings.json. It defines:

• mcpServers: A map of server configurations (command, args, env, URL, etc.).
• users: A list of user accounts (username, hashed password, admin status).
• groups: A map of server groups.
• systemConfig: System-wide settings (e.g., proxy, registry, installation options).

Development Conventions

• Language: TypeScript for both backend and frontend.
• Backend Style: Modular structure with clear separation of concerns (controllers, services, models, middlewares, routes, config, utils).
• Frontend Style: Component-based React architecture with contexts for state management.
• Database: TypeORM with PostgreSQL is used, leveraging decorators for entity definition.
• Testing: Uses jest for backend testing.
• Linting/Formatting: Uses eslint and prettier.
• Scripts: Defined in package.json under the scripts section for common tasks (dev, build, start, test, lint, format).