1. 项目定位与目标

cpp-quick-start-mcp 是一个基于 Model Context Protocol (MCP) 的服务器，专门面向 C++ 项目的脚手架（scaffolding）与现代化改造场景。它通过 npm 分发，当前最新版本为 v0.7.0，安装后提供 cpp-quick-start-mcp 命令，支持默认的 stdio 传输和可选的 HTTP/SSE 模式（默认监听 0.0.0.0:3000） 资料来源：README.md。

其核心价值在于将分散在 C++ 生态中的最佳实践——构建系统（CMake/Make/Meson/Bazel）、包管理（Conan/vcpkg）、测试框架（doctest 等）、静态分析（clang-tidy/cppcheck）、CI/CD（GitHub Actions/GitLab CI）、目录布局（Pitchfork Layout）——封装为统一的 MCP 工具、资源与提示词，让 AI 智能体通过对话方式即可生成符合现代 C++ 工程规范的项目结构，避免"凭记忆"生成不一致或过时的样板代码 资料来源：README.md。

2. 整体架构

服务器采用"分层元技能"（layered meta-skill）设计：底层是大量按目录组织的 SKILL.md 技能库，顶层由一个名为 go 的元提示词统一驱动整个生成流程 资料来源：data/meta-quickstart/SKILL.md。

flowchart TB
    U[用户 / AI 智能体] --> P[MCP 提示词<br/>go]
    P --> M[meta-quickstart 元技能<br/>Mode A 新项目 / Mode B 既有项目]
    M --> R[资源发现<br/>list-resources]
    M --> S[技能库<br/>data/scaffold-*/SKILL.md]
    S --> BS[构建系统<br/>CMake / Make / Meson / Bazel]
    S --> QA[质量工具<br/>clang-tidy / cppcheck]
    S --> CI[CI/CD<br/>GitHub Actions / GitLab CI]
    S --> PKG[包管理 / 测试 / 布局]
    M --> OUT[项目产物<br/>AGENTS.md + skills/<br/>+ 完整脚手架文件]

3. 核心组件

3.1 提示词（Prompt）

go 是唯一的元提示词，作为 Level 2 "Meta-Skill" 存在，其职责不是直接写 C++ 代码，而是根据用户偏好生成针对其工具链定制化的具体技能 资料来源：data/meta-quickstart/SKILL.md。它强制执行"预检扫描 → 模式 A/B 选择 → 多轮分类访谈 → 资源发现 → 文件生成"的工作流。

3.2 技能（Skills）

所有技能均以 SKILL.md 文件形式存放在 data/scaffold-*/ 下，每个文件都带有 YAML frontmatter（name + description），description 字段必须说明技能做什么以及何时使用，供其他智能体判断是否加载 资料来源：data/scaffold-workspace-skills/SKILL.md。技能按职能可分为：

例如 scaffold-cmake 强制要求使用 Modern CMake：cmake_minimum_required(VERSION 3.20)、按目标拆分 CMakeLists.txt、通过 target_compile_features 而非全局变量设置 C++ 标准 资料来源：data/scaffold-cmake/SKILL.md。

3.3 资源（Resources）

技能同时作为 mcp://scaffold/* 资源暴露，智能体在生成文件前可按需读取对应指令，避免幻觉 资料来源：README.md。

3.4 持久化产物

完成生成后，项目根会写入 AGENTS.md（智能体协作指南与 Workspace Skills 索引表） 资料来源：data/scaffold-agents/SKILL.md，并随项目携带永久性的 skills/<name>/SKILL.md，供后续智能体在每次任务开始时优先读取。基础配置文件 .gitignore、.gitattributes、.clangd 也会一并落地 资料来源：data/scaffold-base-configs/SKILL.md。

4. 工作流与约束

meta-quickstart 在启动时强制扫描当前目录，以判定是"空目录（Mode A）"还是"既有项目（Mode B）" 资料来源：data/meta-quickstart/SKILL.md。Mode A 通过多选访谈覆盖构建系统、标准、布局、测试等十余个分类；Mode B 则跳过全量访谈，进入"添加新组件 / 现代化改造"二选一分支。两条路径最终都会调用 list-resources 工具拉取全部可用技能，再向用户主动推荐相关项。

