内容
# Liblib MCP Server
> 基于 `mark3labs/mcp-go` 开发的轻量级 MCP Server，将 Liblib 平台的 ComfyUI 工作流动态发布为 MCP Tools，支持多租户管理。
[](https://golang.org/)
[](https://www.docker.com/)
[](LICENSE)
## 🎯 项目特点
- **🚀 轻量化架构**: 使用 Go 标准库 `http.ServeMux`，最小依赖设计
- **🔌 统一服务器**: 单端口提供 MCP 服务 + 管理 API + 静态文件服务
- **👥 多租户支持**: 一用户一密钥一Token的简化设计，安全隔离
- **🎨 现代化 UI**: React + TypeScript + Tailwind CSS 构建的管理界面
- **🔒 安全加密**: AES-256-GCM 加密存储 API 密钥，Bearer Token 认证
- **🐳 容器化部署**: 多阶段 Docker 构建，生产就绪
## 🏗️ 架构设计
```
┌─────────────┐ StreamableHTTP ┌────────────────────────────┐
│ MCP Client │◄─────────────────┤ │
└─────────────┘ │ │
│ 统一 HTTP 服务器 │
┌─────────────┐ HTTP/JSON │ (Go http.ServeMux) │
│ 管理 UI │◄─────────────────┤ │
└─────────────┘ │ /mcp/ │ /api/v1/ │ / │
└────────┼──────────┼────────┘
│ │ │
MCP 服务 管理API 静态文件
┌──────────────────────────────┐
│ 数据层 │
│ SQLite/MySQL + GORM │
└──────────────────────────────┘
```
## 🛠️ 技术栈
| 层级 | 技术选型 | 说明 |
|------|----------|------|
| **后端** | Go 1.23+ + 标准库 `http.ServeMux` | 轻量级路由，零第三方框架依赖 |
| **MCP** | mark3labs/mcp-go | StreamableHTTP 协议支持 |
| **前端** | React 18 + TypeScript + Vite | 现代化构建工具链 |
| **样式** | Tailwind CSS 4.x | 实用优先的 CSS 框架 |
| **数据库** | SQLite (开发) / MySQL (生产) | GORM ORM 支持 |
| **部署** | Docker + Multi-stage Build | 单镜像包含前后端 |
## 📦 核心依赖
```go
// 仅保留必需依赖，确保轻量化
require (
github.com/mark3labs/mcp-go v0.33.0 // MCP 协议
github.com/rs/zerolog v1.34.0 // 结构化日志
gorm.io/gorm v1.30.0 // 数据库 ORM
gorm.io/driver/sqlite v1.6.0 // SQLite 驱动
gorm.io/driver/mysql v1.6.0 // MySQL 驱动
)
```
## 🚀 快速开始
### 方式一：Docker 部署（推荐）
```bash
# 拉取最新镜像（支持 x86_64 和 ARM64）
docker pull ccr.ccs.tencentyun.com/yfgaia/liblib-mcp-server:latest
# 快速启动
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
# 使用 Docker Compose（推荐）
docker-compose -f docker-compose.prod.yml up -d
```
### 方式二：源码部署
1. **环境要求**
- Go 1.23+
- Node.js 20+
- Git
1. **构建后端**
```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. **构建前端**
```bash
cd web
npm install
npm run build
cd ..
```
1. **配置环境**
```bash
cp config.env.example config.env
# 编辑 config.env 填入必要配置
```
1. **启动服务**
```bash
./bin/server
```
## ⚙️ 配置说明
### 环境变量配置
| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `PORT` | 否 | `8080` | 服务监听端口 |
| `ENV` | 否 | `development` | 运行环境 |
| `LOG_LEVEL` | 否 | `info` | 日志级别 |
| `DB_TYPE` | 否 | `sqlite` | 数据库类型 (`sqlite`/`mysql`) |
| `DB_PATH` | 否 | `./data/liblib.db` | SQLite 数据库路径 |
| `MCP_KMS_KEY` | **是** | - | 32字符加密密钥 |
| `JWT_SECRET` | **是** | - | JWT 签名密钥 |
| `STATIC_DIR` | 否 | `./web/dist` | 静态文件目录 |
| `LIBLIB_API_BASE` | 否 | `https://openapi.liblibai.cloud` | Liblib API 基础 URL |
### MySQL 配置（生产环境）
```bash
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=liblib_mcp
DB_USER=liblib
DB_PASSWORD=your_password
```
## 📖 使用指南
### 1. 首次设置
1. **访问管理界面**: http://localhost:8080
2. **邮箱登录**: 输入邮箱即可（首次自动创建用户）
3. **配置 Liblib 密钥**: 在"密钥管理"页面添加 AccessKey/SecretKey
4. **添加工作流**: 在"工作流管理"页面注册 ComfyUI 工作流
### 2. MCP Client 连接
#### Cursor/其他 MCP Client 配置
在 MCP 设置中添加：
```json
{
"liblib": {
"command": "npx",
"args": [
"@modelcontextprotocol/server-everything"
],
"env": {
"MCP_SERVER_URL": "http://localhost:8080/mcp",
"MCP_AUTH_TOKEN": "your-bearer-token-here"
}
}
}
```
#### 使用 mcp_test_client
```bash
# 测试 MCP 连接
go run mcp_test_client.go -endpoint="http://localhost:8080/mcp" -token="your-bearer-token"
```
### 3. 工作流管理
1. **注册工作流**：
- 提供工作流名称和描述
- 输入 Liblib 工作流 UUID
- 粘贴参数示例 JSON（用于自动解析参数结构）
2. **自动工具生成**：
- 系统自动解析参数结构
- 生成对应的 MCP Tool
- 支持动态参数验证
3. **工具调用**：
- MCP Client 自动发现工具
- 调用时自动使用用户的 Liblib 密钥
- 异步执行，支持状态查询
## 🔧 API 文档
### 认证 API
```bash
# 用户登录
POST /api/v1/auth/login
Content-Type: application/json
{"email": "user@example.com"}
# 返回: {"token": "jwt_token", "user": {...}}
```
### 密钥管理 API
```bash
# 添加密钥
POST /api/v1/credentials
Authorization: Bearer <jwt_token>
Content-Type: application/json
{
"name": "生产环境",
"access_key": "your_access_key",
"secret_key": "your_secret_key"
}
# 获取密钥列表
GET /api/v1/credentials
Authorization: Bearer <jwt_token>
```
### 工作流管理 API
```bash
# 注册工作流
POST /api/v1/workflows
Authorization: Bearer <jwt_token>
Content-Type: application/json
{
"name": "图像生成",
"workflow_uuid": "workflow-uuid-here",
"description": "生成高质量图像",
"params_json": "{\"prompt\": \"示例提示词\"}"
}
# 获取工作流列表
GET /api/v1/workflows
Authorization: Bearer <jwt_token>
```
## 🛡️ 安全性
### 数据加密
- **密钥加密**: 使用 AES-256-GCM 加密存储 Liblib API 密钥
- **传输加密**: 支持 HTTPS 部署
- **Token 安全**: JWT Token 签名验证
### 多租户隔离
- **数据隔离**: 每个用户只能访问自己的资源
- **工具隔离**: MCP 工具基于 Bearer Token 过滤
- **API 隔离**: 接口级别的权限控制
## 📊 监控运维
### 健康检查
```bash
curl http://localhost:8080/health
# 返回: OK (200)
```
### 日志查看
```bash
# Docker 容器日志
docker logs liblib-mcp
# 本地部署日志
tail -f logs/backend.log
```
## 🧪 测试
### 单元测试
```bash
go test ./...
```
### 前端测试
```bash
cd web
npm test
```
### MCP 集成测试
```bash
./scripts/test_mcp_basic.sh
```
## 🤝 贡献指南
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
### 开发规范
- 遵循 [轻量化架构原则](docs/architecture.md)
- 使用标准库优先，最小化依赖
- 保持单端口统一服务架构
- 添加充分的单元测试
## 📄 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
## 🙏 致谢
- [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) - 优秀的 MCP Go 实现
- [Liblib AI](https://www.liblib.art) - ComfyUI 工作流平台
- [GORM](https://gorm.io) - Go ORM 库
## 📞 支持
- 🐛 **问题反馈**: [GitHub Issues](https://github.com/WW-AI-Lab/liblib-mcp-server/issues)
- 💬 **讨论交流**: [GitHub Discussions](https://github.com/WW-AI-Lab/liblib-mcp-server/discussions)
- 📧 **商务合作**: toxingwang@gmail.com
---
<div align="center">
**[🏠 主页](https://github.com/WW-AI-Lab)** • **[📖 文档](docs/)** • **[🚀 部署指南](docs/deploy.md)** • **[🔧 API 文档](docs/api.md)**
</div>
