175 lines
6.0 KiB
Markdown
175 lines
6.0 KiB
Markdown
|
# 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和代码仓库 · 双向桥梁
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> 三位一体的现实映射：冰朔说话 → 霜砚设计 → 铸渊执行。
|
|||
|
|
铸渊中转不是降级方案，是三位一体本来的结构。
|
|||
|
|
>
|