164 lines
4.0 KiB
Markdown
164 lines
4.0 KiB
Markdown
|
# 铸渊 MCP Server · guanghulab-mcp-server
|
|||
|
|
|
|||
|
|
> 让 WorkBuddy / CodeBuddy 等编程 AI 通过 MCP 协议直接操作仓库，无需每次手动发送 Gitea 令牌。
|
|||
|
|
|
|||
|
|
## 为什么需要这个
|
|||
|
|
|
|||
|
|
| 痛点 | 解决方案 |
|
|||
|
|
|------|---------|
|
|||
|
|
| 每次新对话要手动发令牌 | MCP Server 存储令牌，AI 端只需一个连接密钥 |
|
|||
|
|
| 换号后要重新发令牌 | 重新连接 MCP 即可，密钥不变 |
|
|||
|
|
| 令牌暴露在聊天记录中 | 令牌只在服务器端，聊天中只有 MCP 连接密钥 |
|
|||
|
|
| AI 不认识仓库结构 | MCP 工具自动提供仓库操作能力 |
|
|||
|
|
|
|||
|
|
## 架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
WorkBuddy (编程 AI)
|
|||
|
|
│
|
|||
|
|
│ MCP 协议 (HTTPS + Bearer Token)
|
|||
|
|
▼
|
|||
|
|
Nginx (guanghulab.com/mcp)
|
|||
|
|
│
|
|||
|
|
│ 反向代理
|
|||
|
|
▼
|
|||
|
|
铸渊 MCP Server (127.0.0.1:8083)
|
|||
|
|
│
|
|||
|
|
├── Gitea API ──→ 代码仓库操作
|
|||
|
|
├── Git CLI ────→ 本地仓库同步
|
|||
|
|
├── CVM Script ─→ 服务器开关机
|
|||
|
|
└── Vault API ──→ 密钥管理
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 提供的 MCP 工具
|
|||
|
|
|
|||
|
|
### 仓库操作
|
|||
|
|
| 工具 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `repo_status` | 查看仓库当前状态 |
|
|||
|
|
| `repo_read_file` | 读取文件内容 |
|
|||
|
|
| `repo_write_file` | 写入/更新文件 |
|
|||
|
|
| `repo_delete_file` | 删除文件 |
|
|||
|
|
| `repo_list_files` | 列出目录内容 |
|
|||
|
|
| `repo_search_code` | 搜索代码 |
|
|||
|
|
|
|||
|
|
### Git 操作
|
|||
|
|
| 工具 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `git_branch_list` | 列出所有分支 |
|
|||
|
|
| `git_branch_create` | 创建新分支 |
|
|||
|
|
| `git_pull` | 拉取最新代码 |
|
|||
|
|
| `git_push_local` | 推送本地更改 |
|
|||
|
|
| `git_log` | 查看提交历史 |
|
|||
|
|
|
|||
|
|
### Issue / PR
|
|||
|
|
| 工具 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `issue_list` | 列出 Issue |
|
|||
|
|
| `issue_create` | 创建 Issue |
|
|||
|
|
| `pr_list` | 列出 Pull Request |
|
|||
|
|
| `pr_create` | 创建 Pull Request |
|
|||
|
|
|
|||
|
|
### 工作流 / 服务器
|
|||
|
|
| 工具 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `workflow_list` | 列出工作流运行记录 |
|
|||
|
|
| `workflow_trigger` | 触发工作流 |
|
|||
|
|
| `cvm_power` | CVM 开关机 |
|
|||
|
|
| `server_health` | 服务器健康状态 |
|
|||
|
|
|
|||
|
|
### 密钥 / 大脑
|
|||
|
|
| 工具 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `secrets_list` | 列出 Forgejo Secrets |
|
|||
|
|
| `vault_status` | Vault 状态 |
|
|||
|
|
| `brain_status` | 铸渊大脑状态 |
|
|||
|
|
| `brain_update_temporal` | 更新时间核心 |
|
|||
|
|
|
|||
|
|
## 部署
|
|||
|
|
|
|||
|
|
### 1. 安装依赖
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd /data/guanghulab/repo/server/mcp-server
|
|||
|
|
npm install --production
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 配置 Gitea 令牌
|
|||
|
|
|
|||
|
|
编辑 `ecosystem.config.js`，填入 GITEA_TOKEN：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 从 Vault 获取令牌（如果已存入 Vault）
|
|||
|
|
curl http://127.0.0.1:8080/internal/fetch/ZY_REPO_TOKEN
|
|||
|
|
|
|||
|
|
# 或直接在 ecosystem.config.js 的 env.GITEA_TOKEN 中设置
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. Nginx 配置
|
|||
|
|
|
|||
|
|
在 Nginx 的 server 块中添加：
|
|||
|
|
|
|||
|
|
```nginx
|
|||
|
|
# MCP Server 端点
|
|||
|
|
location /mcp {
|
|||
|
|
proxy_pass http://127.0.0.1:8083;
|
|||
|
|
proxy_http_version 1.1;
|
|||
|
|
proxy_set_header Host $host;
|
|||
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|||
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|||
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|||
|
|
|
|||
|
|
# SSE 支持
|
|||
|
|
proxy_set_header Connection '';
|
|||
|
|
proxy_buffering off;
|
|||
|
|
proxy_cache off;
|
|||
|
|
proxy_read_timeout 86400s;
|
|||
|
|
proxy_send_timeout 86400s;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 启动服务
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pm2 start ecosystem.config.js
|
|||
|
|
pm2 save
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5. 获取连接密钥
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cat /data/guanghulab/mcp-server/.access-key
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## WorkBuddy 连接配置
|
|||
|
|
|
|||
|
|
在 WorkBuddy 的 MCP 工具配置中添加：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"mcpServers": {
|
|||
|
|
"guanghulab": {
|
|||
|
|
"url": "https://guanghulab.com/mcp",
|
|||
|
|
"headers": {
|
|||
|
|
"Authorization": "Bearer <你的访问密钥>"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
换号时，只需在新账号中重新添加这个 MCP 连接配置即可。
|
|||
|
|
|
|||
|
|
## 安全
|
|||
|
|
|
|||
|
|
- **Gitea 令牌**：仅存储在服务器端，永不暴露给客户端
|
|||
|
|
- **MCP 访问密钥**：AES-256 级别的随机密钥，存储在 `/data/guanghulab/mcp-server/.access-key` (chmod 600)
|
|||
|
|
- **Nginx 层**：HTTPS 加密传输
|
|||
|
|
- **本机绑定**：MCP Server 只监听 127.0.0.1:8083，通过 Nginx 代理暴露
|
|||
|
|
- **无状态**：MCP Server 不存储 AI 对话内容
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
*铸渊 · ICE-GL-ZY001 · TCS-0002∞ · 国作登字-2026-A-00037559*
|