在产出质量上，工作区技能模板要求所有命令必须以可直接复制粘贴的 fenced 代码块呈现，禁止出现读者需自行替换的占位符；任务类技能必须包含 ## Commands 与 ## Expected Output 两节 资料来源：data/scaffold-workspace-skills/SKILL.md。通用最佳实践则由独立的 best-practices-* 系列兜底，例如 Meson 项目应保持根 meson.build 整洁并通过 add_project_arguments 注入警告 资料来源：data/best-practices-meson/SKILL.md；代码评审强调单一职责、强抽象、依赖单向流动等原则 资料来源：data/best-practices-code-review/SKILL.md。

See Also

• scaffold-cmake — CMake 脚手架细节
• scaffold-pitchfork-layout — Pitchfork 目录布局规范
• Workspace Skills 与 AGENTS.md — 持久化智能体协作指南

cpp-quick-start-mcp 是一个面向 C++ 项目的 Model Context Protocol (MCP) 服务器。它通过标准 MCP 接口向 AI 智能体（例如 Claude Code、Cursor 等）暴露一组「脚手架技能（Scaffolding Skills）」与动态资源，从而引导智能体为新项目或现有项目生成符合现代 C++ 规范的目录结构、构建脚本、CI 配置以及代理协作规范 资料来源：README.md:1-40。

本页聚焦于该服务器的安装与客户端集成两条主线，覆盖 NPM 全局安装、本地源码构建、stdio 与 HTTP/SSE 两种运行模式，以及将服务器接入 MCP 客户端所需的基本配置与调用约定。

安装方式

服务器以 Node.js 包形式分发，因此安装前需要本地具备 Node.js 与 npm 运行时。README 推荐两条等价路径 资料来源：README.md:42-67：

方式一：从 NPM 注册表安装（推荐）

npm install -g @m-velikov/cpp-quick-start-mcp

安装完成后，cpp-quick-start-mcp 命令将进入全局 PATH，可被任意 MCP 客户端调用。该方式最稳定，适合普通使用者。

方式二：从源码构建并本地安装

适合希望修改技能内容、参与贡献或在 CI 中固定版本的场景：

# 1. 克隆并安装依赖
git clone https://github.com/m-velikov/cpp-quick-start-mcp.git
cd cpp-quick-start-mcp
npm install

# 2. 构建产物
npm run build

# 3. 从本地目录进行全局安装
npm install -g .

不论使用哪种方式，安装成功后的可执行入口名称均为 cpp-quick-start-mcp 资料来源：README.md:60-66。

服务器启动模式

服务器默认通过 stdio 与 MCP 客户端通信，因此大部分支持 MCP 协议的客户端无需任何额外参数即可直接调用。若需要把服务器作为独立 HTTP 服务暴露，则可显式指定端口与绑定地址 资料来源：README.md:70-78。

HTTP/SSE 模式默认监听 0.0.0.0:3000，即绑定全部网卡接口，可通过局域网访问；若部署到云服务器，请确保防火墙/安全组放行该端口。

flowchart LR
    A[用户] --> B{MCP 客户端}
    B -->|stdio| C[cpp-quick-start-mcp]
    B -->|HTTP/SSE| D[cpp-quick-start-mcp --port 3000]
    C --> E[(Scaffolding Skills)]
    D --> E
    E --> F[新项目脚手架<br/>build/CMakeLists.txt 等]
    E --> G[现有项目改造<br/>AGENTS.md 等]

客户端集成

在 MCP 客户端中注册服务器

对于支持 MCP 的客户端（Claude Code、Cursor、Cline 等），典型配置是在客户端配置文件中声明一个 stdio 类型的 MCP server，命令指向 cpp-quick-start-mcp。例如 Claude Code 的 mcp_servers.json 可写为：

{
  "mcpServers": {
    "cpp-quick-start": {
      "command": "cpp-quick-start-mcp",
      "args": []
    }
  }
}

若采用 HTTP/SSE 部署，则把 command/args 替换为 url: http://<host>:3000 即可。客户端会通过 MCP 协议列出该服务器暴露的工具（go、list-resources 等）与资源（mcp://scaffold/*）。

可用资源与触发入口

服务器启动后会向客户端暴露两类核心能力：

