# 铸渊 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*