Skip to content

README.md

Latest commit

 

History

History
161 lines (125 loc) · 5.12 KB

README.md

File metadata and controls

161 lines (125 loc) · 5.12 KB
Raw

Agentic C / C++ Unit Test Generator (MCP Server)

This project is a high-performance Model Context Protocol (MCP) Server that automates the generation and verification of Google Test (GTest) suites for C/C++ code. It leverages libclang for AST analysis and provides a technical baseline (Boundary, EP, MCDC) to help LLM hosts generate high-quality test cases.

🏗️ Architecture & Design

The utility acts as a bridge between the C++ build/analysis ecosystem and a Large Language Model (LLM). It separates technical analysis (AST, Build, Coverage) from intelligent test design, allowing the LLM to focus on creating high-value test scenarios.

System Overview

graph TD
    subgraph "MCP Host"
        A["User / Agent Prompt"] --> B["Host LLM"]
    end
    
    subgraph "MCP Server (FastMCP)"
        C["mcp_server.py"]
        D["CodeAnalyzer"]
        E["StrategyGenerator"]
        F["TestGenerator"]
    end

    subgraph "Local Tooling"
        G["libclang (AST)"]
        H["CMake / Make (Build)"]
        I["GTest / LCOV (Verify)"]
    end

    B <--> C
    C --> D
    C --> E
    C --> F
    D --> G
    F --> H
    C --> I
Loading

Sequence Flow: Human-in-the-Loop Workflow

sequenceDiagram
    autonumber
    participant U as User
    participant H as MCP Host (LLM)
    participant S as MCP Server
    participant T as OS / Tooling

    U->>H: Request Test Generation
    H->>U: Mode Choice (Step-by-Step vs E2E?)
    U-->>H: Step-by-Step

    H->>S: analyze_source_code()
    S-->>H: AST Results (Functions, Types)
    
    H->>S: get_test_strategy_context()
    S-->>H: Technical Baseline (MCDC, Boundaries)
    
    Note over H,U: MANDATORY REVIEW: Strategy
    H->>U: Display Strategy (.md)
    U-->>H: Approve Strategy

    H->>H: Generate Test Implementation Logic

    H->>S: generate_gtest_file(bodies)
    S-->>H: Success (GeneratedUT/test.cpp)
    
    Note over H,U: MANDATORY REVIEW: Code
    H->>U: Display Generated Code
    U-->>H: Approve Code

    H->>S: run_and_verify_tests()
    S->>T: cmake, make, run, lcov
    T-->>S: Execution & Coverage Data
    S-->>H: Final Summary
    H->>U: Final Report (HTML Coverage link)
Loading

🛠️ MCP Tools

  1. analyze_source_code: Returns deep AST details (Signatures, Class members, Custom Types).
  2. analyze_existing_tests: Returns existing GTest suites to identify coverage gaps.
  3. get_test_strategy_context: Provides a technical baseline (MCDC conditions, Boundary values) for the LLM to use during generation.
  4. generate_gtest_file: Merges host-provided test bodies into a robust GTest template.
  5. run_and_verify_tests: Orchestrates the build and verification pipeline (CMake, Make, GTest, LCOV).

🚀 Usage Guide

1. Standalone CLI Mode (main.py)

The tool can be used directly from the command line for automation or local testing.

  • Analyze & Generate Strategy:

    python3 main.py analyze path/to/source.cpp

    Creates TestStrategy/source_strategy.yaml and .md.

  • Generate Test Code:

    python3 main.py generate TestStrategy/source_strategy.yaml

    Creates GeneratedUT/source_test.cpp.

  • Build & Run with Coverage:

    python3 main.py build path/to/source.cpp --coverage --run

    Performs build in GeneratedUT/build and generates HTML coverage in GeneratedUT/coverage_html/.

  • Clean Workspace:

    python3 main.py clean

    Safely removes GeneratedUT/ and TestStrategy/ directories.

2. MCP Mode (Skill Workflow)

When using an MCP-enabled agent, use the cpp_test_generator skill. Support is available for:

  • Kilo Code: Uses .kilocode/skills/
  • Roo Code: Uses .roo/skills/ and .roomodes
  • GitHub Copilot: Uses .github/copilot-instructions.md

Workflow Sequence:

  1. Initialization: The agent asks for "Step-by-Step" or "End-to-End" mode. Use Step-by-Step for manual review.
  2. Technical Baseline: The agent provides the strategy context. Review this carefully in the TestStrategy folder.
  3. Approval: Grant permission to proceed to code generation.
  4. Code Review: The agent displays the generated code. Review this for correctness in the GeneratedUT folder.
  5. Final Verification: Grant permission to build and verify.

📂 Project Structure

  • src/: Core logic (Analyzer, Strategy, Generator).
  • templates/: Jinja2 templates for CMakeLists.txt and GTest files.
  • TestStrategy/: Output directory for analysis results (YAML/MD).
  • GeneratedUT/: Output directory for generated tests and build artifacts.
  • main.py: Standalone CLI entry point.
  • mcp_server.py: MCP Server entry point.

🔩 Installation

Requirements

  • Linux (optimized for Ubuntu/Debian)
  • libclang, cmake, g++, lcov, python3
  • pip install mcp jinja2 pyyaml rich typer

Config for MCP Clients

Add this to your mcp_settings.json or mcp.json:

{
  "command": "python3",
  "args": ["/absolute/path/to/UnitTest_Generator_MCP/mcp_server.py"],
  "env": { "PYTHONPATH": "/absolute/path/to/UnitTest_Generator_MCP" }
}