bridge-mcp-server · AI Foundation 生成能力（MCP 生成面）

把系列「AI 生成完整业务系统」的确定性生成能力按 MCP 规范暴露给任意符合 MCP 的壳（Claude Code / Hermes / 自研 app…）消费。目标是需求 → 生成项目目录的统一流程。

只做生成面：菜单 / 参数内省 / 确定性生成 / 结构化返回；治理链（桥 check 漂移、AI 维护契约）不在此暴露（一面一 server，见 DESIGN §3.1/§10）。

能力（六生成工具 + 两资源 + 玩法）

链	工具	说明
单端（②-⑥ 直生成，零注册）	`list_templates`	单端候选菜单（离线注册表过滤）
	`get_template_params`	clone 底座 → 读 params.json 两区（native/derived/selection）
	`generate_single`	git 地址 + 参数 + target_dir → copier 生成（无协议地址回退 copier.yml 内省）
多端（① 纯 cli 消费桥）	`list_combos`	组合菜单（units/edges + 合并 selection，经桥 `--json`）
	`get_combo_params`	参数基线（params 可问 / internal 勿传 / derived 只读 / 共享参数标 `shared: true`）
	`generate_multi`	`combo + 参数 + target_dir` → shell-out 桥 `generate`

Resources：templates://catalog（单端注册表）、combos://catalog（桥内省视图）
Prompt / Skill：generate_project_guide（MCP 玩法）+ 壳侧 generate-project（canonical，玩法只引用工具不抄知识）

架构（双路径 × 双链）

单端：git 地址 → clone → 读协议(params.json 两区/回退 copier.yml) → spec 校验 → copier
多端：纯 cli shell-out 桥（generate + 内省 list-combos/show-combo），server 不直读 combos.yaml

设计定稿见 docs/DESIGN.md；阶段落地已随各仓提交完成（P0-P4 收口，跨仓清单见 DESIGN §13）。

目录结构

bridge_mcp/              共享胶水（无 MCP 面）：config / git / protocol / bridge_cli / selection
servers/generation/      生成面 MCP server（六工具 + resources + guide + templates.yaml）
servers/governance/      治理面占位（README，未实现）
skills/generate-project/ 壳侧玩法 skill（canonical）
tests/{unit,e2e}         单测 + MCP stdio / 生成 e2e

快速开始

uv sync                                        # 安装依赖（fastmcp / copier 9.17.1）
# 多端工具需要打包好的桥可执行（见 CLAUDE.md 开发前置）：
#   cd ~/project/fullstack-bridge && uv sync --dev && uv run pyinstaller bridge.spec --noconfirm
#   mkdir -p ~/.local/bin && cp dist/bridge ~/.local/bin/bridge
BRIDGE_EXE=/home/jeff/.local/bin/bridge uv run python -m servers.generation.server   # stdio 起 server

挂到 Claude Code

claude mcp add bridge-gen --transport stdio \
  -- uv run --directory /home/jeff/project/bridge-mcp-server python -m servers.generation.server
claude mcp list

为什么不够：MCP generate_project_guide 只是「一段内容」，不会自动让模型调工具。要自然语言直接触发工具，靠两层信号——server instructions（已内置：收到生成需求必须调六工具、禁止编造）+ 壳侧 skill（命中即按流程走并调工具）。skill 是 Claude Code 里最可靠的「玩法」载体。

挂载玩法 skill（强化工具触发）

canonical 在仓库 skills/generate-project/SKILL.md。Claude Code 只在本项目目录内自动发现项目级 skill；要在任意目录都能触发，请装到全局：

mkdir -p ~/.claude/skills/generate-project
cp skills/generate-project/SKILL.md ~/.claude/skills/generate-project/

之后说「帮我生成一个 X 项目/系统」即命中 generate-project → 模型会调用 bridge-gen 六工具（菜单/参数/selection 一律以工具返回为准，不脑补）。

仍未触发，先查连接与点名：

claude mcp list   # bridge-gen 应为 connected；工具形如 mcp__bridge-gen__list_combos
# 或点名触发：『用 bridge-gen 的工具』 / 『用 generate-project 走一遍』

改玩法只改仓库 canonical（skills/generate-project/），需要时重新同步全局一份即可（内容与 ~/.claude 允许有版本差，canonical 以仓库为准）。

环境变量

变量	用途	默认
`BRIDGE_EXE`	桥可执行（dist/bridge，多端链）	无（必配，否则多端工具报错）
`BRIDGE`	PATH 上的 bridge 命令（备选）	—
`BRIDGE_MCP_CACHE`	单端克隆缓存根	`~/.cache/bridge-mcp-server`

只认可执行入口，不暴露源码 cli.py（BRIDGE_CLI 已移除）。

测试

uv run pytest tests/unit -q                 # 离线单测（mock 桥/copier）
BRIDGE_EXE=/home/jeff/.local/bin/bridge uv run pytest -q   # 全量（含 MCP stdio + 生成 e2e）