1. 入口工具：go 工具启动完整的「C++ 栈访谈 → 计划 → 脚手架生成」流程，会先扫描当前目录、判断是新项目（Mode A）还是现有项目（Mode B），再读取对应的脚手架技能 资料来源：data/meta-quickstart/SKILL.md:13-31。
2. 动态资源：形如 mcp://scaffold/cmake、mcp://scaffold/github-actions、mcp://scaffold/pitchfork-layout 等 URI，承载具体的「How-to」级指令，供智能体在生成对应产物时按需读取 资料来源：README.md:30-40。

在生成的项目中继续使用

服务器在生成项目时，会在项目根目录写入 AGENTS.md 与 skills/ 目录，使后续的智能体协作具备「自我描述」能力 资料来源：data/scaffold-agents/SKILL.md:8-30。每个工作区技能必须遵守统一的目录布局、YAML frontmatter 与「Commands + Expected Output」结构 资料来源：data/scaffold-workspace-skills/SKILL.md:1-30。同时，Pitchfork 目录布局技能要求将 include/<target>/、src/<target>/、build/ 等标准目录作为脚手架的一部分 资料来源：data/scaffold-pitchfork-layout/SKILL.md:5-22。

常见失败模式与排查

• cpp-quick-start-mcp: command not found：通常意味着全局 npm bin 目录不在 PATH 中。可使用 npm config get prefix 找到全局 bin 路径并加入 PATH，或改用 npx @m-velikov/cpp-quick-start-mcp 直接运行。
• HTTP/SSE 模式端口被占用：更换端口，例如 cpp-quick-start-mcp --port 3100；同时确认服务器是否真的监听了 0.0.0.0 而非 127.0.0.1 资料来源：README.md:72-78。
• **客户端看不到 mcp://scaffold/* 资源**：MCP 客户端必须支持 resources 能力；若不支持，请改用 stdio + 支持 tools 的客户端调用 go 工具。
• 生成的项目缺少 AGENTS.md 或 skills/：检查 go 工具执行时是否处于空目录或已被识别的项目根目录；元技能在开始前会扫描目录内容 资料来源：data/meta-quickstart/SKILL.md:13-20。

See Also

• Architecture & Skills Overview
• Scaffolding Workflow (Mode A & Mode B)
• Configuration & Resources

概述与目标

Scaffolding Skills Knowledge Base 是 cpp-quick-start-mcp 服务器内置的知识资源库，通过 mcp://scaffold/* URI 暴露给 AI Agent。每一个技能（Skill）是一份结构化的 Markdown 指令，告诉 Agent 如何为 C++ 项目生成特定领域（如构建系统、依赖管理、CI、静态分析、目录布局等）的样板文件。

元技能（meta-quickstart，名为 go）负责调度整个知识库：根据用户选择拉取并组装对应的子技能，生成统一的项目脚手架。资料来源：data/meta-quickstart/SKILL.md。

