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
338
docs/features/authentication.mdx
Normal file
338
docs/features/authentication.mdx
Normal file
@@ -0,0 +1,338 @@
|
||||
---
|
||||
title: 'Authentication & Security'
|
||||
description: 'Configure authentication and security settings for MCPHub'
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
MCPHub provides flexible authentication mechanisms to secure your MCP server management platform. The system supports multiple authentication methods and role-based access control.
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
### Environment-based Authentication
|
||||
|
||||
Configure basic authentication using environment variables:
|
||||
|
||||
```bash
|
||||
# Basic auth credentials
|
||||
AUTH_USERNAME=admin
|
||||
AUTH_PASSWORD=your-secure-password
|
||||
|
||||
# JWT settings
|
||||
JWT_SECRET=your-jwt-secret-key
|
||||
JWT_EXPIRES_IN=24h
|
||||
```
|
||||
|
||||
### Database Authentication
|
||||
|
||||
For production deployments, enable database-backed user management:
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"provider": "database",
|
||||
"database": {
|
||||
"url": "postgresql://user:pass@localhost:5432/mcphub",
|
||||
"userTable": "users"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## User Management
|
||||
|
||||
### Creating Users
|
||||
|
||||
Create users via the admin interface or API:
|
||||
|
||||
```bash
|
||||
# Via API
|
||||
curl -X POST http://localhost:3000/api/auth/users \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $ADMIN_TOKEN" \
|
||||
-d '{
|
||||
"username": "newuser",
|
||||
"email": "user@example.com",
|
||||
"password": "securepassword",
|
||||
"role": "user"
|
||||
}'
|
||||
```
|
||||
|
||||
### User Roles
|
||||
|
||||
MCPHub supports role-based access control:
|
||||
|
||||
- **Admin**: Full system access, user management, server configuration
|
||||
- **Manager**: Server management, group management, monitoring
|
||||
- **User**: Basic server access within assigned groups
|
||||
- **Viewer**: Read-only access to assigned resources
|
||||
|
||||
## Group-based Access Control
|
||||
|
||||
### Assigning Users to Groups
|
||||
|
||||
```bash
|
||||
# Add user to group
|
||||
curl -X POST http://localhost:3000/api/groups/{groupId}/users \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-d '{"userId": "user123"}'
|
||||
```
|
||||
|
||||
### Group Permissions
|
||||
|
||||
Configure group-level permissions:
|
||||
|
||||
```json
|
||||
{
|
||||
"groupId": "dev-team",
|
||||
"permissions": {
|
||||
"servers": ["read", "write", "execute"],
|
||||
"tools": ["read", "execute"],
|
||||
"logs": ["read"],
|
||||
"config": ["read"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Authentication
|
||||
|
||||
### JWT Token Authentication
|
||||
|
||||
```javascript
|
||||
// Login to get token
|
||||
const response = await fetch('/api/auth/login', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
username: 'your-username',
|
||||
password: 'your-password',
|
||||
}),
|
||||
});
|
||||
|
||||
const { token } = await response.json();
|
||||
|
||||
// Use token for authenticated requests
|
||||
const serversResponse = await fetch('/api/servers', {
|
||||
headers: { Authorization: `Bearer ${token}` },
|
||||
});
|
||||
```
|
||||
|
||||
### API Key Authentication
|
||||
|
||||
For service-to-service communication:
|
||||
|
||||
```bash
|
||||
# Generate API key
|
||||
curl -X POST http://localhost:3000/api/auth/api-keys \
|
||||
-H "Authorization: Bearer $ADMIN_TOKEN" \
|
||||
-d '{
|
||||
"name": "my-service",
|
||||
"permissions": ["servers:read", "tools:execute"]
|
||||
}'
|
||||
|
||||
# Use API key
|
||||
curl -H "X-API-Key: your-api-key" \
|
||||
http://localhost:3000/api/servers
|
||||
```
|
||||
|
||||
## Security Configuration
|
||||
|
||||
### HTTPS Setup
|
||||
|
||||
Configure HTTPS for production:
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
mcphub:
|
||||
environment:
|
||||
- HTTPS_ENABLED=true
|
||||
- SSL_CERT_PATH=/certs/cert.pem
|
||||
- SSL_KEY_PATH=/certs/key.pem
|
||||
volumes:
|
||||
- ./certs:/certs:ro
|
||||
```
|
||||
|
||||
### CORS Configuration
|
||||
|
||||
Configure CORS for web applications:
|
||||
|
||||
```json
|
||||
{
|
||||
"cors": {
|
||||
"origin": ["https://your-frontend.com"],
|
||||
"credentials": true,
|
||||
"methods": ["GET", "POST", "PUT", "DELETE"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
Protect against abuse with rate limiting:
|
||||
|
||||
```json
|
||||
{
|
||||
"rateLimit": {
|
||||
"windowMs": 900000,
|
||||
"max": 100,
|
||||
"message": "Too many requests from this IP"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Session Management
|
||||
|
||||
### Session Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"session": {
|
||||
"secret": "your-session-secret",
|
||||
"cookie": {
|
||||
"secure": true,
|
||||
"httpOnly": true,
|
||||
"maxAge": 86400000
|
||||
},
|
||||
"store": "redis",
|
||||
"redis": {
|
||||
"host": "localhost",
|
||||
"port": 6379
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Logout and Session Cleanup
|
||||
|
||||
```javascript
|
||||
// Logout endpoint
|
||||
app.post('/api/auth/logout', (req, res) => {
|
||||
req.session.destroy();
|
||||
res.json({ message: 'Logged out successfully' });
|
||||
});
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Password Security
|
||||
|
||||
- Use strong password requirements
|
||||
- Implement password hashing with bcrypt
|
||||
- Support password reset functionality
|
||||
- Enable two-factor authentication (2FA)
|
||||
|
||||
### Token Security
|
||||
|
||||
- Use secure JWT secrets
|
||||
- Implement token rotation
|
||||
- Set appropriate expiration times
|
||||
- Store tokens securely in httpOnly cookies
|
||||
|
||||
### Network Security
|
||||
|
||||
- Use HTTPS in production
|
||||
- Implement proper CORS policies
|
||||
- Enable request validation
|
||||
- Use security headers (helmet.js)
|
||||
|
||||
### Monitoring Security Events
|
||||
|
||||
```javascript
|
||||
// Log security events
|
||||
const auditLog = {
|
||||
event: 'login_attempt',
|
||||
user: username,
|
||||
ip: req.ip,
|
||||
userAgent: req.headers['user-agent'],
|
||||
success: true,
|
||||
timestamp: new Date(),
|
||||
};
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Authentication Issues
|
||||
|
||||
**Invalid Credentials**
|
||||
|
||||
```bash
|
||||
# Check user exists and password is correct
|
||||
curl -X POST http://localhost:3000/api/auth/verify \
|
||||
-d '{"username": "user", "password": "pass"}'
|
||||
```
|
||||
|
||||
**Token Expiration**
|
||||
|
||||
```javascript
|
||||
// Handle token refresh
|
||||
if (response.status === 401) {
|
||||
const newToken = await refreshToken();
|
||||
// Retry request with new token
|
||||
}
|
||||
```
|
||||
|
||||
**Permission Denied**
|
||||
|
||||
```bash
|
||||
# Check user permissions
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:3000/api/auth/permissions
|
||||
```
|
||||
|
||||
### Debug Authentication
|
||||
|
||||
Enable authentication debugging:
|
||||
|
||||
```bash
|
||||
DEBUG=mcphub:auth npm start
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Frontend Integration
|
||||
|
||||
```javascript
|
||||
// React authentication hook
|
||||
const useAuth = () => {
|
||||
const [user, setUser] = useState(null);
|
||||
|
||||
const login = async (credentials) => {
|
||||
const response = await fetch('/api/auth/login', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(credentials),
|
||||
});
|
||||
|
||||
if (response.ok) {
|
||||
const userData = await response.json();
|
||||
setUser(userData.user);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
|
||||
return { user, login };
|
||||
};
|
||||
```
|
||||
|
||||
### Middleware Integration
|
||||
|
||||
```javascript
|
||||
// Express middleware
|
||||
const authMiddleware = (req, res, next) => {
|
||||
const token = req.headers.authorization?.split(' ')[1];
|
||||
|
||||
if (!token) {
|
||||
return res.status(401).json({ error: 'No token provided' });
|
||||
}
|
||||
|
||||
try {
|
||||
const decoded = jwt.verify(token, process.env.JWT_SECRET);
|
||||
req.user = decoded;
|
||||
next();
|
||||
} catch (error) {
|
||||
res.status(401).json({ error: 'Invalid token' });
|
||||
}
|
||||
};
|
||||
```
|
||||
588
docs/features/group-management.mdx
Normal file
588
docs/features/group-management.mdx
Normal file
@@ -0,0 +1,588 @@
|
||||
---
|
||||
title: 'Group Management'
|
||||
description: 'Organize servers into logical groups for streamlined access control'
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Group Management in MCPHub allows you to organize your MCP servers into logical collections based on functionality, use case, or access requirements. This enables fine-grained control over which tools are available to different AI clients and users.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### What are Groups?
|
||||
|
||||
Groups are named collections of MCP servers that can be accessed through dedicated endpoints. Instead of connecting to all servers at once, AI clients can connect to specific groups to access only relevant tools.
|
||||
|
||||
### Benefits of Groups
|
||||
|
||||
- **Focused Tool Access**: AI clients see only relevant tools for their use case
|
||||
- **Better Performance**: Reduced tool discovery overhead
|
||||
- **Enhanced Security**: Limit access to sensitive tools
|
||||
- **Improved Organization**: Logical separation of functionality
|
||||
- **Simplified Management**: Easier to manage related servers together
|
||||
|
||||
## Creating Groups
|
||||
|
||||
### Via Dashboard
|
||||
|
||||
1. **Navigate to Groups Section**: Click "Groups" in the main navigation
|
||||
2. **Click "Create Group"**: Start the group creation process
|
||||
3. **Fill Group Details**:
|
||||
|
||||
- **Name**: Unique identifier for the group
|
||||
- **Display Name**: Human-readable name
|
||||
- **Description**: Purpose and contents of the group
|
||||
- **Access Level**: Public, Private, or Restricted
|
||||
|
||||
4. **Add Servers**: Select servers to include in the group
|
||||
|
||||
### Via API
|
||||
|
||||
Create groups programmatically:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/groups \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"name": "web-automation",
|
||||
"displayName": "Web Automation Tools",
|
||||
"description": "Browser automation and web scraping tools",
|
||||
"servers": ["playwright", "fetch"],
|
||||
"accessLevel": "public"
|
||||
}'
|
||||
```
|
||||
|
||||
### Via Configuration File
|
||||
|
||||
Define groups in your `mcp_settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"fetch": { "command": "uvx", "args": ["mcp-server-fetch"] },
|
||||
"playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] },
|
||||
"slack": { "command": "npx", "args": ["@modelcontextprotocol/server-slack"] }
|
||||
},
|
||||
"groups": {
|
||||
"web-tools": {
|
||||
"displayName": "Web Tools",
|
||||
"description": "Web scraping and browser automation",
|
||||
"servers": ["fetch", "playwright"],
|
||||
"accessLevel": "public"
|
||||
},
|
||||
"communication": {
|
||||
"displayName": "Communication Tools",
|
||||
"description": "Messaging and collaboration tools",
|
||||
"servers": ["slack"],
|
||||
"accessLevel": "private"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Group Types and Use Cases
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Web Automation Group">
|
||||
**Purpose**: Browser automation and web scraping
|
||||
|
||||
**Servers**:
|
||||
- `playwright`: Browser automation
|
||||
- `fetch`: HTTP requests and web scraping
|
||||
- `selenium`: Alternative browser automation
|
||||
|
||||
**Use Cases**:
|
||||
- Automated testing
|
||||
- Data collection
|
||||
- Web monitoring
|
||||
- Content analysis
|
||||
|
||||
**Endpoint**: `http://localhost:3000/mcp/web-automation`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Data Processing Group">
|
||||
**Purpose**: Data manipulation and analysis
|
||||
|
||||
**Servers**:
|
||||
- `sqlite`: Database operations
|
||||
- `filesystem`: File operations
|
||||
- `spreadsheet`: Excel/CSV processing
|
||||
|
||||
**Use Cases**:
|
||||
- Data analysis
|
||||
- Report generation
|
||||
- File processing
|
||||
- Database queries
|
||||
|
||||
**Endpoint**: `http://localhost:3000/mcp/data-processing`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Communication Group">
|
||||
**Purpose**: Messaging and collaboration
|
||||
|
||||
**Servers**:
|
||||
- `slack`: Slack integration
|
||||
- `discord`: Discord bot
|
||||
- `email`: Email sending
|
||||
- `sms`: SMS notifications
|
||||
|
||||
**Use Cases**:
|
||||
- Team notifications
|
||||
- Customer communication
|
||||
- Alert systems
|
||||
- Social media management
|
||||
|
||||
**Endpoint**: `http://localhost:3000/mcp/communication`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Development Group">
|
||||
**Purpose**: Software development tools
|
||||
|
||||
**Servers**:
|
||||
- `github`: GitHub operations
|
||||
- `gitlab`: GitLab integration
|
||||
- `docker`: Container management
|
||||
- `kubernetes`: K8s operations
|
||||
|
||||
**Use Cases**:
|
||||
- Code deployment
|
||||
- Repository management
|
||||
- CI/CD operations
|
||||
- Infrastructure management
|
||||
|
||||
**Endpoint**: `http://localhost:3000/mcp/development`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="AI/ML Group">
|
||||
**Purpose**: Machine learning and AI tools
|
||||
|
||||
**Servers**:
|
||||
- `openai`: OpenAI API integration
|
||||
- `huggingface`: Hugging Face models
|
||||
- `vector-db`: Vector database operations
|
||||
|
||||
**Use Cases**:
|
||||
- Model inference
|
||||
- Data embeddings
|
||||
- Natural language processing
|
||||
- Computer vision
|
||||
|
||||
**Endpoint**: `http://localhost:3000/mcp/ai-ml`
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Group Access Control
|
||||
|
||||
### Access Levels
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Public">
|
||||
**Public Groups**:
|
||||
- Accessible to all authenticated users
|
||||
- No additional permissions required
|
||||
- Visible in group listings
|
||||
- Default access level
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "public-tools",
|
||||
"accessLevel": "public",
|
||||
"servers": ["fetch", "calculator"]
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Private">
|
||||
**Private Groups**:
|
||||
- Only visible to group members
|
||||
- Requires explicit user assignment
|
||||
- Hidden from public listings
|
||||
- Admin-controlled membership
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "internal-tools",
|
||||
"accessLevel": "private",
|
||||
"members": ["user1", "user2"],
|
||||
"servers": ["internal-api", "database"]
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Restricted">
|
||||
**Restricted Groups**:
|
||||
- Role-based access control
|
||||
- Requires specific permissions
|
||||
- Audit logging enabled
|
||||
- Time-limited access
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "admin-tools",
|
||||
"accessLevel": "restricted",
|
||||
"requiredRoles": ["admin", "operator"],
|
||||
"servers": ["system-control", "user-management"]
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### User Management
|
||||
|
||||
Assign users to groups:
|
||||
|
||||
```bash
|
||||
# Add user to group
|
||||
curl -X POST http://localhost:3000/api/groups/web-tools/members \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{"userId": "user123"}'
|
||||
|
||||
# Remove user from group
|
||||
curl -X DELETE http://localhost:3000/api/groups/web-tools/members/user123 \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
|
||||
# List group members
|
||||
curl http://localhost:3000/api/groups/web-tools/members \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
## Group Endpoints
|
||||
|
||||
### Accessing Groups
|
||||
|
||||
Each group gets its own MCP endpoint:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="HTTP MCP">
|
||||
```
|
||||
http://localhost:3000/mcp/{group-name}
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `http://localhost:3000/mcp/web-tools`
|
||||
- `http://localhost:3000/mcp/data-processing`
|
||||
- `http://localhost:3000/mcp/communication`
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="SSE (Legacy)">
|
||||
```
|
||||
http://localhost:3000/sse/{group-name}
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `http://localhost:3000/sse/web-tools`
|
||||
- `http://localhost:3000/sse/data-processing`
|
||||
- `http://localhost:3000/sse/communication`
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Group Tool Discovery
|
||||
|
||||
When connecting to a group endpoint, AI clients will only see tools from servers within that group:
|
||||
|
||||
```bash
|
||||
# List tools in web-tools group
|
||||
curl -X POST http://localhost:3000/mcp/web-tools \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/list",
|
||||
"params": {}
|
||||
}'
|
||||
```
|
||||
|
||||
Response will only include tools from `fetch` and `playwright` servers.
|
||||
|
||||
## Dynamic Group Management
|
||||
|
||||
### Adding Servers to Groups
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Dashboard">
|
||||
1. Navigate to the group in the dashboard
|
||||
2. Click "Manage Servers"
|
||||
3. Select additional servers to add
|
||||
4. Click "Save Changes"
|
||||
</Tab>
|
||||
|
||||
<Tab title="API">
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/groups/web-tools/servers \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{"serverId": "new-server"}'
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Removing Servers from Groups
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Dashboard">
|
||||
1. Navigate to the group in the dashboard
|
||||
2. Click "Manage Servers"
|
||||
3. Unselect servers to remove
|
||||
4. Click "Save Changes"
|
||||
</Tab>
|
||||
|
||||
<Tab title="API">
|
||||
```bash
|
||||
curl -X DELETE http://localhost:3000/api/groups/web-tools/servers/server-name \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Batch Server Updates
|
||||
|
||||
Update multiple servers at once:
|
||||
|
||||
```bash
|
||||
curl -X PUT http://localhost:3000/api/groups/web-tools/servers \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"servers": ["fetch", "playwright", "selenium"]
|
||||
}'
|
||||
```
|
||||
|
||||
## Group Monitoring
|
||||
|
||||
### Group Status
|
||||
|
||||
Monitor group health and activity:
|
||||
|
||||
```bash
|
||||
# Get group status
|
||||
curl http://localhost:3000/api/groups/web-tools/status \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
Response includes:
|
||||
|
||||
- Number of active servers
|
||||
- Tool count
|
||||
- Active connections
|
||||
- Recent activity
|
||||
|
||||
### Group Analytics
|
||||
|
||||
Track group usage:
|
||||
|
||||
```bash
|
||||
# Get group analytics
|
||||
curl http://localhost:3000/api/groups/web-tools/analytics \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
Metrics include:
|
||||
|
||||
- Request count by tool
|
||||
- Response times
|
||||
- Error rates
|
||||
- User activity
|
||||
|
||||
## Advanced Group Features
|
||||
|
||||
### Nested Groups
|
||||
|
||||
Create hierarchical group structures:
|
||||
|
||||
```json
|
||||
{
|
||||
"groups": {
|
||||
"development": {
|
||||
"displayName": "Development Tools",
|
||||
"subGroups": ["frontend-dev", "backend-dev", "devops"]
|
||||
},
|
||||
"frontend-dev": {
|
||||
"displayName": "Frontend Development",
|
||||
"servers": ["playwright", "webpack-server"],
|
||||
"parent": "development"
|
||||
},
|
||||
"backend-dev": {
|
||||
"displayName": "Backend Development",
|
||||
"servers": ["database", "api-server"],
|
||||
"parent": "development"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Group Templates
|
||||
|
||||
Use templates for quick group creation:
|
||||
|
||||
```json
|
||||
{
|
||||
"groupTemplates": {
|
||||
"web-project": {
|
||||
"description": "Standard web project toolset",
|
||||
"servers": ["fetch", "playwright", "filesystem"],
|
||||
"accessLevel": "public"
|
||||
},
|
||||
"data-science": {
|
||||
"description": "Data science and ML tools",
|
||||
"servers": ["python-tools", "jupyter", "vector-db"],
|
||||
"accessLevel": "private"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Apply template:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/groups/from-template \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"name": "my-web-project",
|
||||
"template": "web-project",
|
||||
"displayName": "My Web Project Tools"
|
||||
}'
|
||||
```
|
||||
|
||||
### Group Policies
|
||||
|
||||
Define policies for group behavior:
|
||||
|
||||
```json
|
||||
{
|
||||
"groupPolicies": {
|
||||
"web-tools": {
|
||||
"maxConcurrentConnections": 10,
|
||||
"requestTimeout": 30000,
|
||||
"rateLimiting": {
|
||||
"requestsPerMinute": 100,
|
||||
"burstLimit": 20
|
||||
},
|
||||
"allowedOrigins": ["localhost", "myapp.com"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Group Organization
|
||||
|
||||
<Tip>
|
||||
**Organize by Use Case**: Group servers based on what users want to accomplish, not just technical
|
||||
similarity.
|
||||
</Tip>
|
||||
|
||||
<Tip>
|
||||
**Keep Groups Focused**: Avoid creating groups with too many diverse tools. Smaller, focused
|
||||
groups are more useful.
|
||||
</Tip>
|
||||
|
||||
<Tip>
|
||||
**Use Descriptive Names**: Choose names that clearly indicate the group's purpose and contents.
|
||||
</Tip>
|
||||
|
||||
### Security Considerations
|
||||
|
||||
<Warning>
|
||||
**Principle of Least Privilege**: Only give users access to groups they actually need.
|
||||
</Warning>
|
||||
|
||||
<Warning>
|
||||
**Sensitive Tool Isolation**: Keep sensitive tools in restricted groups with proper access
|
||||
controls.
|
||||
</Warning>
|
||||
|
||||
<Warning>
|
||||
**Regular Access Reviews**: Periodically review group memberships and remove unnecessary access.
|
||||
</Warning>
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
<Info>
|
||||
**Balance Group Size**: Very large groups may have slower tool discovery. Consider splitting into
|
||||
smaller groups.
|
||||
</Info>
|
||||
|
||||
<Info>
|
||||
**Monitor Usage**: Use analytics to identify which groups are heavily used and optimize
|
||||
accordingly.
|
||||
</Info>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Group Not Accessible">
|
||||
**Check:**
|
||||
- User has proper permissions
|
||||
- Group exists and is active
|
||||
- Servers in group are running
|
||||
- Network connectivity
|
||||
|
||||
**Solutions:**
|
||||
1. Verify user group membership
|
||||
2. Check group configuration
|
||||
3. Test individual server connections
|
||||
4. Review access logs
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tools Missing from Group">
|
||||
**Possible causes:**
|
||||
- Server not properly added to group
|
||||
- Server is not running
|
||||
- Tool discovery failed
|
||||
- Caching issues
|
||||
|
||||
**Debug steps:**
|
||||
1. Verify server is in group configuration
|
||||
2. Check server status
|
||||
3. Force refresh tool discovery
|
||||
4. Clear group cache
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Group Performance Issues">
|
||||
**Common issues:**
|
||||
- Too many servers in group
|
||||
- Slow server responses
|
||||
- Network latency
|
||||
- Resource constraints
|
||||
|
||||
**Optimizations:**
|
||||
1. Split large groups
|
||||
2. Monitor server performance
|
||||
3. Implement request caching
|
||||
4. Use connection pooling
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Smart Routing" icon="route" href="/features/smart-routing">
|
||||
AI-powered tool discovery across groups
|
||||
</Card>
|
||||
<Card title="Authentication" icon="shield" href="/features/authentication">
|
||||
User management and access control
|
||||
</Card>
|
||||
<Card title="API Reference" icon="code" href="/api-reference/groups">
|
||||
Complete group management API
|
||||
</Card>
|
||||
<Card title="Configuration" icon="cog" href="/configuration/mcp-settings">
|
||||
Advanced group configuration options
|
||||
</Card>
|
||||
</CardGroup>
|
||||
526
docs/features/monitoring.mdx
Normal file
526
docs/features/monitoring.mdx
Normal file
@@ -0,0 +1,526 @@
|
||||
---
|
||||
title: 'Monitoring & Logging'
|
||||
description: 'Monitor your MCP servers and analyze system logs with MCPHub'
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
MCPHub provides comprehensive monitoring and logging capabilities to help you track server performance, debug issues, and maintain system health.
|
||||
|
||||
## Real-time Monitoring
|
||||
|
||||
### Server Status Dashboard
|
||||
|
||||
The MCPHub dashboard provides real-time monitoring of all registered MCP servers:
|
||||
|
||||
- **Server Health**: Online/offline status with automatic health checks
|
||||
- **Response Times**: Average, min, max response times per server
|
||||
- **Request Volume**: Requests per second/minute/hour
|
||||
- **Error Rates**: Success/failure ratios and error trends
|
||||
- **Resource Usage**: Memory and CPU utilization (when available)
|
||||
|
||||
### Health Check Configuration
|
||||
|
||||
Configure health checks for your MCP servers:
|
||||
|
||||
```json
|
||||
{
|
||||
"healthCheck": {
|
||||
"enabled": true,
|
||||
"interval": 30000,
|
||||
"timeout": 5000,
|
||||
"retries": 3,
|
||||
"endpoints": {
|
||||
"ping": "/health",
|
||||
"tools": "/tools/list"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Monitoring API
|
||||
|
||||
Get monitoring data programmatically:
|
||||
|
||||
```bash
|
||||
# Get server health status
|
||||
curl http://localhost:3000/api/monitoring/health
|
||||
|
||||
# Get performance metrics
|
||||
curl http://localhost:3000/api/monitoring/metrics?server=my-server&range=1h
|
||||
|
||||
# Get system overview
|
||||
curl http://localhost:3000/api/monitoring/overview
|
||||
```
|
||||
|
||||
## Logging System
|
||||
|
||||
### Log Levels
|
||||
|
||||
MCPHub supports standard log levels:
|
||||
|
||||
- **ERROR**: Critical errors requiring immediate attention
|
||||
- **WARN**: Warning conditions that should be monitored
|
||||
- **INFO**: General operational messages
|
||||
- **DEBUG**: Detailed debugging information
|
||||
- **TRACE**: Very detailed trace information
|
||||
|
||||
### Log Configuration
|
||||
|
||||
Configure logging in your environment:
|
||||
|
||||
```bash
|
||||
# Set log level
|
||||
LOG_LEVEL=info
|
||||
|
||||
# Enable structured logging
|
||||
LOG_FORMAT=json
|
||||
|
||||
# Log file location
|
||||
LOG_FILE=/var/log/mcphub/app.log
|
||||
|
||||
# Enable request logging
|
||||
ENABLE_REQUEST_LOGS=true
|
||||
```
|
||||
|
||||
### Structured Logging
|
||||
|
||||
MCPHub uses structured logging for better analysis:
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2024-01-20T10:30:00Z",
|
||||
"level": "info",
|
||||
"message": "MCP server request completed",
|
||||
"server": "github-mcp",
|
||||
"tool": "search_repositories",
|
||||
"duration": 245,
|
||||
"status": "success",
|
||||
"requestId": "req_123456",
|
||||
"userId": "user_789"
|
||||
}
|
||||
```
|
||||
|
||||
## Log Management
|
||||
|
||||
### Log Storage Options
|
||||
|
||||
#### File-based Logging
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
mcphub:
|
||||
volumes:
|
||||
- ./logs:/app/logs
|
||||
environment:
|
||||
- LOG_FILE=/app/logs/mcphub.log
|
||||
- LOG_ROTATION=daily
|
||||
- LOG_MAX_SIZE=100MB
|
||||
- LOG_MAX_FILES=7
|
||||
```
|
||||
|
||||
#### Database Logging
|
||||
|
||||
```json
|
||||
{
|
||||
"logging": {
|
||||
"database": {
|
||||
"enabled": true,
|
||||
"table": "logs",
|
||||
"retention": "30d",
|
||||
"indexes": ["timestamp", "level", "server"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### External Log Services
|
||||
|
||||
```bash
|
||||
# Syslog integration
|
||||
SYSLOG_ENABLED=true
|
||||
SYSLOG_HOST=localhost
|
||||
SYSLOG_PORT=514
|
||||
SYSLOG_FACILITY=local0
|
||||
|
||||
# ELK Stack integration
|
||||
ELASTICSEARCH_URL=http://localhost:9200
|
||||
ELASTICSEARCH_INDEX=mcphub-logs
|
||||
```
|
||||
|
||||
### Log Rotation
|
||||
|
||||
Automatic log rotation configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"logRotation": {
|
||||
"enabled": true,
|
||||
"maxSize": "100MB",
|
||||
"maxFiles": 10,
|
||||
"compress": true,
|
||||
"interval": "daily"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Metrics Collection
|
||||
|
||||
### System Metrics
|
||||
|
||||
MCPHub collects various system metrics:
|
||||
|
||||
```javascript
|
||||
// Example metrics collected
|
||||
{
|
||||
"timestamp": "2024-01-20T10:30:00Z",
|
||||
"metrics": {
|
||||
"requests": {
|
||||
"total": 1547,
|
||||
"success": 1523,
|
||||
"errors": 24,
|
||||
"rate": 12.5
|
||||
},
|
||||
"servers": {
|
||||
"online": 8,
|
||||
"offline": 2,
|
||||
"total": 10
|
||||
},
|
||||
"performance": {
|
||||
"avgResponseTime": 156,
|
||||
"p95ResponseTime": 324,
|
||||
"p99ResponseTime": 567
|
||||
},
|
||||
"system": {
|
||||
"memoryUsage": "245MB",
|
||||
"cpuUsage": "15%",
|
||||
"uptime": "72h 35m"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Metrics
|
||||
|
||||
Add custom metrics for your use case:
|
||||
|
||||
```javascript
|
||||
// Custom metric example
|
||||
const customMetric = {
|
||||
name: 'tool_usage',
|
||||
type: 'counter',
|
||||
tags: {
|
||||
server: 'github-mcp',
|
||||
tool: 'search_repositories',
|
||||
result: 'success',
|
||||
},
|
||||
value: 1,
|
||||
};
|
||||
|
||||
// Send to metrics endpoint
|
||||
await fetch('/api/monitoring/metrics', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(customMetric),
|
||||
});
|
||||
```
|
||||
|
||||
## Alerting
|
||||
|
||||
### Alert Configuration
|
||||
|
||||
Set up alerts for critical conditions:
|
||||
|
||||
```json
|
||||
{
|
||||
"alerts": {
|
||||
"serverDown": {
|
||||
"condition": "server.status == 'offline'",
|
||||
"duration": "5m",
|
||||
"severity": "critical",
|
||||
"channels": ["email", "slack"]
|
||||
},
|
||||
"highErrorRate": {
|
||||
"condition": "errors.rate > 0.1",
|
||||
"duration": "2m",
|
||||
"severity": "warning",
|
||||
"channels": ["slack"]
|
||||
},
|
||||
"slowResponse": {
|
||||
"condition": "response.p95 > 1000",
|
||||
"duration": "5m",
|
||||
"severity": "warning",
|
||||
"channels": ["email"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Notification Channels
|
||||
|
||||
#### Email Notifications
|
||||
|
||||
```bash
|
||||
# Email configuration
|
||||
SMTP_HOST=smtp.gmail.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USER=alerts@yourcompany.com
|
||||
SMTP_PASS=your-app-password
|
||||
ALERT_EMAIL_TO=admin@yourcompany.com
|
||||
```
|
||||
|
||||
#### Slack Integration
|
||||
|
||||
```bash
|
||||
# Slack webhook
|
||||
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
|
||||
SLACK_CHANNEL=#mcphub-alerts
|
||||
```
|
||||
|
||||
#### Webhook Notifications
|
||||
|
||||
```json
|
||||
{
|
||||
"webhooks": [
|
||||
{
|
||||
"url": "https://your-service.com/webhooks/mcphub",
|
||||
"events": ["server.down", "error.rate.high"],
|
||||
"headers": {
|
||||
"Authorization": "Bearer your-token"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Log Analysis
|
||||
|
||||
### Query Logs
|
||||
|
||||
Use the logs API to query and analyze logs:
|
||||
|
||||
```bash
|
||||
# Get recent errors
|
||||
curl "http://localhost:3000/api/logs?level=error&since=1h"
|
||||
|
||||
# Search logs by server
|
||||
curl "http://localhost:3000/api/logs?server=github-mcp&limit=100"
|
||||
|
||||
# Get logs for specific request
|
||||
curl "http://localhost:3000/api/logs?requestId=req_123456"
|
||||
|
||||
# Filter by time range
|
||||
curl "http://localhost:3000/api/logs?from=2024-01-20T00:00:00Z&to=2024-01-20T23:59:59Z"
|
||||
```
|
||||
|
||||
### Log Aggregation
|
||||
|
||||
Aggregate logs for insights:
|
||||
|
||||
```bash
|
||||
# Error summary by server
|
||||
curl "http://localhost:3000/api/logs/aggregate?groupBy=server&level=error&since=24h"
|
||||
|
||||
# Request volume over time
|
||||
curl "http://localhost:3000/api/logs/aggregate?groupBy=hour&type=request&since=7d"
|
||||
```
|
||||
|
||||
## Performance Monitoring
|
||||
|
||||
### Response Time Tracking
|
||||
|
||||
Monitor MCP server response times:
|
||||
|
||||
```javascript
|
||||
// Response time metrics
|
||||
{
|
||||
"server": "github-mcp",
|
||||
"tool": "search_repositories",
|
||||
"metrics": {
|
||||
"calls": 156,
|
||||
"avgTime": 234,
|
||||
"minTime": 89,
|
||||
"maxTime": 1205,
|
||||
"p50": 201,
|
||||
"p95": 567,
|
||||
"p99": 892
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Rate Monitoring
|
||||
|
||||
Track error rates and patterns:
|
||||
|
||||
```bash
|
||||
# Get error rates by server
|
||||
curl "http://localhost:3000/api/monitoring/errors?groupBy=server&since=1h"
|
||||
|
||||
# Get error details
|
||||
curl "http://localhost:3000/api/monitoring/errors?server=github-mcp&details=true"
|
||||
```
|
||||
|
||||
## Integration with External Tools
|
||||
|
||||
### Prometheus Integration
|
||||
|
||||
Export metrics to Prometheus:
|
||||
|
||||
```yaml
|
||||
# prometheus.yml
|
||||
scrape_configs:
|
||||
- job_name: 'mcphub'
|
||||
static_configs:
|
||||
- targets: ['localhost:3000']
|
||||
metrics_path: '/api/monitoring/prometheus'
|
||||
scrape_interval: 30s
|
||||
```
|
||||
|
||||
### Grafana Dashboards
|
||||
|
||||
Import MCPHub Grafana dashboard:
|
||||
|
||||
```json
|
||||
{
|
||||
"dashboard": {
|
||||
"title": "MCPHub Monitoring",
|
||||
"panels": [
|
||||
{
|
||||
"title": "Server Status",
|
||||
"type": "stat",
|
||||
"targets": [
|
||||
{
|
||||
"expr": "mcphub_servers_online",
|
||||
"legendFormat": "Online"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Request Rate",
|
||||
"type": "graph",
|
||||
"targets": [
|
||||
{
|
||||
"expr": "rate(mcphub_requests_total[5m])",
|
||||
"legendFormat": "Requests/sec"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ELK Stack Integration
|
||||
|
||||
Configure Logstash for log processing:
|
||||
|
||||
```ruby
|
||||
# logstash.conf
|
||||
input {
|
||||
beats {
|
||||
port => 5044
|
||||
}
|
||||
}
|
||||
|
||||
filter {
|
||||
if [fields][service] == "mcphub" {
|
||||
json {
|
||||
source => "message"
|
||||
}
|
||||
|
||||
date {
|
||||
match => [ "timestamp", "ISO8601" ]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
output {
|
||||
elasticsearch {
|
||||
hosts => ["localhost:9200"]
|
||||
index => "mcphub-logs-%{+YYYY.MM.dd}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Monitoring Issues
|
||||
|
||||
**Missing Metrics**
|
||||
|
||||
```bash
|
||||
# Check metrics endpoint
|
||||
curl http://localhost:3000/api/monitoring/health
|
||||
|
||||
# Verify configuration
|
||||
grep -r "monitoring" /path/to/config/
|
||||
```
|
||||
|
||||
**Log File Issues**
|
||||
|
||||
```bash
|
||||
# Check log file permissions
|
||||
ls -la /var/log/mcphub/
|
||||
|
||||
# Verify disk space
|
||||
df -h /var/log/
|
||||
|
||||
# Check log rotation
|
||||
logrotate -d /etc/logrotate.d/mcphub
|
||||
```
|
||||
|
||||
**Performance Issues**
|
||||
|
||||
```bash
|
||||
# Monitor system resources
|
||||
top -p $(pgrep -f mcphub)
|
||||
|
||||
# Check database connections
|
||||
curl http://localhost:3000/api/monitoring/database
|
||||
|
||||
# Analyze slow queries
|
||||
curl http://localhost:3000/api/monitoring/slow-queries
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging for troubleshooting:
|
||||
|
||||
```bash
|
||||
# Enable debug mode
|
||||
DEBUG=mcphub:* npm start
|
||||
|
||||
# Or set environment variable
|
||||
export DEBUG=mcphub:monitoring,mcphub:logging
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Log Management
|
||||
|
||||
- Use structured logging with consistent formats
|
||||
- Implement proper log levels and filtering
|
||||
- Set up log rotation and retention policies
|
||||
- Monitor log file sizes and disk usage
|
||||
|
||||
### Monitoring Setup
|
||||
|
||||
- Configure appropriate health check intervals
|
||||
- Set up alerts for critical conditions
|
||||
- Monitor both system and application metrics
|
||||
- Use dashboards for visual monitoring
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
- Index log database tables appropriately
|
||||
- Use log sampling for high-volume scenarios
|
||||
- Implement proper caching for metrics
|
||||
- Regular cleanup of old logs and metrics
|
||||
|
||||
### Security Considerations
|
||||
|
||||
- Sanitize sensitive data in logs
|
||||
- Secure access to monitoring endpoints
|
||||
- Use authentication for external integrations
|
||||
- Encrypt log transmission when using external services
|
||||
509
docs/features/server-management.mdx
Normal file
509
docs/features/server-management.mdx
Normal file
@@ -0,0 +1,509 @@
|
||||
---
|
||||
title: 'Server Management'
|
||||
description: 'Centrally manage multiple MCP servers with hot-swappable configuration'
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
MCPHub's server management system allows you to centrally configure, monitor, and control multiple MCP (Model Context Protocol) servers from a single dashboard. All changes are applied in real-time without requiring server restarts.
|
||||
|
||||
## Adding MCP Servers
|
||||
|
||||
### Via Dashboard
|
||||
|
||||
1. **Access the Dashboard**: Navigate to `http://localhost:3000` and log in
|
||||
2. **Click "Add Server"**: Located in the servers section
|
||||
3. **Fill Server Details**:
|
||||
- **Name**: Unique identifier for the server
|
||||
- **Command**: Executable command (e.g., `npx`, `uvx`, `python`)
|
||||
- **Arguments**: Array of command arguments
|
||||
- **Environment Variables**: Key-value pairs for environment setup
|
||||
- **Working Directory**: Optional working directory for the command
|
||||
|
||||
### Via Configuration File
|
||||
|
||||
Edit your `mcp_settings.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name": {
|
||||
"command": "command-to-run",
|
||||
"args": ["arg1", "arg2"],
|
||||
"env": {
|
||||
"API_KEY": "your-api-key",
|
||||
"CONFIG_VALUE": "some-value"
|
||||
},
|
||||
"cwd": "/optional/working/directory"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Via API
|
||||
|
||||
Use the REST API to add servers programmatically:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/servers \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"name": "fetch-server",
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"],
|
||||
"env": {}
|
||||
}'
|
||||
```
|
||||
|
||||
## Popular MCP Server Examples
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Web Fetch Server">
|
||||
Provides web scraping and HTTP request capabilities:
|
||||
|
||||
```json
|
||||
{
|
||||
"fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Tools:**
|
||||
- `fetch`: Make HTTP requests
|
||||
- `fetch_html`: Scrape web pages
|
||||
- `fetch_json`: Get JSON data from APIs
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Playwright Browser Automation">
|
||||
Browser automation for web interactions:
|
||||
|
||||
```json
|
||||
{
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": ["@playwright/mcp@latest", "--headless"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Tools:**
|
||||
- `playwright_navigate`: Navigate to web pages
|
||||
- `playwright_screenshot`: Take screenshots
|
||||
- `playwright_click`: Click elements
|
||||
- `playwright_fill`: Fill forms
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="File System Operations">
|
||||
File and directory management:
|
||||
|
||||
```json
|
||||
{
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Tools:**
|
||||
- `read_file`: Read file contents
|
||||
- `write_file`: Write to files
|
||||
- `create_directory`: Create directories
|
||||
- `list_directory`: List directory contents
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="SQLite Database">
|
||||
Database operations:
|
||||
|
||||
```json
|
||||
{
|
||||
"sqlite": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Tools:**
|
||||
- `execute_query`: Execute SQL queries
|
||||
- `describe_tables`: Get table schemas
|
||||
- `create_table`: Create new tables
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Slack Integration">
|
||||
Slack workspace integration:
|
||||
|
||||
```json
|
||||
{
|
||||
"slack": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-slack"],
|
||||
"env": {
|
||||
"SLACK_BOT_TOKEN": "xoxb-your-bot-token",
|
||||
"SLACK_TEAM_ID": "T1234567890"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Tools:**
|
||||
- `send_slack_message`: Send messages to channels
|
||||
- `list_slack_channels`: List available channels
|
||||
- `get_slack_thread`: Get thread messages
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="GitHub Integration">
|
||||
GitHub repository operations:
|
||||
|
||||
```json
|
||||
{
|
||||
"github": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-github"],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Tools:**
|
||||
- `create_or_update_file`: Create/update repository files
|
||||
- `search_repositories`: Search GitHub repositories
|
||||
- `create_issue`: Create issues
|
||||
- `create_pull_request`: Create pull requests
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Google Drive">
|
||||
Google Drive file operations:
|
||||
|
||||
```json
|
||||
{
|
||||
"gdrive": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-gdrive"],
|
||||
"env": {
|
||||
"GDRIVE_CLIENT_ID": "your-client-id",
|
||||
"GDRIVE_CLIENT_SECRET": "your-client-secret",
|
||||
"GDRIVE_REDIRECT_URI": "your-redirect-uri"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Tools:**
|
||||
- `gdrive_search`: Search files and folders
|
||||
- `gdrive_read`: Read file contents
|
||||
- `gdrive_create`: Create new files
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Amap Maps (China)">
|
||||
Chinese mapping and location services:
|
||||
|
||||
```json
|
||||
{
|
||||
"amap": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@amap/amap-maps-mcp-server"],
|
||||
"env": {
|
||||
"AMAP_MAPS_API_KEY": "your-api-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available Tools:**
|
||||
- `search_location`: Search for locations
|
||||
- `get_directions`: Get route directions
|
||||
- `reverse_geocode`: Convert coordinates to addresses
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Server Lifecycle Management
|
||||
|
||||
### Starting Servers
|
||||
|
||||
Servers are automatically started when:
|
||||
|
||||
- MCPHub boots up
|
||||
- A server is added via the dashboard or API
|
||||
- A server configuration is updated
|
||||
- A stopped server is manually restarted
|
||||
|
||||
### Stopping Servers
|
||||
|
||||
You can stop servers:
|
||||
|
||||
- **Via Dashboard**: Toggle the server status switch
|
||||
- **Via API**: Send a POST request to `/api/servers/{name}/toggle`
|
||||
- **Automatically**: Servers stop if they crash or encounter errors
|
||||
|
||||
### Restarting Servers
|
||||
|
||||
Servers are automatically restarted:
|
||||
|
||||
- When configuration changes are made
|
||||
- After environment variable updates
|
||||
- When manually triggered via dashboard or API
|
||||
|
||||
## Server Status Monitoring
|
||||
|
||||
### Status Indicators
|
||||
|
||||
Each server displays a status indicator:
|
||||
|
||||
- 🟢 **Running**: Server is active and responding
|
||||
- 🟡 **Starting**: Server is initializing
|
||||
- 🔴 **Stopped**: Server is not running
|
||||
- ⚠️ **Error**: Server encountered an error
|
||||
|
||||
### Real-time Logs
|
||||
|
||||
View server logs in real-time:
|
||||
|
||||
1. **Dashboard Logs**: Click on a server to view its logs
|
||||
2. **API Logs**: Access logs via `/api/logs` endpoint
|
||||
3. **Streaming Logs**: Subscribe to log streams via WebSocket
|
||||
|
||||
### Health Checks
|
||||
|
||||
MCPHub automatically performs health checks:
|
||||
|
||||
- **Initialization Check**: Verifies server starts successfully
|
||||
- **Tool Discovery**: Confirms available tools are detected
|
||||
- **Response Check**: Tests server responsiveness
|
||||
- **Resource Monitoring**: Tracks CPU and memory usage
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Servers can use environment variables for configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"server-name": {
|
||||
"command": "python",
|
||||
"args": ["server.py"],
|
||||
"env": {
|
||||
"API_KEY": "${YOUR_API_KEY}",
|
||||
"DEBUG": "true",
|
||||
"MAX_CONNECTIONS": "10"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Environment Variable Expansion:**
|
||||
|
||||
- `${VAR_NAME}`: Expands to environment variable value
|
||||
- `${VAR_NAME:-default}`: Uses default if variable not set
|
||||
- `${VAR_NAME:+value}`: Uses value if variable is set
|
||||
|
||||
### Working Directory
|
||||
|
||||
Set the working directory for server execution:
|
||||
|
||||
```json
|
||||
{
|
||||
"server-name": {
|
||||
"command": "./local-script.sh",
|
||||
"args": [],
|
||||
"cwd": "/path/to/server/directory"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Command Variations
|
||||
|
||||
Different ways to specify server commands:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="npm/npx">
|
||||
```json
|
||||
{
|
||||
"npm-server": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "package-name", "--option", "value"]
|
||||
}
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Python/uvx">
|
||||
```json
|
||||
{
|
||||
"python-server": {
|
||||
"command": "uvx",
|
||||
"args": ["package-name", "--config", "config.json"]
|
||||
}
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Direct Python">
|
||||
```json
|
||||
{
|
||||
"direct-python": {
|
||||
"command": "python",
|
||||
"args": ["-m", "module_name", "--arg", "value"]
|
||||
}
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Local Script">
|
||||
```json
|
||||
{
|
||||
"local-script": {
|
||||
"command": "./server.sh",
|
||||
"args": ["--port", "8080"],
|
||||
"cwd": "/path/to/script"
|
||||
}
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Hot Reloading
|
||||
|
||||
MCPHub supports hot reloading of server configurations:
|
||||
|
||||
1. **Config File Changes**: Automatically detects changes to `mcp_settings.json`
|
||||
2. **Dashboard Updates**: Immediately applies changes made through the web interface
|
||||
3. **API Updates**: Real-time updates via REST API calls
|
||||
4. **Zero Downtime**: Graceful server restarts without affecting other servers
|
||||
|
||||
### Resource Limits
|
||||
|
||||
Control server resource usage:
|
||||
|
||||
```json
|
||||
{
|
||||
"resource-limited-server": {
|
||||
"command": "memory-intensive-server",
|
||||
"args": [],
|
||||
"limits": {
|
||||
"memory": "512MB",
|
||||
"cpu": "50%",
|
||||
"timeout": "30s"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Dependency Management
|
||||
|
||||
Handle server dependencies:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Auto-installation">
|
||||
MCPHub can automatically install missing packages:
|
||||
|
||||
```json
|
||||
{
|
||||
"auto-install-server": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "package-that-might-not-exist"],
|
||||
"autoInstall": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Pre-installation Scripts">
|
||||
Run setup scripts before starting servers:
|
||||
|
||||
```json
|
||||
{
|
||||
"setup-server": {
|
||||
"preStart": ["npm install", "pip install -r requirements.txt"],
|
||||
"command": "python",
|
||||
"args": ["server.py"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Server Won't Start">
|
||||
**Check the following:**
|
||||
- Command is available in PATH
|
||||
- All required environment variables are set
|
||||
- Working directory exists and is accessible
|
||||
- Network ports are not blocked
|
||||
- Dependencies are installed
|
||||
|
||||
**Debug steps:**
|
||||
1. Check server logs in the dashboard
|
||||
2. Test command manually in terminal
|
||||
3. Verify environment variable expansion
|
||||
4. Check file permissions
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Server Keeps Crashing">
|
||||
**Common causes:**
|
||||
- Invalid configuration parameters
|
||||
- Missing API keys or credentials
|
||||
- Resource limits exceeded
|
||||
- Dependency conflicts
|
||||
|
||||
**Solutions:**
|
||||
1. Review server logs for error messages
|
||||
2. Test with minimal configuration
|
||||
3. Verify all credentials and API keys
|
||||
4. Check system resource availability
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tools Not Appearing">
|
||||
**Possible issues:**
|
||||
- Server not fully initialized
|
||||
- Tool discovery timeout
|
||||
- Communication protocol mismatch
|
||||
- Server reporting errors
|
||||
|
||||
**Debug steps:**
|
||||
1. Wait for server initialization to complete
|
||||
2. Check server logs for tool registration messages
|
||||
3. Test direct communication with server
|
||||
4. Verify MCP protocol compatibility
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Group Management" icon="users" href="/features/group-management">
|
||||
Organize servers into logical groups
|
||||
</Card>
|
||||
<Card title="Smart Routing" icon="route" href="/features/smart-routing">
|
||||
Set up AI-powered tool discovery
|
||||
</Card>
|
||||
<Card title="API Reference" icon="code" href="/api-reference/servers">
|
||||
Server management API documentation
|
||||
</Card>
|
||||
<Card title="Configuration Guide" icon="cog" href="/configuration/mcp-settings">
|
||||
Detailed configuration options
|
||||
</Card>
|
||||
</CardGroup>
|
||||
720
docs/features/smart-routing.mdx
Normal file
720
docs/features/smart-routing.mdx
Normal file
@@ -0,0 +1,720 @@
|
||||
---
|
||||
title: 'Smart Routing'
|
||||
description: 'AI-powered tool discovery using vector semantic search'
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Smart Routing is MCPHub's intelligent tool discovery system that uses vector semantic search to automatically find the most relevant tools for any given task. Instead of manually specifying which tools to use, AI clients can describe what they want to accomplish, and Smart Routing will identify and provide access to the most appropriate tools.
|
||||
|
||||
## How Smart Routing Works
|
||||
|
||||
### 1. Tool Indexing
|
||||
|
||||
When servers start up, Smart Routing automatically:
|
||||
|
||||
- Discovers all available tools from MCP servers
|
||||
- Extracts tool metadata (names, descriptions, parameters)
|
||||
- Converts tool information to vector embeddings
|
||||
- Stores embeddings in PostgreSQL with pgvector
|
||||
|
||||
### 2. Semantic Search
|
||||
|
||||
When a query is made:
|
||||
|
||||
- User queries are converted to vector embeddings
|
||||
- Similarity search finds matching tools using cosine similarity
|
||||
- Dynamic thresholds filter out irrelevant results
|
||||
- Results are ranked by relevance score
|
||||
|
||||
### 3. Intelligent Filtering
|
||||
|
||||
Smart Routing applies several filters:
|
||||
|
||||
- **Relevance Threshold**: Only returns tools above similarity threshold
|
||||
- **Context Awareness**: Considers conversation context
|
||||
- **Tool Availability**: Ensures tools are currently accessible
|
||||
- **Permission Filtering**: Respects user access permissions
|
||||
|
||||
### 4. Tool Execution
|
||||
|
||||
Found tools can be directly executed:
|
||||
|
||||
- Parameter validation ensures correct tool usage
|
||||
- Error handling provides helpful feedback
|
||||
- Response formatting maintains consistency
|
||||
- Logging tracks tool usage for analytics
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Smart Routing requires additional setup compared to basic MCPHub usage:
|
||||
|
||||
### Required Components
|
||||
|
||||
1. **PostgreSQL with pgvector**: Vector database for embeddings storage
|
||||
2. **Embedding Service**: OpenAI API or compatible service
|
||||
3. **Environment Configuration**: Proper configuration variables
|
||||
|
||||
### Quick Setup
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Docker Compose">
|
||||
Use this `docker-compose.yml` for complete setup:
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
mcphub:
|
||||
image: samanhappy/mcphub:latest
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
- DATABASE_URL=postgresql://mcphub:password@postgres:5432/mcphub
|
||||
- OPENAI_API_KEY=your_openai_api_key
|
||||
- ENABLE_SMART_ROUTING=true
|
||||
depends_on:
|
||||
- postgres
|
||||
volumes:
|
||||
- ./mcp_settings.json:/app/mcp_settings.json
|
||||
|
||||
postgres:
|
||||
image: pgvector/pgvector:pg16
|
||||
environment:
|
||||
- POSTGRES_DB=mcphub
|
||||
- POSTGRES_USER=mcphub
|
||||
- POSTGRES_PASSWORD=password
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
ports:
|
||||
- "5432:5432"
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
```
|
||||
|
||||
Start with:
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Manual Setup">
|
||||
1. **Install PostgreSQL with pgvector**:
|
||||
```bash
|
||||
# Using Docker
|
||||
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
|
||||
```
|
||||
|
||||
2. **Set Environment Variables**:
|
||||
```bash
|
||||
export DATABASE_URL="postgresql://mcphub:your_password@localhost:5432/mcphub"
|
||||
export OPENAI_API_KEY="your_openai_api_key"
|
||||
export ENABLE_SMART_ROUTING="true"
|
||||
```
|
||||
|
||||
3. **Start MCPHub**:
|
||||
```bash
|
||||
mcphub
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Kubernetes">
|
||||
Deploy with these Kubernetes manifests:
|
||||
|
||||
```yaml
|
||||
# postgres-deployment.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: postgres
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: postgres
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: postgres
|
||||
spec:
|
||||
containers:
|
||||
- name: postgres
|
||||
image: pgvector/pgvector:pg16
|
||||
env:
|
||||
- name: POSTGRES_DB
|
||||
value: mcphub
|
||||
- name: POSTGRES_USER
|
||||
value: mcphub
|
||||
- name: POSTGRES_PASSWORD
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: postgres-secret
|
||||
key: password
|
||||
ports:
|
||||
- containerPort: 5432
|
||||
---
|
||||
# mcphub-deployment.yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: mcphub
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: mcphub
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: mcphub
|
||||
spec:
|
||||
containers:
|
||||
- name: mcphub
|
||||
image: samanhappy/mcphub:latest
|
||||
env:
|
||||
- name: DATABASE_URL
|
||||
value: "postgresql://mcphub:password@postgres:5432/mcphub"
|
||||
- name: OPENAI_API_KEY
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: openai-secret
|
||||
key: api-key
|
||||
- name: ENABLE_SMART_ROUTING
|
||||
value: "true"
|
||||
ports:
|
||||
- containerPort: 3000
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Configure Smart Routing with these environment variables:
|
||||
|
||||
```bash
|
||||
# Required
|
||||
DATABASE_URL=postgresql://user:password@host:5432/database
|
||||
OPENAI_API_KEY=your_openai_api_key
|
||||
|
||||
# Optional
|
||||
ENABLE_SMART_ROUTING=true
|
||||
EMBEDDING_MODEL=text-embedding-3-small
|
||||
SIMILARITY_THRESHOLD=0.7
|
||||
MAX_TOOLS_RETURNED=10
|
||||
EMBEDDING_BATCH_SIZE=100
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Database Configuration">
|
||||
```bash
|
||||
# Full PostgreSQL connection string
|
||||
DATABASE_URL=postgresql://username:password@host:port/database?schema=public
|
||||
|
||||
# SSL configuration for cloud databases
|
||||
DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require
|
||||
|
||||
# Connection pool settings
|
||||
DATABASE_POOL_SIZE=20
|
||||
DATABASE_TIMEOUT=30000
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Embedding Service">
|
||||
```bash
|
||||
# OpenAI (default)
|
||||
OPENAI_API_KEY=sk-your-api-key
|
||||
EMBEDDING_MODEL=text-embedding-3-small
|
||||
|
||||
# Azure OpenAI
|
||||
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
|
||||
AZURE_OPENAI_API_KEY=your-api-key
|
||||
AZURE_OPENAI_DEPLOYMENT=your-embedding-deployment
|
||||
|
||||
# Custom embedding service
|
||||
EMBEDDING_SERVICE_URL=https://your-embedding-service.com
|
||||
EMBEDDING_SERVICE_API_KEY=your-api-key
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Search Parameters">
|
||||
```bash
|
||||
# Similarity threshold (0.0 to 1.0)
|
||||
SIMILARITY_THRESHOLD=0.7
|
||||
|
||||
# Maximum tools to return
|
||||
MAX_TOOLS_RETURNED=10
|
||||
|
||||
# Minimum query length for smart routing
|
||||
MIN_QUERY_LENGTH=5
|
||||
|
||||
# Cache TTL for embeddings (seconds)
|
||||
EMBEDDING_CACHE_TTL=3600
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Using Smart Routing
|
||||
|
||||
### Smart Routing Endpoint
|
||||
|
||||
Access Smart Routing through the special `$smart` endpoint:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="HTTP MCP">
|
||||
```
|
||||
http://localhost:3000/mcp/$smart
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="SSE (Legacy)">
|
||||
```
|
||||
http://localhost:3000/sse/$smart
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Basic Usage
|
||||
|
||||
Connect your AI client to the Smart Routing endpoint and make natural language requests:
|
||||
|
||||
```bash
|
||||
# Example: Find tools for web scraping
|
||||
curl -X POST http://localhost:3000/mcp/$smart \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/search",
|
||||
"params": {
|
||||
"query": "scrape website content and extract text"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": {
|
||||
"tools": [
|
||||
{
|
||||
"name": "fetch_html",
|
||||
"server": "fetch",
|
||||
"description": "Fetch and parse HTML content from a URL",
|
||||
"relevanceScore": 0.92,
|
||||
"parameters": { ... }
|
||||
},
|
||||
{
|
||||
"name": "playwright_navigate",
|
||||
"server": "playwright",
|
||||
"description": "Navigate to a web page and extract content",
|
||||
"relevanceScore": 0.87,
|
||||
"parameters": { ... }
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Queries
|
||||
|
||||
Smart Routing supports various query types:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Task-Based Queries">
|
||||
```bash
|
||||
# What you want to accomplish
|
||||
curl -X POST http://localhost:3000/mcp/$smart \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/search",
|
||||
"params": {
|
||||
"query": "send a message to a slack channel"
|
||||
}
|
||||
}'
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Domain-Specific Queries">
|
||||
```bash
|
||||
# Specific domain or technology
|
||||
curl -X POST http://localhost:3000/mcp/$smart \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/search",
|
||||
"params": {
|
||||
"query": "database operations SQL queries"
|
||||
}
|
||||
}'
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Action-Oriented Queries">
|
||||
```bash
|
||||
# Specific actions
|
||||
curl -X POST http://localhost:3000/mcp/$smart \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/search",
|
||||
"params": {
|
||||
"query": "create file upload to github repository"
|
||||
}
|
||||
}'
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Context-Aware Queries">
|
||||
```bash
|
||||
# Include context for better results
|
||||
curl -X POST http://localhost:3000/mcp/$smart \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/search",
|
||||
"params": {
|
||||
"query": "automated testing web application",
|
||||
"context": {
|
||||
"project": "e-commerce website",
|
||||
"technologies": ["React", "Node.js"],
|
||||
"environment": "staging"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Tool Execution
|
||||
|
||||
Once Smart Routing finds relevant tools, you can execute them directly:
|
||||
|
||||
```bash
|
||||
# Execute a found tool
|
||||
curl -X POST http://localhost:3000/mcp/$smart \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 2,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "fetch_html",
|
||||
"arguments": {
|
||||
"url": "https://example.com"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Embedding Cache
|
||||
|
||||
Smart Routing caches embeddings to improve performance:
|
||||
|
||||
```bash
|
||||
# Configure cache settings
|
||||
EMBEDDING_CACHE_TTL=3600 # Cache for 1 hour
|
||||
EMBEDDING_CACHE_SIZE=10000 # Cache up to 10k embeddings
|
||||
EMBEDDING_CACHE_CLEANUP=300 # Cleanup every 5 minutes
|
||||
```
|
||||
|
||||
### Batch Processing
|
||||
|
||||
Tools are indexed in batches for efficiency:
|
||||
|
||||
```bash
|
||||
# Batch size for embedding generation
|
||||
EMBEDDING_BATCH_SIZE=100
|
||||
|
||||
# Concurrent embedding requests
|
||||
EMBEDDING_CONCURRENCY=5
|
||||
|
||||
# Index update frequency
|
||||
INDEX_UPDATE_INTERVAL=3600 # Re-index every hour
|
||||
```
|
||||
|
||||
### Database Optimization
|
||||
|
||||
Optimize PostgreSQL for vector operations:
|
||||
|
||||
```sql
|
||||
-- Create indexes for better performance
|
||||
CREATE INDEX ON tool_embeddings USING hnsw (embedding vector_cosine_ops);
|
||||
|
||||
-- Adjust PostgreSQL settings
|
||||
ALTER SYSTEM SET shared_preload_libraries = 'vector';
|
||||
ALTER SYSTEM SET max_connections = 200;
|
||||
ALTER SYSTEM SET shared_buffers = '256MB';
|
||||
ALTER SYSTEM SET effective_cache_size = '1GB';
|
||||
```
|
||||
|
||||
## Monitoring and Analytics
|
||||
|
||||
### Smart Routing Metrics
|
||||
|
||||
Monitor Smart Routing performance:
|
||||
|
||||
```bash
|
||||
# Get Smart Routing statistics
|
||||
curl http://localhost:3000/api/smart-routing/stats \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
Response includes:
|
||||
|
||||
- Query count and frequency
|
||||
- Average response time
|
||||
- Embedding cache hit rate
|
||||
- Most popular tools
|
||||
- Query patterns
|
||||
|
||||
### Tool Usage Analytics
|
||||
|
||||
Track which tools are found and used:
|
||||
|
||||
```bash
|
||||
# Get tool usage analytics
|
||||
curl http://localhost:3000/api/smart-routing/analytics \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
Metrics include:
|
||||
|
||||
- Tool discovery rates
|
||||
- Execution success rates
|
||||
- User satisfaction scores
|
||||
- Query-to-execution conversion
|
||||
|
||||
### Performance Monitoring
|
||||
|
||||
Monitor system performance:
|
||||
|
||||
```bash
|
||||
# Database performance
|
||||
curl http://localhost:3000/api/smart-routing/db-stats \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
|
||||
# Embedding service status
|
||||
curl http://localhost:3000/api/smart-routing/embedding-stats \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Custom Embeddings
|
||||
|
||||
Use custom embedding models:
|
||||
|
||||
```bash
|
||||
# Hugging Face models
|
||||
EMBEDDING_SERVICE=huggingface
|
||||
HUGGINGFACE_MODEL=sentence-transformers/all-MiniLM-L6-v2
|
||||
HUGGINGFACE_API_KEY=your_api_key
|
||||
|
||||
# Local embedding service
|
||||
EMBEDDING_SERVICE=local
|
||||
EMBEDDING_SERVICE_URL=http://localhost:8080/embeddings
|
||||
```
|
||||
|
||||
### Query Enhancement
|
||||
|
||||
Enhance queries for better results:
|
||||
|
||||
```json
|
||||
{
|
||||
"queryEnhancement": {
|
||||
"enabled": true,
|
||||
"expandAcronyms": true,
|
||||
"addSynonyms": true,
|
||||
"contextualExpansion": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Result Filtering
|
||||
|
||||
Filter results based on criteria:
|
||||
|
||||
```json
|
||||
{
|
||||
"resultFiltering": {
|
||||
"minRelevanceScore": 0.7,
|
||||
"maxResults": 10,
|
||||
"preferredServers": ["fetch", "playwright"],
|
||||
"excludeServers": ["deprecated-server"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Feedback Learning
|
||||
|
||||
Improve results based on user feedback:
|
||||
|
||||
```bash
|
||||
# Provide feedback on search results
|
||||
curl -X POST http://localhost:3000/api/smart-routing/feedback \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"queryId": "search-123",
|
||||
"toolName": "fetch_html",
|
||||
"rating": 5,
|
||||
"successful": true,
|
||||
"comments": "Perfect tool for the task"
|
||||
}'
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Database Connection Issues">
|
||||
**Symptoms:**
|
||||
- Smart Routing not available
|
||||
- Database connection errors
|
||||
- Embedding storage failures
|
||||
|
||||
**Solutions:**
|
||||
1. Verify PostgreSQL is running
|
||||
2. Check DATABASE_URL format
|
||||
3. Ensure pgvector extension is installed
|
||||
4. Test connection manually:
|
||||
```bash
|
||||
psql $DATABASE_URL -c "SELECT 1;"
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Embedding Service Problems">
|
||||
**Symptoms:**
|
||||
- Tool indexing failures
|
||||
- Query processing errors
|
||||
- API rate limit errors
|
||||
|
||||
**Solutions:**
|
||||
1. Verify API key validity
|
||||
2. Check network connectivity
|
||||
3. Monitor rate limits
|
||||
4. Test embedding service:
|
||||
```bash
|
||||
curl -X POST https://api.openai.com/v1/embeddings \
|
||||
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"input": "test", "model": "text-embedding-3-small"}'
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Poor Search Results">
|
||||
**Symptoms:**
|
||||
- Irrelevant tools returned
|
||||
- Low relevance scores
|
||||
- Missing expected tools
|
||||
|
||||
**Solutions:**
|
||||
1. Adjust similarity threshold
|
||||
2. Re-index tools with better descriptions
|
||||
3. Use more specific queries
|
||||
4. Check tool metadata quality
|
||||
```bash
|
||||
# Re-index all tools
|
||||
curl -X POST http://localhost:3000/api/smart-routing/reindex \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Performance Issues">
|
||||
**Symptoms:**
|
||||
- Slow query responses
|
||||
- High database load
|
||||
- Memory usage spikes
|
||||
|
||||
**Solutions:**
|
||||
1. Optimize database configuration
|
||||
2. Increase cache sizes
|
||||
3. Reduce batch sizes
|
||||
4. Monitor system resources
|
||||
```bash
|
||||
# Check system performance
|
||||
curl http://localhost:3000/api/smart-routing/performance \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Query Writing
|
||||
|
||||
<Tip>
|
||||
**Be Descriptive**: Use specific, descriptive language in queries for better tool matching.
|
||||
</Tip>
|
||||
|
||||
<Tip>
|
||||
**Include Context**: Provide relevant context about your task or domain for more accurate results.
|
||||
</Tip>
|
||||
|
||||
<Tip>**Use Natural Language**: Write queries as you would describe the task to a human.</Tip>
|
||||
|
||||
### Tool Descriptions
|
||||
|
||||
<Warning>
|
||||
**Quality Metadata**: Ensure MCP servers provide high-quality tool descriptions and metadata.
|
||||
</Warning>
|
||||
|
||||
<Warning>**Regular Updates**: Keep tool descriptions current as functionality evolves.</Warning>
|
||||
|
||||
<Warning>
|
||||
**Consistent Naming**: Use consistent naming conventions across tools and servers.
|
||||
</Warning>
|
||||
|
||||
### System Maintenance
|
||||
|
||||
<Info>**Regular Re-indexing**: Periodically re-index tools to ensure embedding quality.</Info>
|
||||
|
||||
<Info>**Monitor Performance**: Track query patterns and optimize based on usage.</Info>
|
||||
|
||||
<Info>
|
||||
**Update Models**: Consider updating to newer embedding models as they become available.
|
||||
</Info>
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Authentication" icon="shield" href="/features/authentication">
|
||||
User management and access control
|
||||
</Card>
|
||||
<Card title="Monitoring" icon="chart-line" href="/features/monitoring">
|
||||
System monitoring and analytics
|
||||
</Card>
|
||||
<Card title="API Reference" icon="code" href="/api-reference/smart-routing">
|
||||
Complete Smart Routing API documentation
|
||||
</Card>
|
||||
<Card title="Configuration" icon="cog" href="/configuration/environment-variables">
|
||||
Advanced configuration options
|
||||
</Card>
|
||||
</CardGroup>
|
||||
Reference in New Issue
Block a user