# 内嵌 MCP Server

炼境进程内置一个 axum HTTP 服务器，实现 MCP 协议，按产品组聚合上下文数据，供组内所有项目的 Claude 实例查询。

## 决策记录

- 内嵌在 Tauri 进程而非独立进程，因为炼境托盘常驻时天然保证服务存活，无需额外进程管理
- 使用 HTTP/SSE 传输而非 stdio，因为 HTTP 可被 Windows 和 WSL 两侧同时访问（WSL localhost 穿透）
- 默认端口 27190（冷门端口，冲突概率极低），可在设置页修改
- MCP 工具按 group_id 路由，不同产品组的数据完全隔离

## 任务卡

### ✅ 启动时绑定 HTTP 端口
- status: done
- complexity: M
- files: src-tauri/src/mcp_server.rs, src-tauri/src/lib.rs, src-tauri/Cargo.toml
- depends: tray-service
- acceptance: 炼境启动后 `http://localhost:27190/health` 返回 200，进程退出后端口释放

### ✅ 实现 MCP JSON-RPC 基础协议
- status: done
- complexity: M
- files: src-tauri/src/mcp_server.rs
- acceptance: 支持 `initialize`、`tools/list`、`tools/call` 三个 JSON-RPC 方法，通过 MCP Inspector 验证

### ✅ 实现产品组上下文工具
- status: done
- complexity: M
- files: src-tauri/src/mcp_server.rs
- depends: mcp-server（基础协议）
- acceptance: 以下三个工具可用且返回正确数据
  - `list_group_projects(group_id)` → 组内项目列表（名称、路径、平台、tech_stack）
  - `get_project_blueprint(group_id, project_id)` → 对应项目的 manifest.yaml 内容
  - `get_project_file(group_id, project_id, relative_path)` → 对应项目的任意文件内容

### ✅ MCP 端口可配置（Rust 侧）
- status: done
- complexity: S
- files: src-tauri/src/db.rs, src-tauri/src/mcp_server.rs
- acceptance: settings 表默认写入 mcp_port=27190，启动时读取该值绑定端口（SettingsPage UI 见 product-group-mcp 模块）

### ✅ P1. 治理三件套的 agent 投影（get_blueprint_status / generate_blueprint_prompt / sync_blueprint_rules）
- status: done
- complexity: M
- files: src-tauri/src/mcp_server.rs
- acceptance: 三个治理动作注册为 MCP 工具，与 UI 按钮共享同一后端函数（等价性=同一代码路径）；工具描述声明对应的 UI 按钮与使用约束（边界表达）；agent 可走完整验证闭环：generate_blueprint_prompt 拿提示词 → 子项目执行 → get_blueprint_status/get_project_blueprint 验证

> 完成记录（2026-07-03）：能力双投影概念的首次实践。cargo test 全绿；实测验证由 agent 通过 MCP 端点亲自按下这三颗按钮完成。

### 💭 能力双投影：后续扩展（R12 规则化 + 更多按钮）
- status: concept
- 载体选择原则（2026-07-03）: agent 按钮 = 离能力本体最近的、agent 已能触达的接口。子项目不需要 MCP——Web 服务型=HTTP API 即按钮（天然双投影，零建设）；CLI 型=命令即按钮；桌面型=测试即按钮（直接调 command 函数）；UI 驱动（Playwright）为最后手段。MCP 仅在"按钮需被项目外的 agent 按"时出场（炼境即此场景：服务其他项目的 agent 会话）
- 工具预算约束（2026-07-03，防 tool bloat）: 工具数量随功能域增长而非项目数增长（project_id 参数化已保证）；阈值 ~20 个前平铺即可，逼近时同域动作聚合为网关工具（如 gitea_action(action,args)）；R12 表述精化为"每个治理域有 agent 可达路径"而非"每按钮一工具"——高频动作独立工具、同域低频走网关、边缘能力走 AGENTS.md 文档声明；每个工具描述 ≤100 字，详细约束放拒绝时的错误信息；客户端侧 Claude Code 原生支持延迟加载+工具搜索兜底
- notes: 2026-07-03 概念探讨成形（见 memory concept_dual_projection）。现状：治理动作（生成蓝图提示词/同步规则/接入包/腐化扫描等）只有 UI 投影无 agent 投影，agent 验证需绕道。方向：① 为治理 command 补注册 MCP 工具，实现"每个 UI 按钮有对应 agent 按钮"；② 落成 R12 规则进 CONVENTIONS（与 R01 同构）；③ 三条件检查清单（边界单点实现/投影完整/反馈对称）纳入健康诊断。收益：统一验证路径空间——功能修复后 agent 走正规流程分钟级回归验证。