Related Pages

Related topics: Installation & Client Configuration, Scaffolding Skills Knowledge Base, Interview Workflow & Usage Patterns

Project Overview & MCP Architecture

Purpose and Scope

@m-velikov/cpp-quick-start-mcp is a Model Context Protocol (MCP) server whose purpose is to scaffold modern C++ projects and configure them for agentic AI development. It exposes structured knowledge — build files, layout conventions, CI pipelines, static-analysis configs, and agent-guideline templates — that an AI agent client can fetch on demand and assemble into a working C++ repository. Source: README.md:1-30

The package is distributed on the NPM registry under the name @m-velikov/cpp-quick-start-mcp and registers a global CLI named cpp-quick-start-mcp. Source: package.json:1-11 and package.json:23-30 ("bin": { "cpp-quick-start-mcp": "build/index.js" }). It is written in TypeScript, built to build/index.js, requires Node.js >=18.3.0, and uses ES modules ("type": "module"). Source: package.json:25-29.

As of release v0.7.0 (Changelog), the published bundle ships the compiled server plus the entire data/ directory of scaffolding resources, declared in package.json:18-21 ("files": ["build", "data"]).

MCP Architecture

The server follows the standard MCP pattern with three primitives exposed to clients: tools, resources, and prompts.

• Resources are URI-addressed content blocks the agent reads through MCP read-resource. The canonical scheme used throughout the project is mcp://scaffold/<topic> (e.g. mcp://scaffold/cmake, mcp://scaffold/conan, mcp://scaffold/github-actions). Source: README.md:18-22 and data/meta-quickstart/SKILL.md.
• Tools include at least list-resources, which returns the complete URI catalogue so the agent can decide what to load. Source: data/meta-quickstart/SKILL.md.
• Prompts provide entry-point workflows. The flagship prompt is go, a Level-2 meta-skill that orchestrates scaffolding rather than writing C++ directly. Source: data/meta-quickstart/SKILL.md:6-10.

Two transports are supported. The default uses standard I/O for MCP clients that launch the server as a subprocess. Optionally, the server can run over HTTP/SSE via cpp-quick-start-mcp --port 3000, binding 0.0.0.0:3000. Source: README.md:48-55.

