# Cpp-Test-Agent-MCP

**Repository Path**: aramae/cpp-test-agent-mcp

## Basic Information

- **Project Name**: Cpp-Test-Agent-MCP
- **Description**: 基于开源架构复现并二次开发的 AI C/C++ 单元测试生成工具。集成 libclang AST 分析与 LLM，自动生成并验证 GTest 测试套件，支持 MCP 协议并可通过 CLI 独立运行。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cpp-Test-Agent-MCP

> 基于 MCP 协议的 C/C++ 单元测试自动生成与覆盖率验证工具
> 本项目基于开源项目 [UnitTest_Generator_MCP](https://github.com/ajithksr/UnitTest_Generator_MCP) 二次开发，重点完成国内网络 + Ubuntu 24.04 + GCC 13 环境下的工程化适配。

集成 libclang AST 分析、LLM 测试生成、CMake 构建、GTest 执行与 LCOV 覆盖率分析，通过 MCP 协议为 LLM 代理提供 5 个工具接口，也可独立通过 CLI 运行。

---

## ✨ 我的改造点

### 1. Ubuntu 24.04 + libclang 18 环境适配

**问题**：原版在 Ubuntu 24.04 下 `analyze` 直接崩溃，报错 `LibclangError: libclang.so: cannot open shared object file`。

**修复**：
- `src/analyzer.py` 中硬编码 `Config.set_library_file('/usr/lib/llvm-18/lib/libclang.so.1')`
- 配合 `/etc/ld.so.conf.d/llvm.conf` 注册动态库搜索路径

**效果**：`analyze` 命令从 0% 成功率 → 100%。

### 2. lcov 2.x + GCC 13 覆盖率兼容

**问题**：原版在 lcov 2.0 下报 `mismatch end line` 错误，HTML 覆盖率报告为空。

**修复**：
- `main.py` / `mcp_server.py` 中给 `lcov`、`genhtml` 命令加 `--ignore-errors mismatch,empty,negative,unused` 参数

**效果**：覆盖率报告正常生成，实测 `sample.cpp` 达 **85.7% 行覆盖率 / 100% 函数覆盖率**。

### 3. 国内网络环境下 gtest 依赖拉取

**问题**：CMake 从 GitHub 实时下载 gtest 源码，国内网络下报 `status_code: 56` 或超时。

**修复**：
- 从 Gitee 镜像预拉取 gtest 源码到本地
- 修改 CMakeLists 模板的 `FetchContent_Declare`，改为 `SOURCE_DIR` 本地路径

**效果**：首次 `build` 成功率从 0% → 100%。

### 4. 依赖版本锁定

**问题**：原版未锁定 `clang` 版本，装到 21.x 时会与系统 libclang 18 不兼容，报 `undefined symbol`。

**修复**：`requirements.txt` 补上 `clang==18.1.8`。

### 5. gtest 源路径可配置

**问题**：原版 CMakeLists 模板硬编码了 gtest 源路径，无法适配不同环境。

**修复**：
- `main.py` 增加 `--gtest-dir` 参数（默认 `/tmp/googletest`）
- 通过 Jinja2 模板变量传递到 CMakeLists.txt

**效果**：用户可通过 `python3 main.py build sample.cpp --gtest-dir /custom/path` 自由指定 gtest 位置，无需改代码。

### 6. 覆盖率门禁（Coverage Gate）

**问题**：原版在生成覆盖率报告后，无论覆盖率多少都返回成功，无法直接接入 CI/CD 流水线进行质量卡点。

**修复**：
- `main.py` 的 `build` 命令增加 `--threshold` 参数。
- 使用正则解析 `lcov` 摘要，若实际覆盖率低于阈值，打印红色错误并以状态码 `1` 退出。

**效果**：实现了流水线级别的质量门禁。例如：`python3 main.py build sample.cpp --coverage --threshold 80`，若覆盖率未达标将直接阻断后续构建流程。

## 🚀 Quick Start

### 环境要求

- Ubuntu 22.04 / 24.04
- Python 3.10+
- 系统依赖：`libclang-dev`、`clang`、`cmake`、`g++`、`lcov`、`libgtest-dev`

### 安装

```bash
sudo apt update
sudo apt install -y libclang-dev clang cmake g++ lcov python3 python3-pip libgtest-dev

git clone git@gitee.com:aramae/Cpp-Test-Agent-MCP.git
cd Cpp-Test-Agent-MCP

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 国内网络：预拉取 gtest
git clone --depth 1 https://gitee.com/mirrors/googletest.git /tmp/googletest
```

### 使用

```bash
# 分析源码，生成测试策略
python3 main.py analyze sample.cpp

# 生成 GTest 测试代码
python3 main.py generate TestStrategy/sample_strategy.yaml

# 编译 + 运行测试 + 生成覆盖率报告
python3 main.py build sample.cpp --coverage --run

# 清理工作区
python3 main.py clean
```

---

## 🛠️ MCP 工具集

| 工具 | 功能 |
|---|---|
| `analyze_source_code` | 返回深度 AST 详情 |
| `analyze_existing_tests` | 分析已有 GTest 套件，识别覆盖率缺口 |
| `get_test_strategy_context` | 提供技术基线（MCDC、边界值） |
| `generate_gtest_file` | 将测试体合并到 GTest 模板 |
| `run_and_verify_tests` | 编排构建与验证流水线 |

---


## 📂 项目结构

```
src/              核心逻辑（Analyzer、Strategy、Generator）
templates/        Jinja2 模板（CMakeLists.txt、GTest 文件）
main.py           独立 CLI 入口
mcp_server.py     MCP 服务器入口
requirements.txt  Python 依赖（含 clang==18.1.8 锁定）
```

---

## 📌 与原项目的差异

| 项 | 原版 | 本版 |
|---|---|---|
| libclang 路径 | 依赖系统默认 | 硬编码兼容 + ldconfig 注册 |
| lcov 版本 | 假设 1.x | 兼容 2.x |
| gtest 拉取 | GitHub URL | 支持本地 / Gitee 镜像 |
| 依赖版本 | 未锁定 | `clang==18.1.8` |

---

## 🙏 致谢

本项目基于 [ajithksr/UnitTest_Generator_MCP](https://github.com/ajithksr/UnitTest_Generator_MCP) 二次开发，感谢原作者的开源贡献。