guanghulab/server/mcp-server/README.md

铸渊 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. 安装依赖

cd /data/guanghulab/repo/server/mcp-server
npm install --production

2. 配置 Gitea 令牌

编辑 ecosystem.config.js，填入 GITEA_TOKEN：

# 从 Vault 获取令牌（如果已存入 Vault）
curl http://127.0.0.1:8080/internal/fetch/ZY_REPO_TOKEN

# 或直接在 ecosystem.config.js 的 env.GITEA_TOKEN 中设置

3. Nginx 配置

在 Nginx 的 server 块中添加：

# 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. 启动服务

pm2 start ecosystem.config.js
pm2 save

5. 获取连接密钥

cat /data/guanghulab/mcp-server/.access-key

WorkBuddy 连接配置

在 WorkBuddy 的 MCP 工具配置中添加：

{
  "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