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*
|