# repo-mcp-server · 铸渊代码仓库MCP工具 · 霜砚的手 · 2026-05-14部署

```jsx
HLDP://tools/repo-mcp-server · 2026-05-14
├── what: 铸渊开发的MCP服务器 · 让霜砚能直接读写代码仓库
├── 定位: 霜砚的「手」· 从Notion伸进代码世界
├── 部署: 光湖服务器 · pm2进程 · nginx反代
└── 状态: ✅ 全链路闭环 · 铸渊中转已验证 · 2026-05-14
```

---

## 📡 服务信息

| 项目 | 值 |
| --- | --- |
| 公网地址 | `https://guanghulab.com/repo-mcp` |
| 内部端口 | 3903 |
| 部署路径 | `/opt/zhuyuan/repo-mcp-server` |
| pm2进程名 | `repo-mcp-server` |
| Gitea仓库 | `http://127.0.0.1:3001/bingshuo/guanghulab` |
| 认证方式 | Bearer Token ✅ `382b0ad8288c8283636c86c0ad5172bd`（本地 + 仓库 `.workbuddy/mcp.json`） |
| 健康检查 | `https://guanghulab.com/repo-mcp/health` → ✅ |
| MCP端点 | `https://guanghulab.com/repo-mcp/mcp` → ✅ |

---

## 🔧 13个工具清单

| 工具名 | 功能 | 说明 |
| --- | --- | --- |
| `repo_read` | 读取文件 | 读取仓库中指定路径的文件内容 |
| `repo_write` | 写入文件 | 创建或覆盖仓库中的文件 |
| `repo_delete` | 删除文件 | 删除仓库中指定文件 |
| `repo_list` | 列出目录 | 列出指定路径下的文件和文件夹 |
| `repo_search` | 搜索代码 | 在仓库中搜索关键词 |
| `repo_file_tree` | 文件树 | 获取仓库完整目录树结构 |
| `repo_branch_list` | 列出分支 | 查看所有分支 |
| `repo_branch_create` | 创建分支 | 从指定分支创建新分支 |
| `repo_pr_create` | 创建PR | 创建Pull Request |
| `repo_pr_list` | 列出PR | 查看PR列表 |
| `repo_workflow_run` | 运行工作流 | 触发CI/CD工作流 |
| `repo_status` | 仓库状态 | 查看仓库基本信息和状态 |
| `repo_log` | 提交日志 | 查看最近的commit记录 |

---

## 🌿 分支体系

```jsx
main           ← 稳定主干 · 只接受PR合并 · 不直接推送
forge/*        ← 铸渊专用分支 · 铸渊在GitHub/Forgejo端开发用
notion/*       ← 人格体专用分支 · 霜砚等人格体通过MCP操作用
  └── notion/shuangyan  ← 默认分支 · 霜砚的工作分支
```

**工作流**：

1. 霜砚在 `notion/shuangyan` 分支上读写代码
2. 完成后创建PR → 合并到 `main`
3. 铸渊在 `forge/*` 分支上开发 → 同样PR合并到 `main`
4. `main` 分支始终保持稳定可用

---

## ✅ 当前方案 · 铸渊中转（2026-05-14确认）

```jsx
结论 = 霜砚暂时不直接长手 · 铸渊当翻译官 · 双向搬运
原因 = Custom Agent + MCP 需要 Business/Enterprise + Notion Credits · 目前不划算
```

**运行方式**：

1. 霜砚在Notion里写需求/代码 → 留在Notion页面里
2. 铸渊通过 Notion MCP 读取霜砚写的内容
3. 铸渊用 repo-mcp-server 把内容写到代码仓库
4. 反过来也一样：铸渊读仓库 → 写回Notion给霜砚看

**本质**：不是「霜砚自己有手」，是「铸渊帮霜砚动手」。效果一样——Notion和代码仓库打通了，不花钱。

**未来升级路径**：

- Notion Workers稳定后 → 可能不需要Custom Agent就能调外部服务
- 或升级Business计划后 → 霜砚直接挂MCP · 自己长手

---

## ✅ 完成清单（2026-05-14 凌晨全部完成）

- [x]  **repo-mcp-server 代码** — 13个工具 · 写入 `mcp-servers/repo-mcp-server/`
- [x]  **分支策略** — `forge/*` 铸渊 / `notion/*` 霜砚
- [x]  **CVM 部署** — PM2 端口 3903 · 开机自启
- [x]  **Nginx 反代** — `/repo-mcp` → `127.0.0.1:3903`
- [x]  **Bearer 密钥** — 已配本地 + 仓库 `.workbuddy/mcp.json`
- [x]  **notion/shuangyan 分支** — 已创建 · 测试文件已写入
- [x]  **铸渊中转全链路测试** — Notion MCP → 铸渊 → repo-mcp-server → 仓库 ✅
- [x]  **大脑文件更新** — self-cognition / thinking-logic / progress ✅
- [x]  ~~Notion端直连MCP~~ — **暂缓** · 需Business计划 · 当前走铸渊中转

---

## 🔑 铸渊恢复两步走

1. 打开仓库 → WorkBuddy 自动读 `.workbuddy/mcp.json` → 连上两个 MCP
2. 叫铸渊一声 → 读完记忆文件恢复上下文 → 继续干活

---

## 💻 冰朔本地开发环境（Mac mini M4 · 2024）

```jsx
硬件:
  机型: Mac mini 2024
  芯片: Apple M4
  内存: 16GB
  系统: macOS Tahoe 26.3

开发语言:
  Python:  3.9.6 ✅
  Node.js: v24.13.1 ✅
  npm:     11.8.0 ✅

版本管理:
  Git: 2.50.1 (Apple Git-155) ✅

AI编程工具:
  WorkBuddy  ✅（连着Notion MCP + repo-mcp-server）
  Codex      ✅（OpenAI）
  CodeBuddy  ✅（腾讯）

本地AI:
  Ollama ✅（可跑本地模型）

包管理:
  Homebrew 5.1.11 ✅（国内镜像源安装 · 2026-05-14）

未装:
  VS Code  ❌（已有三个编辑器 · 不需要）
```

**开发流程**：

1. 本地写代码（WorkBuddy/Codex/CodeBuddy）→ 不花钱
2. `git push` 到 Forgejo 仓库 → 不花钱
3. 需要GPU/需要上线时才开服务器 → 只为「跑」付费，不为「写」付费

---

## 🧭 Notion端配置步骤（备用 · 等升级Business后用）

1. **Settings → Notion AI → AI connectors → Enable Custom MCP servers**
2. 在自定义Agent设置 → **Tools & Access → Add connection → Custom MCP server**
3. 填写：
    - URL: `https://guanghulab.com/repo-mcp`
    - Display Name: `repo-mcp-server`
    - Authentication: Bearer Token → 填铸渊给的 REPO_MCP_SECRET
4. 保存 → 测试连接

---

## 💡 架构哲学

```jsx
冰朔的语言意图 = 「霜砚应该有手 · 能直接碰代码」
架构哲学 = 能力延伸有两条路：
  路径A = 霜砚直接挂MCP（需要钱 · 暂缓）
  路径B = 铸渊中转（免费 · 当前方案）
  本质相同 = 语言层和执行层之间打通了 · 只是经不经过铸渊的区别
现实对应 = repo-mcp-server已部署 · 铸渊同时连着Notion MCP和代码仓库 · 双向桥梁
```

> 三位一体的现实映射：冰朔说话 → 霜砚设计 → 铸渊执行。
铸渊中转不是降级方案，是三位一体本来的结构。
>