Content
# Tool List
<div align="center">
**Enterprise-level Service Governance Platform based on Anthropic MCP Protocol**
[English](README_EN.md) |
</div>
---
## 📖 Introduction
MCP Hub is an enterprise-level Model Context Protocol (MCP) service governance platform that provides unified MCP Server management, permission control, audit logs, and cost tracking.
### Core Features
- 🚀 **Unified Management** - Centralized management of all MCP Server registration, configuration, and lifecycle
- 🔐 **Permission Control** - Fine-grained permission management based on RBAC, supporting JWT authentication
- 📊 **Multi-tenancy** - Complete workspace isolation, supporting team collaboration
- 📝 **Audit Logs** - Complete operation audit tracking
- 💰 **Cost Tracking** - API call cost statistics and analysis
- 🗄️ **Lightweight** - Using SQLite database, no additional dependencies
- 🔌 **Protocol Adaptation** - Complete MCP protocol support
---
## 🏗️ Architecture Design
```
┌─────────────────────────────────────────────────────────┐
│ API Gateway │
│ (RESTful API + JWT Auth) │
└─────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌───────▼────────┐ ┌──────▼──────┐ ┌────────▼────────┐
│ Permission │ │ Workspace │ │ Server │
│ Engine │ │ Manager │ │ Manager │
│ (RBAC + JWT) │ │ (Multi- │ │ (Lifecycle) │
│ │ │ Tenant) │ │ │
└────────────────┘ └─────────────┘ └─────────────────┘
│ │ │
└───────────────────┼───────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌───────▼────────┐ ┌──────▼──────┐ ┌────────▼────────┐
│ Audit Logger │ │ Cost │ │ Protocol │
│ │ │ Tracker │ │ Adapter │
└────────────────┘ └─────────────┘ └─────────────────┘
│
┌───────▼────────┐
│ SQLite Store │
│ (Data Layer) │
└────────────────┘
```
---
## 🚀 Quick Start
### Prerequisites
- Go 1.20 or higher
- Git
### Installation Steps
#### 1. Clone Repository
```bash
git clone https://github.com/Mhunzi/mcp-hub.git
cd mcp-hub
```
#### 2. Install Dependencies
```bash
# If you are in mainland China, consider setting up a proxy
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=off
# Download dependencies
go mod download
```
#### 3. Run Service
```bash
# Run directly
go run cmd/server/main.go
# Or build and run
go build -o mcp-hub cmd/server/main.go
./mcp-hub
```
Service will start at `http://localhost:8080`
#### 4. Verify Installation
```bash
curl http://localhost:8080/health
# Response: {"status":"healthy"}
```
---
## 📚 User Guide
### Default Credentials
The system automatically creates an administrator account on the first startup:
- **Username**: `admin`
- **Password**: `admin`
⚠️ **Change the default password in production immediately!**
### API Usage Example
#### 1. User Login
```bash
curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "admin"
}'
```
**Response**:
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "user_admin",
"username": "admin",
"email": "admin@mcp-hub.local"
}
}
```
#### 2. Create Workspace
```bash
TOKEN="your-jwt-token"
curl -X POST http://localhost:8080/api/v1/workspaces \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My Workspace",
"description": "Team collaboration space"
}'
```
#### 3. Register MCP Server
```bash
curl -X POST http://localhost:8080/api/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "File System Service",
"source": "npm",
"version": "1.0.0",
"workspace_id": "your-workspace-id",
"config": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
}
}'
```
#### 4. Query Servers
```bash
curl http://localhost:8080/api/v1/servers?workspace_id=your-workspace-id \
-H "Authorization: Bearer $TOKEN"
```
#### 5. Start Server
```bash
curl -X POST http://localhost:8080/api/v1/servers/{server_id}/start \
-H "Authorization: Bearer $TOKEN"
```
#### 6. View Audit Logs
```bash
curl "http://localhost:8080/api/v1/audit/logs?workspace_id=your-workspace-id&limit=50" \
-H "Authorization: Bearer $TOKEN"
```
#### 7. View Cost Statistics
```bash
curl "http://localhost:8080/api/v1/cost/stats?workspace_id=your-workspace-id&start_time=2024-01-01T00:00:00Z&end_time=2024-12-31T23:59:59Z" \
-H "Authorization: Bearer $TOKEN"
```
---
## 🔧 Configuration Instructions
### Environment Variables
| Variable | Description | Default Value |
|--------|------|--------|
| `PORT` | Service listening port | `8080` |
| `JWT_SECRET` | JWT signature key | `default-secret-change-in-production` |
| `MCP_HUB_DATA_DIR` | Data storage directory | `~/.mcp-hub/data` |
### Configuration Example
```bash
# Linux/Mac
export PORT=3000
export JWT_SECRET="your-super-secret-key-change-me"
export MCP_HUB_DATA_DIR="/var/lib/mcp-hub"
# Windows
set PORT=3000
set JWT_SECRET=your-super-secret-key-change-me
set MCP_HUB_DATA_DIR=C:\mcp-hub\data
```
---
## 📡 API Endpoints
### Authentication
| Method | Path | Description |
|------|------|------|
| POST | `/api/v1/auth/login` | User login |
| POST | `/api/v1/auth/logout` | User logout |
| POST | `/api/v1/auth/refresh` | Refresh Token |
### User Management
| Method | Path | Description |
|------|------|------|
| GET | `/api/v1/users` | List users |
| POST | `/api/v1/users` | Create user |
| GET | `/api/v1/users/{id}` | Get user details |
| PUT | `/api/v1/users/{id}` | Update user |
| DELETE | `/api/v1/users/{id}` | Delete user |
### Workspace Management
| Method | Path | Description |
|------|------|------|
| GET | `/api/v1/workspaces` | List workspaces |
| POST | `/api/v1/workspaces` | Create workspace |
| GET | `/api/v1/workspaces/{id}` | Get workspace details |
| PUT | `/api/v1/workspaces/{id}` | Update workspace |
| DELETE | `/api/v1/workspaces/{id}` | Delete workspace |
### Server Management
| Method | Path | Description |
|------|------|------|
| GET | `/api/v1/servers` | List Servers |
| POST | `/api/v1/servers` | Register Server |
| GET | `/api/v1/servers/{id}` | Get Server details |
| PUT | `/api/v1/servers/{id}` | Update Server |
| DELETE | `/api/v1/servers/{id}` | Delete Server |
| POST | `/api/v1/servers/{id}/start` | Start Server |
| POST | `/api/v1/servers/{id}/stop` | Stop Server |
### Audit Logs
| Method | Path | Description |
|------|------|------|
| GET | `/api/v1/audit/logs` | Query audit logs |
### Cost Statistics
| Method | Path | Description |
|------|------|------|
| GET | `/api/v1/cost/stats` | Get cost statistics |
### System
| Method | Path | Description |
|------|------|------|
| GET | `/health` | Health check |
---
## 🔐 Permission System
### Built-in Roles
| Role | Permissions |
|------|------|
| `admin` | Complete access permissions |
| `developer` | Server management permissions |
| `viewer` | Read-only permissions |
### Permission Matrix
| Resource | admin | developer | viewer |
|------|-------|-----------|--------|
| User Management | ✅ | ❌ | ❌ |
| Workspace Management | ✅ | ✅ | ❌ |
| Server Management | ✅ | ✅ | ❌ |
| View Data | ✅ | ✅ | ✅ |
| Audit Logs | ✅ | ✅ | ✅ |
---
## 🗄️ Database Structure
### Core Tables
- `users` - User information
- `roles` - Role definitions
- `user_roles` - User role associations
- `workspaces` - Workspaces
- `servers` - MCP Server registration information
- `audit_logs` - Audit logs
- `cost_records` - Cost records
For detailed database schema, please refer to [internal/datastore/sqlite.go](internal/datastore/sqlite.go)
---
## 🧪 Testing
### Run Tests
```bash
# Run all tests
go test ./...
# Run unit tests
go test ./tests/unit/...
# Run integration tests
go test ./tests/integration/...
# Run E2E tests
go test ./tests/e2e/...
# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```
### Test Report
View the complete test report: [RUNTIME_TEST_REPORT.md](RUNTIME_TEST_REPORT.md)
---
## 📦 Deployment
### Docker Deployment
```dockerfile
# Dockerfile
FROM golang:1.20-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download
RUN go build -o mcp-hub cmd/server/main.go
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/mcp-hub .
EXPOSE 8080
CMD ["./mcp-hub"]
```
```bash
# Build image
docker build -t mcp-hub:latest .
# Run container
docker run -d \
-p 8080:8080 \
-e JWT_SECRET=your-secret-key \
-v /path/to/data:/root/.mcp-hub/data \
--name mcp-hub \
mcp-hub:latest
```
### Systemd Service
```ini
# /etc/systemd/system/mcp-hub.service
[Unit]
Description=MCP Hub Service
After=network.target
[Service]
Type=simple
User=mcp-hub
WorkingDirectory=/opt/mcp-hub
ExecStart=/opt/mcp-hub/mcp-hub
Restart=on-failure
Environment="JWT_SECRET=your-secret-key"
Environment="PORT=8080"
[Install]
WantedBy=multi-user.target
```
```bash
# Start service
sudo systemctl daemon-reload
sudo systemctl enable mcp-hub
sudo systemctl start mcp-hub
sudo systemctl status mcp-hub
```
---
## 🛠️ Development Guide
### Project Structure
```
mcp-hub/
├── cmd/
│ └── server/ # Main program entry
│ └── main.go
├── internal/
│ ├── api/ # API gateway layer
│ ├── audit/ # Audit logs
│ ├── cost/ # Cost tracking
│ ├── datastore/ # Data persistence layer
│ ├── permission/ # Permission engine
│ ├── protocol/ # MCP protocol adaptation
│ ├── server/ # Server management
│ └── workspace/ # Workspace management
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
├── go.mod
├── go.sum
└── README.md
```
### Add New Features
1. Create a new module under `internal/`
2. Implement business logic
3. Add API endpoints in `internal/api/`
4. Write test cases
5. Update documentation
### Code Style
- Follow Go official code style
- Use `gofmt` to format code
- Use `golint` to check code quality
- Write unit tests, maintain test coverage > 80%
---
## 🤝 Contribution Guide
Welcome to contribute code! Please follow these steps:
1. Fork this repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to branch (`git push origin feature/AmazingFeature`)
5. Open Pull Request
### Commit Style
```
feat: New feature
fix: Fix bug
docs: Documentation update
style: Code format adjustment
refactor: Refactor
test: Test related
chore: Build/toolchain related
```
---
## 📄 License
This project uses MIT License - see [LICENSE](LICENSE) file
---
## 🙏 Acknowledgments
- [Anthropic](https://www.anthropic.com/) - MCP protocol design
- [Go](https://golang.org/) - Programming language
- [SQLite](https://www.sqlite.org/) - Database
- [JWT](https://jwt.io/) - Authentication standard
---
## 📞 Contact
- Issue feedback: [GitHub Issues](https://github.com/yourusername/mcp-hub/issues)
- Feature suggestions: [GitHub Discussions](https://github.com/yourusername/mcp-hub/discussions)
---
## 🗺️ Roadmap
### v1.0 (Current Version)
- ✅ Core functionality implementation
- ✅ RESTful API
- ✅ JWT authentication
- ✅ RBAC permission control
- ✅ Audit logs
- ✅ Cost tracking
### v1.1 (Planned)
- ⏸️ Web management interface
- ⏸️ CLI command-line tool
- ⏸️ Server health check
- ⏸️ Performance monitoring
### v2.0 (Future)
- ⏸️ PostgreSQL support
- ⏸️ Distributed deployment
- ⏸️ Plugin system
- ⏸️ Monitoring and alerting
---
<div align="center">
**⭐ If this project helps you, give it a Star!⭐**
Made with ❤️ by MCP Hub Team
</div>
