mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 02:39:19 -05:00
generate documents using mintlify (#153)
This commit is contained in:
samanhappy
575
docs/installation.mdx
Normal file
575
docs/installation.mdx
Normal file
@@ -0,0 +1,575 @@
|
||||
---
|
||||
title: 'Installation Guide'
|
||||
description: 'Detailed installation instructions for all platforms'
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before installing MCPHub, ensure you have the following prerequisites:
|
||||
|
||||
- **Node.js** 18+ (for local development)
|
||||
- **Docker** (recommended for production)
|
||||
- **pnpm** (for local development)
|
||||
|
||||
Optional for Smart Routing:
|
||||
|
||||
- **PostgreSQL** with pgvector extension
|
||||
- **OpenAI API Key** or compatible embedding service
|
||||
|
||||
## Installation Methods
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Docker (Recommended)">
|
||||
### Docker Installation
|
||||
|
||||
Docker is the recommended way to deploy MCPHub in production.
|
||||
|
||||
#### 1. Basic Installation
|
||||
|
||||
```bash
|
||||
# Pull the latest image
|
||||
docker pull samanhappy/mcphub:latest
|
||||
|
||||
# Run with default settings
|
||||
docker run -d \
|
||||
--name mcphub \
|
||||
-p 3000:3000 \
|
||||
samanhappy/mcphub:latest
|
||||
```
|
||||
|
||||
#### 2. With Custom Configuration
|
||||
|
||||
```bash
|
||||
# Create your configuration file
|
||||
cat > mcp_settings.json << 'EOF'
|
||||
{
|
||||
"mcpServers": {
|
||||
"fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
},
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": ["@playwright/mcp@latest", "--headless"]
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
# Run with mounted config
|
||||
docker run -d \
|
||||
--name mcphub \
|
||||
-p 3000:3000 \
|
||||
-v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
|
||||
samanhappy/mcphub:latest
|
||||
```
|
||||
|
||||
#### 3. With Environment Variables
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name mcphub \
|
||||
-p 3000:3000 \
|
||||
-e PORT=3000 \
|
||||
-e BASE_PATH="" \
|
||||
-e REQUEST_TIMEOUT=60000 \
|
||||
samanhappy/mcphub:latest
|
||||
```
|
||||
|
||||
#### 4. Docker Compose
|
||||
|
||||
Create a `docker-compose.yml` file:
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
mcphub:
|
||||
image: samanhappy/mcphub:latest
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- ./mcp_settings.json:/app/mcp_settings.json
|
||||
environment:
|
||||
- PORT=3000
|
||||
- BASE_PATH=""
|
||||
- REQUEST_TIMEOUT=60000
|
||||
restart: unless-stopped
|
||||
|
||||
# Optional: PostgreSQL for Smart Routing
|
||||
postgres:
|
||||
image: pgvector/pgvector:pg16
|
||||
environment:
|
||||
POSTGRES_DB: mcphub
|
||||
POSTGRES_USER: mcphub
|
||||
POSTGRES_PASSWORD: mcphub_password
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
ports:
|
||||
- "5432:5432"
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
```
|
||||
|
||||
Run with:
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="npm Package">
|
||||
### npm Package Installation
|
||||
|
||||
Install MCPHub as a global npm package:
|
||||
|
||||
#### 1. Global Installation
|
||||
|
||||
```bash
|
||||
# Install globally
|
||||
npm install -g @samanhappy/mcphub
|
||||
|
||||
# Or with yarn
|
||||
yarn global add @samanhappy/mcphub
|
||||
|
||||
# Or with pnpm
|
||||
pnpm add -g @samanhappy/mcphub
|
||||
```
|
||||
|
||||
#### 2. Running MCPHub
|
||||
|
||||
```bash
|
||||
# Run with default settings
|
||||
mcphub
|
||||
|
||||
# Run with custom port
|
||||
PORT=8080 mcphub
|
||||
|
||||
# Run with custom config path
|
||||
MCP_SETTINGS_PATH=/path/to/mcp_settings.json mcphub
|
||||
```
|
||||
|
||||
#### 3. Local Installation
|
||||
|
||||
You can also install MCPHub locally in a project:
|
||||
|
||||
```bash
|
||||
# Create a new directory
|
||||
mkdir my-mcphub
|
||||
cd my-mcphub
|
||||
|
||||
# Initialize package.json
|
||||
npm init -y
|
||||
|
||||
# Install MCPHub locally
|
||||
npm install @samanhappy/mcphub
|
||||
|
||||
# Create a start script
|
||||
echo '#!/bin/bash\nnpx mcphub' > start.sh
|
||||
chmod +x start.sh
|
||||
|
||||
# Run MCPHub
|
||||
./start.sh
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Local Development">
|
||||
### Local Development Setup
|
||||
|
||||
For development, customization, or contribution:
|
||||
|
||||
#### 1. Clone Repository
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/samanhappy/mcphub.git
|
||||
cd mcphub
|
||||
```
|
||||
|
||||
#### 2. Install Dependencies
|
||||
|
||||
```bash
|
||||
# Install dependencies with pnpm (recommended)
|
||||
pnpm install
|
||||
|
||||
# Or with npm
|
||||
npm install
|
||||
|
||||
# Or with yarn
|
||||
yarn install
|
||||
```
|
||||
|
||||
#### 3. Development Mode
|
||||
|
||||
```bash
|
||||
# Start both backend and frontend in development mode
|
||||
pnpm dev
|
||||
|
||||
# This will start:
|
||||
# - Backend on http://localhost:3001
|
||||
# - Frontend on http://localhost:5173
|
||||
# - Frontend proxies API calls to backend
|
||||
```
|
||||
|
||||
#### 4. Build for Production
|
||||
|
||||
```bash
|
||||
# Build both backend and frontend
|
||||
pnpm build
|
||||
|
||||
# Start production server
|
||||
pnpm start
|
||||
```
|
||||
|
||||
#### 5. Development Scripts
|
||||
|
||||
```bash
|
||||
# Backend only (for API development)
|
||||
pnpm backend:dev
|
||||
|
||||
# Frontend only (when backend is running separately)
|
||||
pnpm frontend:dev
|
||||
|
||||
# Run tests
|
||||
pnpm test
|
||||
|
||||
# Lint code
|
||||
pnpm lint
|
||||
|
||||
# Format code
|
||||
pnpm format
|
||||
```
|
||||
|
||||
<Note>
|
||||
On Windows, you may need to run backend and frontend separately:
|
||||
```bash
|
||||
# Terminal 1: Backend
|
||||
pnpm backend:dev
|
||||
|
||||
# Terminal 2: Frontend
|
||||
pnpm frontend:dev
|
||||
```
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Kubernetes">
|
||||
### Kubernetes Deployment
|
||||
|
||||
Deploy MCPHub on Kubernetes with these manifests:
|
||||
|
||||
#### 1. ConfigMap for Settings
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: mcphub-config
|
||||
data:
|
||||
mcp_settings.json: |
|
||||
{
|
||||
"mcpServers": {
|
||||
"fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
},
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": ["@playwright/mcp@latest", "--headless"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Deployment
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: mcphub
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: mcphub
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: mcphub
|
||||
spec:
|
||||
containers:
|
||||
- name: mcphub
|
||||
image: samanhappy/mcphub:latest
|
||||
ports:
|
||||
- containerPort: 3000
|
||||
env:
|
||||
- name: PORT
|
||||
value: "3000"
|
||||
volumeMounts:
|
||||
- name: config
|
||||
mountPath: /app/mcp_settings.json
|
||||
subPath: mcp_settings.json
|
||||
volumes:
|
||||
- name: config
|
||||
configMap:
|
||||
name: mcphub-config
|
||||
```
|
||||
|
||||
#### 3. Service
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: mcphub-service
|
||||
spec:
|
||||
selector:
|
||||
app: mcphub
|
||||
ports:
|
||||
- port: 80
|
||||
targetPort: 3000
|
||||
type: ClusterIP
|
||||
```
|
||||
|
||||
#### 4. Ingress (Optional)
|
||||
|
||||
```yaml
|
||||
apiVersion: networking.k8s.io/v1
|
||||
kind: Ingress
|
||||
metadata:
|
||||
name: mcphub-ingress
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/proxy-buffering: "off"
|
||||
spec:
|
||||
rules:
|
||||
- host: mcphub.yourdomain.com
|
||||
http:
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
backend:
|
||||
service:
|
||||
name: mcphub-service
|
||||
port:
|
||||
number: 80
|
||||
```
|
||||
|
||||
Deploy with:
|
||||
```bash
|
||||
kubectl apply -f mcphub-configmap.yaml
|
||||
kubectl apply -f mcphub-deployment.yaml
|
||||
kubectl apply -f mcphub-service.yaml
|
||||
kubectl apply -f mcphub-ingress.yaml
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Smart Routing Setup (Optional)
|
||||
|
||||
Smart Routing provides AI-powered tool discovery using vector semantic search.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. **PostgreSQL with pgvector**
|
||||
2. **OpenAI API Key** (or compatible embedding service)
|
||||
|
||||
### Database Setup
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Docker PostgreSQL">
|
||||
```bash
|
||||
# Run PostgreSQL with pgvector
|
||||
docker run -d \
|
||||
--name mcphub-postgres \
|
||||
-e POSTGRES_DB=mcphub \
|
||||
-e POSTGRES_USER=mcphub \
|
||||
-e POSTGRES_PASSWORD=your_password \
|
||||
-p 5432:5432 \
|
||||
pgvector/pgvector:pg16
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Existing PostgreSQL">
|
||||
If you have an existing PostgreSQL instance:
|
||||
|
||||
```sql
|
||||
-- Connect to your PostgreSQL instance
|
||||
-- Create database
|
||||
CREATE DATABASE mcphub;
|
||||
|
||||
-- Connect to the mcphub database
|
||||
\c mcphub;
|
||||
|
||||
-- Enable pgvector extension
|
||||
CREATE EXTENSION IF NOT EXISTS vector;
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Cloud PostgreSQL">
|
||||
For cloud providers (AWS RDS, Google Cloud SQL, etc.):
|
||||
|
||||
1. Enable the pgvector extension in your cloud provider's console
|
||||
2. Create a database named `mcphub`
|
||||
3. Note down the connection details
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
Set the following environment variables:
|
||||
|
||||
```bash
|
||||
# Database connection
|
||||
DATABASE_URL=postgresql://mcphub:your_password@localhost:5432/mcphub
|
||||
|
||||
# OpenAI API for embeddings
|
||||
OPENAI_API_KEY=your_openai_api_key
|
||||
|
||||
# Optional: Custom embedding model
|
||||
EMBEDDING_MODEL=text-embedding-3-small
|
||||
|
||||
# Optional: Enable smart routing
|
||||
ENABLE_SMART_ROUTING=true
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
After installation, verify MCPHub is working:
|
||||
|
||||
### 1. Health Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
Expected response:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"version": "x.x.x",
|
||||
"uptime": 123
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Dashboard Access
|
||||
|
||||
Open your browser and navigate to:
|
||||
|
||||
```
|
||||
http://localhost:3000
|
||||
```
|
||||
|
||||
### 3. API Test
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/mcp \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/list",
|
||||
"params": {}
|
||||
}'
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Docker Issues">
|
||||
**Port already in use:**
|
||||
```bash
|
||||
# Check what's using port 3000
|
||||
lsof -i :3000
|
||||
|
||||
# Use a different port
|
||||
docker run -p 8080:3000 samanhappy/mcphub
|
||||
```
|
||||
|
||||
**Container won't start:**
|
||||
```bash
|
||||
# Check container logs
|
||||
docker logs mcphub
|
||||
|
||||
# Run interactively for debugging
|
||||
docker run -it --rm samanhappy/mcphub /bin/bash
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="npm Installation Issues">
|
||||
**Permission errors:**
|
||||
```bash
|
||||
# Use npx instead of global install
|
||||
npx @samanhappy/mcphub
|
||||
|
||||
# Or fix npm permissions
|
||||
npm config set prefix ~/.npm-global
|
||||
export PATH=~/.npm-global/bin:$PATH
|
||||
```
|
||||
|
||||
**Node version issues:**
|
||||
```bash
|
||||
# Check Node version
|
||||
node --version
|
||||
|
||||
# Install Node 18+ using nvm
|
||||
nvm install 18
|
||||
nvm use 18
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Network Issues">
|
||||
**Can't access dashboard:**
|
||||
- Check if MCPHub is running: `ps aux | grep mcphub`
|
||||
- Verify port binding: `netstat -tlnp | grep 3000`
|
||||
- Check firewall settings
|
||||
- Try accessing via `127.0.0.1:3000` instead of `localhost:3000`
|
||||
|
||||
**AI clients can't connect:**
|
||||
- Ensure the endpoint URL is correct
|
||||
- Check if MCPHub is behind a proxy
|
||||
- Verify network policies in Kubernetes/Docker environments
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Smart Routing Issues">
|
||||
**Database connection failed:**
|
||||
```bash
|
||||
# Test database connection
|
||||
psql $DATABASE_URL -c "SELECT 1;"
|
||||
|
||||
# Check if pgvector is installed
|
||||
psql $DATABASE_URL -c "CREATE EXTENSION IF NOT EXISTS vector;"
|
||||
```
|
||||
|
||||
**Embedding service errors:**
|
||||
- Verify OpenAI API key is valid
|
||||
- Check internet connectivity
|
||||
- Monitor rate limits
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Configuration" icon="cog" href="/configuration/mcp-settings">
|
||||
Configure your MCP servers and settings
|
||||
</Card>
|
||||
<Card title="Quick Start" icon="rocket" href="/quickstart">
|
||||
Get up and running in 5 minutes
|
||||
</Card>
|
||||
<Card title="Server Management" icon="server" href="/features/server-management">
|
||||
Learn how to manage your MCP servers
|
||||
</Card>
|
||||
<Card title="API Reference" icon="code" href="/api-reference/introduction">
|
||||
Explore the complete API documentation
|
||||
</Card>
|
||||
</CardGroup>
|
||||
Reference in New Issue
Block a user