docs(blueprint): 登记 mcp-single-server concept 模块——组级挂载收敛为单一全局服务器
All checks were successful
Push & PR Check / check (push) Successful in 48s

动机:MCP 客户端配置成本随产品组数线性增长(12 组 × 28 工具),
与飞轮'项目越多越强'方向相反;实测组级挂载无隔离价值(任意组
服务器可操作任意项目)。单一服务器后 liangjing.json 只需
project_id,group_id 同步问题从根上消失。L 级,待 /architect。
This commit is contained in:
lanrtop 2026-07-06 19:04:04 +09:00
parent bce9a0a37c
commit 138a06aa17
2 changed files with 44 additions and 0 deletions

View File

@ -416,6 +416,14 @@ modules:
note: "项目默认A+可选B& 产品组默认F+可选G四视图多对一关系用户可新建"
position: [4000, 0]
- id: mcp-single-server
name: MCP 单一服务器化
area: backend
status: concept
progress: 0
note: "组级挂载 lian-jing-{group_id} 收敛为单一全局 lian-jing授权/注册一次项目数增长零客户端配置liangjing.json 只需 project_id。L 级,先 /architect 再拆卡"
position: [1750, 500]
edges:
# 前端依赖
- from: workspace-mgmt
@ -662,3 +670,11 @@ edges:
- from: gitea-integration
to: github-decommission
type: related
# MCP 单一服务器化
- from: mcp-server
to: mcp-single-server
type: dependency
- from: mcp-config-inject
to: mcp-single-server
type: dependency

View File

@ -0,0 +1,28 @@
# MCP 单一服务器化
将组级挂载的 `lian-jing-{group_id}`(每产品组一个 MCP 服务器)收敛为单一全局 `lian-jing` 服务器。
## 为什么
- **摩擦随项目数复利增长,与飞轮方向相反**:当前每新增一个产品组 = 多一次 `claude mcp add` + 多一个授权单元 + 每个会话多一份重复工具清单(现状 12 个组 × 28 工具 ≈ 300+ 工具注册)。炼境的目标是"管理项目越多 → agent 辅助越强",客户端配置成本必须是 O(1)。
- **组级挂载没有真正的隔离价值**2026-07-06 实测,任意组的服务器可对任意项目执行 `inject_mcp`(工具全部显式传 `project_id`),组这一层只是命名空间,不是权限边界。
- **消除 group_id 身份卡的存在必要**:单一服务器后 `liangjing.json` 只需 `project_id`group_id 缺失/过期/移组同步这一整类问题从根上消失(而非修复)。
## 改造范围(侦察结论,待 /architect 细化)
- `mcp_server.rs``/mcp/group/{group_id}` 路由 → 新增全局 `/mcp` 路由;旧路由保留一段过渡期
- `mcp_tools.rs`:工具已全部显式传 `project_id`,改动小;`list_group_projects` 等组上下文工具改为显式传参或从 project 反查 `project_group_map`
- `mcp_inject.rs`settings.json 注入条目 + `claude mcp add` 收敛为单个 `lian-jing``liangjing.json` 去掉 group_id 依赖
- **存量迁移**:清理 ~/.claude.json 中 12 个旧 `lian-jing-*` 注册;已注入项目 settings.json 批量刷新(复用 `reinject_all_mcp` 机制)
- 接入包模板 / `docs/ai-context/git-workflow.md``lian-jing-{group_id}` 引用同步改
- 用户全局 `~/.claude/CLAUDE.md` 炼境按钮规则段(引用 `lian-jing-{group_id}`)需同步
## 风险
- 迁移期新旧服务器并存agent 可能困惑——需设计干净的切换顺序(先加新、批量迁移、后删旧)
- webhook 回调路径是否含 group_id 待核实(`mcp_webhook.rs`
- 状态conceptL 级——禁止直接写代码,先 `/architect` 输出设计文档,用户确认后 `/splitter` 拆 S/M 卡
## 任务卡
(待 /architect 设计确认后由 /splitter 生成)