Content
# Liblib MCP Server
> Lightweight MCP Server based on `mark3labs/mcp-go`, dynamically publishing Liblib platform's ComfyUI workflows as MCP Tools, supporting multi-tenant management.
[](https://golang.org/)
[](https://www.docker.com/)
[](LICENSE)
## <div align="center"> **🎯 Project Features** </div>
- **🚀 Lightweight Architecture**: Using Go standard library `http.ServeMux`, minimal dependency design
- **🔌 Unified Server**: Single port providing MCP service + management API + static file service
- **👥 Multi-Tenant Support**: Simplified design of one user, one key, one token, secure isolation
- **🎨 Modern UI**: Management interface built with React + TypeScript + Tailwind CSS
- **🔒 Secure Encryption**: AES-256-GCM encrypted storage of API keys, Bearer Token authentication
- **🐳 Containerized Deployment**: Multi-stage Docker build, production-ready
## <div align="center"> **🏗️ Architecture Design** </div>
```
┌─────────────┐ StreamableHTTP ┌────────────────────────────┐
│ MCP Client │◄─────────────────┤ │
└─────────────┘ │ │
│ Unified HTTP Server │
┌─────────────┐ HTTP/JSON │ (Go http.ServeMux) │
│ Management UI │◄─────────────────┤ │
└─────────────┘ │ /mcp/ │ /api/v1/ │ / │
└────────┼──────────┼────────┘
│ │ │
MCP Service Management API Static Files
┌──────────────────────────────┐
│ Data Layer │
│ SQLite/MySQL + GORM │
└──────────────────────────────┘
```
## <div align="center"> **🛠️ Technical Stack** </div>
| Layer | Technology Selection | Description |
|------|----------|------|
| **Backend** | Go 1.23+ + standard library `http.ServeMux` | Lightweight routing, zero third-party framework dependency |
| **MCP** | mark3labs/mcp-go | StreamableHTTP protocol support |
| **Frontend** | React 18 + TypeScript + Vite | Modern build toolchain |
| **Styles** | Tailwind CSS 4.x | Practical CSS framework |
| **Database** | SQLite (development) / MySQL (production) | GORM ORM support |
| **Deployment** | Docker + Multi-stage Build | Single image containing frontend and backend |
## <div align="center"> **📦 Core Dependencies** </div>
```go
// Keep only necessary dependencies to ensure lightweight
require (
github.com/mark3labs/mcp-go v0.33.0 // MCP protocol
github.com/rs/zerolog v1.34.0 // Structured logging
gorm.io/gorm v1.30.0 // Database ORM
gorm.io/driver/sqlite v1.6.0 // SQLite driver
gorm.io/driver/mysql v1.6.0 // MySQL driver
)
```
## <div align="center"> **🚀 Quick Start** </div>
### Method 1: Docker Deployment (Recommended)
```bash
# Pull the latest image (supporting x86_64 and ARM64)
docker pull ccr.ccs.tencentyun.com/yfgaia/liblib-mcp-server:latest
# Quick start
docker run -d \
-p 8080:8080 \
-v $(pwd)/data:/app/data \
-v $(pwd)/logs:/app/logs \
--name liblib-mcp-server \
ccr.ccs.tencentyun.com/yfgaia/liblib-mcp-server:latest
# Use Docker Compose (recommended)
docker-compose -f docker-compose.prod.yml up -d
```
### Method 2: Source Code Deployment
1. **Environment Requirements**
- Go 1.23+
- Node.js 20+
- Git
1. **Build Backend**
```bash
git clone https://github.com/WW-AI-Lab/liblib-mcp-server.git
cd liblib-mcp-server
go mod download
go build -o bin/server ./cmd/server
```
1. **Build Frontend**
```bash
cd web
npm install
npm run build
cd ..
```
1. **Configure Environment**
```bash
cp config.env.example config.env
# Edit config.env to fill in necessary configurations
```
1. **Start Service**
```bash
./bin/server
```
## <div align="center"> **⚙️ Configuration Instructions** </div>
### Environment Variable Configuration
| Variable Name | Required | Default Value | Description |
|--------|------|--------|------|
| `PORT` | No | `8080` | Service listening port |
| `ENV` | No | `development` | Running environment |
| `LOG_LEVEL` | No | `info` | Log level |
| `DB_TYPE` | No | `sqlite` | Database type (`sqlite`/`mysql`) |
| `DB_PATH` | No | `./data/liblib.db` | SQLite database path |
| `MCP_KMS_KEY` | **Yes** | - | 32-character encryption key |
| `JWT_SECRET` | **Yes** | - | JWT signature key |
| `STATIC_DIR` | No | `./web/dist` | Static file directory |
| `LIBLIB_API_BASE` | No | `https://openapi.liblibai.cloud` | Liblib API base URL |
### MySQL Configuration (Production Environment)
```bash
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=liblib_mcp
DB_USER=liblib
DB_PASSWORD=your_password
```
## <div align="center"> **📖 Usage Guide** </div>
### 1. Initial Setup
1. **Access Management Interface**: http://localhost:8080
2. **Email Login**: Enter email (automatically creates user on first use)
3. **Configure Liblib Key**: Add AccessKey/SecretKey on "Key Management" page
4. **Add Workflow**: Register ComfyUI workflow on "Workflow Management" page
### 2. MCP Client Connection
#### Cursor/Other MCP Client Configuration
Add in MCP settings:
```json
{
"liblib": {
"command": "npx",
"args": [
"@modelcontextprotocol/server-everything"
],
"env": {
"MCP_SERVER_URL": "http://localhost:8080/mcp",
"MCP_AUTH_TOKEN": "your-bearer-token-here"
}
}
}
```
#### Use mcp_test_client
```bash
# Test MCP connection
go run mcp_test_client.go -endpoint="http://localhost:8080/mcp" -token="your-bearer-token"
```
### 3. Workflow Management
1. **Register Workflow**:
- Provide workflow name and description
- Input Liblib workflow UUID
- Paste parameter example JSON (for automatic parameter structure parsing)
2. **Automatic Tool Generation**:
- System automatically parses parameter structure
- Generates corresponding MCP Tool
- Supports dynamic parameter verification
3. **Tool Invocation**:
- MCP Client automatically discovers tools
- Automatically uses user's Liblib key when calling
- Asynchronous execution, supports status query
## <div align="center"> **🔧 API Documentation** </div>
### Authentication API
```bash
# User login
POST /api/v1/auth/login
Content-Type: application/json
{"email": "user@example.com"}
# Return: {"token": "jwt_token", "user": {...}}
```
### Key Management API
```bash
# Add key
POST /api/v1/credentials
Authorization: Bearer <jwt_token>
Content-Type: application/json
{
"name": "Production Environment",
"access_key": "your_access_key",
"secret_key": "your_secret_key"
}
# Get key list
GET /api/v1/credentials
Authorization: Bearer <jwt_token>
```
### Workflow Management API
```bash
# Register workflow
POST /api/v1/workflows
Authorization: Bearer <jwt_token>
Content-Type: application/json
{
"name": "Image Generation",
"workflow_uuid": "workflow-uuid-here",
"description": "Generate high-quality images",
"params_json": "{\"prompt\": \"Example prompt\"}"
}
# Get workflow list
GET /api/v1/workflows
Authorization: Bearer <jwt_token>
```
## <div align="center"> **🛡️ Security** </div>
### Data Encryption
- **Key Encryption**: Use AES-256-GCM to encrypt and store Liblib API keys
- **Transmission Encryption**: Support HTTPS deployment
- **Token Security**: JWT Token signature verification
### Multi-Tenant Isolation
- **Data Isolation**: Each user can only access their own resources
- **Tool Isolation**: MCP tools filtered based on Bearer Token
- **API Isolation**: Interface-level permission control
## <div align="center"> **📊 Monitoring and Maintenance** </div>
### Health Check
```bash
curl http://localhost:8080/health
# Return: OK (200)
```
### Log Viewing
```bash
# Docker container logs
docker logs liblib-mcp
# Local deployment logs
tail -f logs/backend.log
```
## <div align="center"> **🧪 Testing** </div>
### Unit Testing
```bash
go test ./...
```
### Frontend Testing
```bash
cd web
npm test
```
### MCP Integration Testing
```bash
./scripts/test_mcp_basic.sh
```
## <div align="center"> **🤝 Contribution Guide** </div>
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 the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
### Development Specifications
- Follow [lightweight architecture principles](docs/architecture.md)
- Use standard library first, minimize dependencies
- Maintain single-port unified service architecture
- Add sufficient unit tests
## <div align="center"> **📄 License** </div>
This project uses the MIT License - see [LICENSE](LICENSE) file for details.
## <div align="center"> **🙏 Acknowledgements** </div>
- [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) - Excellent MCP Go implementation
- [Liblib AI](https://www.liblib.art) - ComfyUI workflow platform
- [GORM](https://gorm.io) - Go ORM library
## <div align="center"> **📞 Support** </div>
- 🐛 **Issue Feedback**: [GitHub Issues](https://github.com/WW-AI-Lab/liblib-mcp-server/issues)
- 💬 **Discussion**: [GitHub Discussions](https://github.com/WW-AI-Lab/liblib-mcp-server/discussions)
- 📧 **Business Cooperation**: toxingwang@gmail.com
---
<div align="center">
**[🏠 Home](https://github.com/WW-AI-Lab)** • **[📖 Documentation](docs/)** • **[🚀 Deployment Guide](docs/deploy.md)** • **[🔧 API Documentation](docs/api.md)**
</div>