flowchart LR
    A[AI Agent Client] -- MCP protocol --> B[cpp-quick-start-mcp server]
    B -- tools/list, resources/read --> A
    B -- data/*.md --> C[(data/ scaffolding skills)]
    B -- generated skills/, AGENTS.md --> D[(User Project)]

Resource & Skill Catalogue

Every shipped resource is a Markdown skill under data/scaffold-<component>/SKILL.md, each starting with YAML frontmatter containing a kebab-case name and a single-line description ending in Use when …. Source: data/scaffold-cmake/SKILL.md:1-3 and data/scaffold-workspace-skills/SKILL.md:9-14.

The meta-quickstart skill (go prompt) does not scaffold C++ itself — it drives the interview and then dispatches to the per-component skills above. Source: data/meta-quickstart/SKILL.md:6-12.

Meta-Scaffold Workflow

The go prompt implements a two-mode workflow. Source: data/meta-quickstart/SKILL.md:13-26.

1. Pre-flight scan — list the working directory to detect an existing project (CMakeLists.txt, Makefile, src/, etc.).
2. Mode A: New Project — run a 12-category interactive interview (build system, package manager, C++ standard, layout, testing framework, CI provider, formatter, static analysis, target platforms, namespace, license, etc.).
3. Mode B: Existing Project — read existing build files to infer conventions, then ask whether to add components or modernize the codebase for agentic development. Source: data/meta-quickstart/SKILL.md (Mode B section).
4. Resource discovery — call list-resources to enumerate every available mcp://scaffold/* URI and proactively suggest the relevant ones.
5. Skill emission — write permanent workspace skills into the user's project at skills/<skill-name>/SKILL.md, each with the frontmatter and required sections (## Commands, ## Expected Output) mandated by scaffold-workspace-skills/SKILL.md:9-26.
6. AGENTS.md generation — emit a top-level agent-guidelines file whose "Workspace Skills" index row-matches every skill actually present in skills/. Source: scaffold-agents/SKILL.md:9-30.

The end result is a C++ repository seeded with executable, copy-pasteable CLI commands for configuring, building, testing, and reviewing the project — so any future agent can collaborate safely without improvising.

See Also

• Latest release notes: v0.7.0 changelog
• Pitchfork Layout Specification — referenced by data/scaffold-pitchfork-layout/SKILL.md
• CMake Presets v3 — referenced by data/scaffold-cmake-presets/SKILL.md

Related Pages

Related topics: Project Overview & MCP Architecture, Interview Workflow & Usage Patterns

Installation & Client Configuration

Overview

cpp-quick-start-mcp is a Model Context Protocol (MCP) server that bootstraps modern C++ projects through a guided interview with an AI agent. It exposes a curated library of mcp://scaffold/* resources and a quickstart prompt, letting any MCP-compatible client generate build files, manifests, agent guidelines, and directory structures consistent with current C++ best practices. Source: README.md:1-40

This page focuses on getting the server installed, started, and wired into an MCP client, then summarizes what the client can expect to discover on the other end.

Installation

The server is distributed as a Node.js package and can be installed globally in two ways. Source: README.md:50-75

Install from NPM (Recommended)

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

This registers the cpp-quick-start-mcp binary on PATH, which is the command every MCP client will eventually invoke. Source: README.md:55-60

Install from Source (Local Development)

When cloning the repository for hacking on the server itself:

npm install
npm run build
npm install -g .

The first two commands resolve the project's own development dependencies and compile the TypeScript output; the third installs the locally built package globally so the cpp-quick-start-mcp command is available system-wide. Source: README.md:63-73

Server Startup Options

By default the server speaks MCP over standard I/O, which is the transport expected by most agent runtimes (Claude Desktop, IDE plugins, etc.). It can also be run standalone over HTTP/SSE. Source: README.md:80-90

# Start with default options (port 3000, host 0.0.0.0)
cpp-quick-start-mcp --port 3000

When launched this way the server binds to all interfaces (0.0.0.0) on port 3000, making it reachable from other machines on the network. The README explicitly notes that this HTTP/SSE mode is optional — for most agent workflows the stdio transport is sufficient. Source: README.md:85-90

Client Configuration

Once installed, the server must be registered with an MCP-compatible client. The client is responsible for spawning the cpp-quick-start-mcp process (stdio mode) or pointing at the HTTP/SSE endpoint (network mode) defined above.

The server's onboarding flow is driven by the quickstart prompt, which performs a Mode A interview for new projects or a Mode B audit for existing repositories, then reads additional mcp://scaffold/* resources to fill in the chosen stack. Source: data/meta-quickstart/SKILL.md:1-40

Typical configuration for a stdio-based MCP client (pseudo-config):

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

For network mode, replace command with a url pointing at http://<host>:3000. Source: README.md:85-90

What the Client Discovers

After connecting, the client can enumerate the server's resources to understand the scaffolding surface area. The bundled resources cover every decision point the agent needs:

• Build systems: CMake, Make, Meson, Bazel — each skill enforces non-recursive architectures and target-based modularity. Source: data/scaffold-cmake/SKILL.md:1-25, data/scaffold-make/SKILL.md:1-15
• Package managers & packaging: Conan, vcpkg — generating manifest files with locked baselines. Source: data/scaffold-vcpkg/SKILL.md:1-25
• Directory layouts: Pitchfork Layout — the recommended structure for both single and multi-target projects. Source: data/scaffold-pitchfork-layout/SKILL.md:1-40
• CMake Presets: CMakePresets.json generation to standardize cmake --preset dev workflows. Source: data/scaffold-cmake-presets/SKILL.md:1-25
• Testing frameworks: Doctest boilerplate and integration recipes. Source: data/scaffold-doctest/SKILL.md:1-25
• Static analysis: .clang-tidy and cppcheck configuration wired into both build targets and (optionally) pre-commit hooks. Source: data/scaffold-clang-tidy/SKILL.md:1-25, data/scaffold-cppcheck/SKILL.md:1-25
• Base repository files: .gitignore, .gitattributes, and .clangd so Git, cross-platform line endings, and IDEs all behave correctly out of the box. Source: data/scaffold-base-configs/SKILL.md:1-40
• Agent topology: An AGENTS.md index table that points future agents at the project's own workspace skills. Source: data/scaffold-agents/SKILL.md:1-30

The permanent skills written into the user's project under skills/<name>/SKILL.md follow a strict structure — YAML frontmatter, kebab-case names, copy-pasteable commands, and ordered ## Commands / ## Expected Output sections — so downstream agents can rely on a predictable shape regardless of which skill they load. Source: data/scaffold-workspace-skills/SKILL.md:1-25

Common Failure Modes

1. Command not found after install: The global node_modules bin directory is not on PATH. Re-run with npm install -g or use npx @m-velikov/cpp-quick-start-mcp instead.
2. Server starts but client sees no resources: Some MCP clients cache the resource list at connect time. Restart the client (or reconnect the server) after upgrading — the v0.7.0 release added resources that older sessions may not surface.
3. Mode B detects the wrong conventions: When invoked against an existing project, the agent scans build files for hints. Make sure the project's primary build file (e.g. CMakeLists.txt, Makefile) is committed and not generated. Source: data/meta-quickstart/SKILL.md:15-35

See Also

• Quickstart Interview Flow & Modes
• Scaffolding Resources Reference
• Workspace Skills Format

Related Pages

Related topics: Project Overview & MCP Architecture, Interview Workflow & Usage Patterns

Scaffolding Skills Knowledge Base

The Scaffolding Skills Knowledge Base is the structured collection of Markdown-based instructional resources shipped under data/scaffold-* within the cpp-quick-start-mcp MCP server. It powers a "dynamic scaffolding" workflow in which an AI agent can read targeted skill files via the mcp://scaffold/* resource URIs and emit correct, opinionated boilerplate for a wide range of C++ toolchains. As described in README.md, the knowledge base exists so the model "knows exactly how to write the requested boilerplate files perfectly" and seeds a project with "built-in guidelines and architecture rules" for safe agentic collaboration.

Purpose and Scope

The knowledge base is not a static C++ tutorial. It is a curated set of executable instructions, each scoped to a single tool, layout, or workflow. Every skill file uses YAML frontmatter with name and a one-line description ending in Use when ... so an agent can decide whether to load it without reading the body.

Skills fall into three operational layers:

• Meta-skill — data/meta-quickstart/SKILL.md ("go") is a Level 2 meta-skill whose job is to interview the user, then synthesize a tailored scaffolding plan. It explicitly states it is a "Level 2 'Meta-Skill'. Its purpose is not to write C++ code directly, but to generate the _actual_ scaffolding skills (e.g., scaffold-project, build-project) tailored to the user's specific tooling choices." (meta-quickstart/SKILL.md)
• Per-tool scaffolding skills — one skill per tool: scaffold-cmake, scaffold-bazel, scaffold-meson, scaffold-make, scaffold-vcpkg, scaffold-doctest, scaffold-clang-tidy, scaffold-cppcheck, scaffold-cmake-presets, scaffold-base-configs, scaffold-pitchfork-layout, scaffold-gitlab-ci, etc.
• Project-emitted skills — scaffold-workspace-skills defines the structure for the *permanent* task skills (e.g. configure-project, build-project, test-project) that get written into the user's skills/ directory after scaffolding.

Coverage of the C++ Stack

The knowledge base spans the major axes of a modern C++ project:

Each skill encodes non-negotiable conventions. For example, scaffold-cmake mandates cmake_minimum_required(VERSION 3.20), target-based Modern CMake, cxx_std_20 via target_compile_features, and a critical modularity rule: "Do NOT create a single monolithic top-level CMakeLists.txt … you MUST split the build files per artifact." (scaffold-cmake/SKILL.md). scaffold-make enforces a non-recursive Makefile design, warning that "GNU Make does not support ** globbing, so it would silently expand to nothing" if $(wildcard ...) is used naively (scaffold-make/SKILL.md). scaffold-bazel declares a root MODULE.bazel for Bzlmod and uses per-target BUILD files (scaffold-bazel/SKILL.md), while scaffold-meson follows the same modularity rule for Meson (scaffold-meson/SKILL.md).

Quality, layout, and CI skills add their own firm rules. scaffold-clang-tidy requires the agent to ask the user about naming conventions before emitting CheckOptions for readability-identifier-naming.* (scaffold-clang-tidy/SKILL.md). scaffold-cppcheck provides a run-cppcheck add_custom_target template wired into CMake with a curated --suppress list (scaffold-cppcheck/SKILL.md). scaffold-pitchfork-layout requires a target-namespaced include/<target_name>/ subdirectory, explicitly forbidding flat headers (scaffold-pitchfork-layout/SKILL.md). scaffold-cmake-presets standardizes configuration via a hidden base preset plus dev/release user-facing presets (scaffold-cmake-presets/SKILL.md). scaffold-base-configs ships the canonical .gitignore, .gitattributes, and .clangd every project should have (scaffold-base-configs/SKILL.md), and scaffold-gitlab-ci provides a two-stage (build, test) pipeline with ccache and per-package-manager caching (scaffold-gitlab-ci/SKILL.md).

Skill Structure and Composition

Workspace-emitted skills are governed by scaffold-workspace-skills, which makes the format uniform. Every such skill must live at skills/<skill-name>/SKILL.md with kebab-case names, the same YAML frontmatter, copy-pasteable commands in fenced blocks (no unresolved placeholders), and, for task skills, a fixed ## Commands / ## Expected Output section order (scaffold-workspace-skills/SKILL.md). scaffold-agents builds on this by populating an AGENTS.md index table whose rows are generated from the description of every skill actually present in skills/, ensuring future agents always read the relevant skill before acting (scaffold-agents/SKILL.md).

The meta-skill orchestrates composition. meta-quickstart instructs the agent to first scan the working directory to decide between Mode A: New Project Interview and Mode B: Add Components, ask all 12 stack categories in batched multiple-choice questions, then call list-resources to discover every mcp://scaffold/* URI, perform a gap analysis, and "proactively suggest relevant ones to the user" — e.g. scaffold-clang-tidy, scaffold-cppcheck, scaffold-code-hygiene, scaffold-github-actions — before writing a single file (meta-quickstart/SKILL.md). This means the knowledge base is not consumed linearly; it is queried on demand and stitched together per project, which is why the v0.7.0 release emphasizes "Dynamic Scaffolding Resources" and an "Agent-Ready Architecture" in README.md.

See Also

• cpp-quick-start-mcp overview and installation
• Release notes: v0.7.0 changelog

Related Pages

Related topics: Project Overview & MCP Architecture, Scaffolding Skills Knowledge Base, Installation & Client Configuration

Interview Workflow & Usage Patterns

Overview

cpp-quick-start-mcp is an MCP (Model Context Protocol) server that drives AI agents through a deterministic, interview-based workflow for creating and modernizing C++ projects. The centerpiece of this workflow is the Level 2 meta-skill data/meta-quickstart/SKILL.md, which delegates work to a library of single-purpose scaffolding skills (e.g., scaffold-cmake, scaffold-meson, scaffold-pitchfork-layout, scaffold-doctest). The result is an agentic stack that exposes curated mcp://scaffold/* resources and writes a project-specific AGENTS.md plus a skills/ directory of permanent workspace skills (README.md).

The current latest release is v0.7.0, which incrementally refines this interview workflow; users upgrading from v0.6.0 should see no breaking changes to the MCP interface but should consult the release comparison for additions to the question set or new skill resources.

Pre-flight Scan and Mode Selection

The interview always begins with a pre-flight project scan: the agent lists the working directory and looks for markers such as CMakeLists.txt, Makefile, or src/. Based on this scan, data/meta-quickstart/SKILL.md branches into one of two top-level modes:

• Mode A — New Project Interview: the directory is essentially empty.
• Mode B — Add Components or Modernize: an existing project is detected. The agent scans the build files and a few sources to infer conventions, then asks the user which path to take.

flowchart TD
    A[Pre-flight Scan] --> B{Empty dir?}
    B -- yes --> C[Mode A: 12-category interview]
    B -- no --> D[Mode B: Convention Scan]
    D --> E{User path?}
    E -- Path 1 --> F[Add Components]
    E -- Path 2 --> G[Modernize & Augment]
    C --> H[Step 2: Resource Discovery]
    F --> H
    G --> H
    H --> I[Generate scaffolding + workspace skills]

Mode A: New Project Interview

When the directory is empty, the meta-skill requires the agent to ask the user about 12 mandatory categories (build system, C++ standard, package manager, testing framework, formatter, linter, static analyzer, CI provider, pre-commit hooks, target platforms, project layout, license). Per data/meta-quickstart/SKILL.md, the agent must:

1. Use an interactive multiple-choice question tool (e.g., ask_question) with a free-form text input option, since users may have write-in answers.
2. Split questions across as many consecutive batches as the tool allows; none of the 12 categories may be skipped, inferred, or dropped, even if the tool only fits four questions per call.
3. After the interview, automatically load and apply the matching scaffold-* skill for each chosen component. For example, selecting CMake activates data/scaffold-cmake/SKILL.md, which mandates a target-based CMakeLists.txt per artifact with cmake_minimum_required(VERSION 3.20) (or higher) and target_compile_features(... PUBLIC cxx_std_20) enforced on the target rather than via CMAKE_CXX_STANDARD. Picking CMake also triggers data/scaffold-cmake-presets/SKILL.md, which requires a CMakePresets.json (version 3+) with a hidden base preset and user-facing dev / release presets inheriting from it.

Mode B: Adding Components to or Modernizing an Existing Project

When a project already exists, the agent must NOT redo the full Mode A interview. Instead, per data/meta-quickstart/SKILL.md:

• The agent auto-detects the build system, package manager, directory layout, naming conventions, and formatting style from existing files.
• It asks the user to pick Path 1 (Add Components) or Path 2 (Modernize & Augment).
• Path 1 triggers a focused component interview: new libraries/executables, target platforms, and a layout-conformity check (e.g., proposing a migration to Pitchfork if the additions would violate the inferred layout).
• Path 2 triggers a missing-tooling interview (.clang-format, pre-commit hooks, .clang-tidy, cppcheck, testing, CI/CD, .gitignore), a build-system evaluation that *avoids* migrations to a different family (e.g., Make → CMake is disallowed, but legacy CMake → target-based CMake is encouraged), an explicit Pitchfork-layout question, and a target-platforms question.

Step 2: Resource Discovery and Proactive Suggestion

After either Mode concludes, the meta-skill requires the agent to call list-resources against the MCP server, fetch every relevant mcp://scaffold/* URI via read-resource, and include the full text of any matching best-practices resource into the generated workspace skills. This is what produces the project-specific skills/best-practices-<component>/SKILL.md files; for example, a Meson-based project receives data/best-practices-meson/SKILL.md content in full, covering structured meson.build files, dialect selection via default_options: ['cpp_std=c++20'], dependency() lookup, and the meson test -C build invocation (data/best-practices-meson/SKILL.md).

The meta-skill also mandates specific workspace skills be created (always in full, never summarized):

• skills/configure-project/SKILL.md — exact dependency-fetch and configure commands.
• skills/build-project/SKILL.md — exact build commands.
• Component best-practices skills (e.g., best-practices-cmake).
• skills/best-practices-refactoring/SKILL.md — refactoring rules including the namespace/file-name consistency rule.
• skills/best-practices-code-review/SKILL.md — code-review rules.

Workspace Skill Structure and `AGENTS.md`

Every skill written into the user's skills/ directory must follow the contract in data/scaffold-workspace-skills/SKILL.md: kebab-case directory names matching the name field, a YAML frontmatter with name and a one-line description ending in Use when ..., copy-pasteable commands in fenced code blocks with no placeholders, and (for task skills) a ## Commands section followed by ## Expected Output.

The generated AGENTS.md (per data/scaffold-agents/SKILL.md) is the agent's entry point and must contain a Workspace Skills index table whose rows reflect only the skills actually present in skills/. Agents are instructed to scan this table first and load the relevant SKILL.md in full before configuring, building, testing, refactoring, or reviewing the project.

Common Failure Modes

• Skipping interview categories: a known anti-pattern. The meta-skill explicitly forbids inferring or dropping any of the 12 categories.
• Using recursive Makefiles: data/scaffold-make/SKILL.md requires a non-recursive Makefile design because GNU Make does not support ** globbing and recursive $(MAKE) calls hurt dependency tracking.
• Replacing the build system family in Mode B: never migrate Make → CMake or vice versa; only modernize within the existing family.
• Summarizing MCP resources: the meta-skill requires read-resource contents to be included in full in the generated workspace skills, not paraphrased.
• Omitting AGENTS.md or CMakePresets.json: when CMake is chosen, both files are mandatory outputs of the interview workflow.

See Also

• Scaffolding Skills — catalog of every scaffold-* resource.
• Workspace Skills Format — detailed format spec for the generated skills/ directory.
• Best Practices Library — full list of best-practices-* resources embedded into projects.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/m-velikov/cpp-quick-start-mcp

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/m-velikov/cpp-quick-start-mcp

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/m-velikov/cpp-quick-start-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/m-velikov/cpp-quick-start-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using cpp-quick-start-mcp with real data or production workflows.

• Release v0.7.0 - github / github_release
• Release v0.6.0 - github / github_release
• Release v0.5.0 - github / github_release
• Release v0.4.1 - github / github_release
• Release v0.4.0 - github / github_release
• Release v0.3.0 - github / github_release
• Configuration risk requires verification - GitHub / issue