flowchart TD
    A[Agent 触发 meta-quickstart / go] --> B{扫描当前目录}
    B -->|空目录| C[Mode A: 12 项偏好访谈]
    B -->|已有项目| D[Mode B: 增补或现代化]
    C --> E[list-resources 发现 mcp://scaffold/*]
    D --> E
    E --> F[read-resource 拉取子技能]
    F --> G[生成项目根文件 + skills/*]
    G --> H[输出 AGENTS.md 与永久技能]

元技能与编排流程

meta-quickstart/SKILL.md 明确规定了三步流程：项目扫描、Mode A/B 访谈、资源发现与主动建议。Agent 必须先列出现有目录，再决定走「新建项目」还是「改造现有项目」分支。资料来源：data/meta-quickstart/SKILL.md。

Mode A 强制要求覆盖 12 个类别（构建系统、测试框架、CI 提供方、包管理器、目录布局、代码质量、平台目标等），并通过多选/自由输入工具逐批提问。资料来源：data/meta-quickstart/SKILL.md。

在资源发现阶段，Agent 必须调用 list-resources 列出全部 mcp://scaffold/* 资源，再做差距分析，主动建议用户采纳尚未要求但有价值的技能（如 scaffold-cppcheck、scaffold-code-hygiene、scaffold-github-actions）。资料来源：data/meta-quickstart/SKILL.md。

技能分类与覆盖范围

知识库按职责划分为多个子技能。下表汇总了当前仓库内可见的子技能及其对应文件：

例如，CMake 技能要求使用 target_compile_features(<target> PUBLIC cxx_std_20) 强制 C++ 标准，并明确禁止「单体式」顶层 CMakeLists.txt，必须按目标拆分文件。资料来源：data/scaffold-cmake/SKILL.md。CMake Presets 技能则规定使用 Ninja 作为默认生成器，并通过隐藏基预设统一 CMAKE_EXPORT_COMPILE_COMMANDS。资料来源：data/scaffold-cmake-presets/SKILL.md。

Make 技能特别强调：GNU Make 不支持 ** 通配符，必须使用 find 命令发现源文件；同时强制非递归设计，通过 include .mk 文件来组织多子目录。资料来源：data/scaffold-make/SKILL.md。

vcpkg 技能要求生成合法 JSON（包含 $schema、name、version、dependencies）的 vcpkg.json，并在需要基线锁定时附 vcpkg-configuration.json。资料来源：data/scaffold-vcpkg/SKILL.md。

技能文档的结构与消费方式

所有技能（scaffold-* 与 best-practices-*）均遵守统一的 Markdown 模板：YAML frontmatter 声明 name 与 description（Use when ...），正文则用 ## Instructions / ## Requirements 等小节给出可直接复制的代码块。资料来源：data/scaffold-workspace-skills/SKILL.md。

Meta 技能会强制要求命令必须以 fenced code block 形式给出，避免占位符歧义；同时为任务型技能（configure-project、build-project、test-project）规定固定章节顺序：## Commands → ## Expected Output。资料来源：data/scaffold-workspace-skills/SKILL.md。

AGENTS.md 中的 Workspace Skills 索引表必须真实反映项目 skills/ 目录下的内容，禁止保留示例占位行，从而保证 Agent 在执行任务前能精准匹配并加载相关技能。资料来源：data/scaffold-agents/SKILL.md。

资源纪律方面，知识库强调「建议而非越权」：Agent 只实现用户明确请求的内容，对额外改进以一两句话提示即可，避免消耗用户预算。资料来源：data/scaffold-agents/SKILL.md。

See Also

• cpp-quick-start-mcp 项目主页
• Release v0.7.0 更新日志：<https://github.com/m-velikov/cpp-quick-start-mcp/compare/v0.6.0...v0.7.0>

概述

"最佳实践与工作流编排"是 cpp-quick-start-mcp 服务器的核心能力层，它并不直接编写 C++ 代码，而是通过 元技能 (Meta-Skill) 驱动一组原子技能完成从需求访谈到项目脚手架生成的完整流水线。资料来源：data/meta-quickstart/SKILL.md 中明确将 go 描述为 Level 2 "Meta-Skill"，其目标是根据用户的工具栈选择生成与之匹配的 scaffold-* 与 build-* 任务技能。

整套编排层解决三个关键问题：

1. 避免凭空捏造 (anti-hallucination)：所有脚手架命令和约定都必须来自真实读取的技能文件，而不是模型记忆。
2. 决策可追溯：通过分模式 (Mode A / Mode B) 显式控制新项目与既有项目两条不同流程。
3. 最佳实践即资源：将 CMake、Conan、Meson、Clang-Tidy 等最佳实践作为可被 list-resources 工具枚举的 MCP 资源（mcp://scaffold/...）提供。资料来源：README.md:Dynamic Scaffolding Resources。

编排流程：Mode A vs Mode B

元技能 go 在执行任何操作前都必须先进行 预扫描 (Pre-flight Project Scan)，通过 ls 当前目录判定目标路径是空白目录还是已有项目，并据此切换工作流。资料来源：data/meta-quickstart/SKILL.md:Pre-flight Project Scan。

Mode A：全新项目访谈

当目录为空时，代理必须通过交互式多选工具（如 ask_question）逐一询问 12 个类别的用户偏好，例如构建系统、测试框架、布局规范、CI 提供商等。流程强调：

• 即便一次调用只能容纳 4 个问题，代理也必须 按批次连续提问，禁止跳过任何类别。
• 必须为每个问题保留自由文本输入选项，以支持用户自定义答案。
• 完成 12 类别后进入 Step 2：资源发现与主动建议，调用 list-resources 枚举所有可用的 mcp://scaffold/* 资源，并将其嵌入最终的生成计划。

Mode B：既有项目增量 / 现代化

如果目录已包含 CMakeLists.txt、Makefile 或 src/ 等标记，代理切换到 Mode B，禁止进行完整的 Mode A 访谈。取而代之的是：

1. 约定扫描：读取既有构建文件与若干源文件，自动推断构建系统、包管理器、目录布局、命名风格与代码格式。
2. 路径选择：询问用户是 "添加新组件" 还是 "现代化并增强 Agent 开发支持"。
3. 目标平台与一致性检查：询问桌面/移动、Windows/Linux 等平台，并通过 布局一致性检查 (Layout Conformity Check) 评估新增组件是否破坏既有目录约定；若破坏，则主动建议迁移到 Pitchfork 布局。资料来源：data/scaffold-pitchfork-layout/SKILL.md:Existing Project Additions。

flowchart TD
    A[开始] --> B{目录是否为空?}
    B -- 是 --> C[Mode A: 12 类访谈]
    B -- 否 --> D[Mode B: 约定扫描]
    D --> E{添加组件 vs 现代化?}
    E -- 添加 --> F[组件访谈 + 平台询问]
    E -- 现代化 --> G[缺失工具访谈 + 布局重构建议]
    C --> H[Step 2: list-resources]
    F --> H
    G --> H
    H --> I[生成 scaffold-* / build-* 技能]
    I --> J[结束]

最佳实践资源集合

编排层把最佳实践作为独立的 MCP 资源提供，确保模型不会基于过期记忆给出错误建议。以 Meson 资源为例，它明确要求：

• 通过 subdir() 保持根 meson.build 简洁，避免在顶层堆叠所有 library() / executable()。
• 使用 add_project_arguments() 添加项目级警告，禁止硬编码 GCC/Clang 特定标志，需先判断 cpp.get_id()。
• 利用 WrapDB 与 dependency() 的 fallback 优雅处理缺失的系统包。
• 通过 meson test -C build 运行完整测试套件。

资料来源：data/best-practices-meson/SKILL.md:Structured Build Files。

类似地，基础配置文件技能为任何新 C++ 仓库定义了 必须生成 的根目录文件，包括标准 .gitignore、* text=auto eol=lf 规则的 .gitattributes，以及让 clangd 在 build/ 中找到 compile_commands.json 的 .clangd。资料来源：data/scaffold-base-configs/SKILL.md:.gitignore。

代理拓扑与工作区技能

编排的最终落地形态是项目内 永久存在的工作区技能。根据 data/scaffold-agents/SKILL.md:Workspace Skills，每个项目应在 skills/ 目录下拥有 configure-project、build-project、test-project 等任务技能，它们的结构由 data/scaffold-workspace-skills/SKILL.md:Requirements 严格规定：

• 必须使用 kebab-case 命名。
• 必须含 YAML frontmatter（name、description），description 必须包含 Use when ... 触发条件。
• 每个命令必须以可直接复制的代码块形式出现，不允许出现 <your-preset> 类占位符。
• 任务技能必须依次包含 ## Commands 与 ## Expected Output 两个小节。

AGENTS.md 同时强制要求任何后续代理在开始任务前先扫描 skills/ 索引表，匹配触发条件后必须 完整读取 对应的 SKILL.md，禁止凭记忆配置、构建或重构。这条 "READ FIRST" 规则正是整个编排系统的安全护栏——它把分散的最佳实践文档固化为代理必须显式调用的契约。资料来源：data/scaffold-agents/SKILL.md:READ FIRST。

See Also

• Pitchfork Layout Specification — 目录布局权威规范。
• MCP 资源列表：mcp://scaffold/cmake、mcp://scaffold/conan、mcp://scaffold/github-actions、mcp://scaffold/gitlab-ci 等，可在 list-resources 调用时枚举。
• README.md — 安装与运行方式。

Pitfall Log / 踩坑日志

项目：m-velikov/cpp-quick-start-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/m-velikov/cpp-quick-start-mcp | host_targets=mcp_host, claude, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/m-velikov/cpp-quick-start-mcp | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/m-velikov/cpp-quick-start-mcp | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/m-velikov/cpp-quick-start-mcp | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp | release_recency=unknown