coco-mcp

# Coco MCP Server Preview The Coco Model Context Protocol (MCP) server allows you to interact with Coco code coverage data and reports in an AI-assisted workflow. See the [release announcement](https://www.qt.io/blog/introducing-the-coco-mcp-server-preview-for-qt-developers). ## Requirements * [uv](https://docs.astral.sh/uv/) for managing the Python environment and dependencies * [Coco](https://www.qt.io/quality-assurance/coco) 7.5.0 or later, with the command line tools available in the `PATH` environment variable * MCP-compatible client, e.g. * [Visual Studio Code](https://code.visualstudio.com/) with [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) Extension * [Claude Code](https://claude.com/product/claude-code) > [!NOTE] > The MCP tools assume that the `.csmes` files (coverage database) and `.csexe` files (runtime coverage data) have already been generated from an instrumented build and test execution. ## Installation 1. Clone the repository: ```bash git clone <coco-mcp-repo-url> ``` 2. Install Python dependencies: ```bash cd coco-mcp uv sync ``` ## Configuration When using with a local coding agent, you can configure the MCP server to start automatically with your agent. The exact steps depend on the coding agent you are using, but generally involve adding a new MCP server configuration that runs the command: ```bash uv run --directory <path/to/coco-mcp> coco_mcp ``` > [!NOTE] > Make sure to replace `<path/to/coco-mcp>` with the **absolute path to the `coco-mcp`** directory on your machine. Below are example configuration steps for some popular coding agents. <details> <summary> ### GitHub Copilot </summary> See MCP configuration documentation for [VS Code (GitHub Copilot)](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more details. #### User Configuration From any *Visual Studio Code* window, you can add `coco-mcp` to your *user's list of MCP servers* by using the Command Palette (*Ctrl+Shift+P* or *Cmd+Shift+P* on macOS) and searching for **"MCP: Open User Configuration"**. This opens the file `mcp.json` in your user's global configuration directory where you can add the server configuration for Coco MCP: ```json { "servers": { "Coco MCP": { "command": "uv", "args": [ "run", "--directory", "<path/to/coco-mcp>", "coco_mcp" ] } } } ``` #### Workspace Configuration When you want to use the MCP server only for a specific project or repository, it's better to configure it in the workspace settings instead of globally for your user. For workspace-specific configuration, you can use **"MCP: Open Workspace Folder MCP Configuration"** instead, or directly create a `.vscode/mcp.json` file in that folder where you can add the same server configuration as above. </details> <details> <summary> ### Claude Code </summary> See MCP installation documentation for [Claude Code](https://code.claude.com/docs/en/mcp#installing-mcp-servers) for more details. #### User Scope Configuration For *Claude Code*, you can add the MCP server to your user's global settings via the terminal command: ```bash claude mcp add --transport stdio --scope user coco_mcp -- uv run --directory <path/to/coco-mcp> coco_mcp ``` #### Local/Project Scope Configuration When working on a specific project, you may want to configure the MCP server only for that project or workspace instead of globally for your user. You can use the same command as above but with `--scope local` or `--scope project` instead of `--scope user` to configure the server for the current directory's workspace or project, respectively. See the [documentation on MCP installation scopes](https://code.claude.com/docs/en/mcp#mcp-installation-scopes) for details. </details> ## Example Usage ### Using Sample Reports The folder `examples/sample_reports` contains `.csmes` and `.csexe` files generated from a sample project. You can use the MCP server to query and analyze the coverage data, without needing to set up instrumentation or generate the reports yourself. #### Setup 1. Navigate to the `examples/sample_reports` directory. ```bash cd examples/sample_reports ``` 2. *Optional:* If you haven't configured the MCP server globally for your user, configure it for this workspace directory as described in the [Configuration](#configuration) section above. - For [GitHub Copilot](#workspace-configuration), you can create a `.vscode/mcp.json` file in the `examples/sample_reports` directory with the JSON configuration. - For [Claude Code](#localproject-scope-configuration), you can run the `claude mcp add` command with `--scope local` while in the `examples/sample_reports` directory. 3. Open the `examples/sample_reports` directory with your coding agent, e.g.: ```bash claude . ``` #### Sample Prompts You can then prompt the agent to analyze the coverage data and generate reports, e.g.: > [!TIP] > Prompt: **"Import execution reports to unittests.csmes"** > > Import execution reports (`.csexe`) to measurement files (`.csmes`) using the `import_execution_report` tool > [!TIP] > Prompt: **"Create decision coverage report in CSV format for the same measurements file"** > > Creates a CSV report for decision coverage, using the `create_csv_report` tool, and returns the file path to the generated report > [!TIP] > Prompt: **"What is the overall condition coverage"** > > Reports the overall condition coverage percentage using the `get_coverage_overview` tool > [!TIP] > Prompt: **"Which lines in `parser.cpp` are unexecuted or dead code?"** > > Returns exact line numbers grouped by status using the `get_file_coverage_detail` tool ### Using the Coco Parser Example You can try out the MCP server on a sample codebase that has been instrumented with Coco. Coco comes with a [parser example](https://doc.qt.io/coco/instrumentation-of-a-simple-project.html) that you can build with instrumentation and run tests to generate coverage data. We have included an instructions markdown file `parser-instructions.md` in this repository that contains instructions for your coding agent to build and run the parser example with Coco instrumentation. You can then use the Coco MCP server to analyze the coverage data and suggest improvements. #### Setup 1. Create a local working directory and copy the source code of the parser samples and the CppUnit testing framework into it. - Windows: ```bat mkdir parser_sample cd parser_sample xcopy "%SQUISHCOCO%\parser" parser /E /I /Y xcopy "%SQUISHCOCO%\cppunit-1.15.1" cppunit-1.15.1 /E /I /Y ``` - Linux/macOS: ```bash mkdir parser_sample cd parser_sample cp -r /path/to/SquishCoco/samples/parser /path/to/SquishCoco/samples/cppunit-1.15.1 . ``` 2. Navigate to the `parser/parser_v4` directory and copy the `examples/parser/parser-instructions.md` file from this repository to the markdown file that your coding agent uses as instructions. - For example, if you are using Claude Code on Linux/macOS you need to create a `CLAUDE.md` file in the `parser_v4` directory: ```bash cd parser/parser_v4 cp /path/to/coco-mcp/examples/parser/parser-instructions.md CLAUDE.md ``` See [CLAUDE.md](https://code.claude.com/docs/en/memory#claude-md-files) documentation for more details. - If you are using Visual Studio Code with GitHub Copilot on Windows, you can place this file in the `.github` folder as `copilot-instructions.md`: ```bat cd parser\parser_v4 mkdir .github copy \path\to\coco-mcp\examples\parser\parser-instructions.md .github\copilot-instructions.md ``` See [Copilot Instructions documentation](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions) for more details. 3. *Optional:* If you haven't configured the MCP server globally for your user, configure it for the `parser_v4` directory as described in the [Configuration](#configuration) section above. - For [GitHub Copilot](#workspace-configuration), you can create a `.vscode/mcp.json` file in your working version of `parser_v4` with the JSON configuration. - For [Claude Code](#localproject-scope-configuration), you can run the `claude mcp add` command with `--scope local` while in the `parser_v4` directory. 4. Open the `parser/parser_v4` directory with your coding agent and try the prompts below, e.g. for Claude Code: ```bash claude . ``` #### Sample Prompts > [!TIP] > Prompt: **"Build the parser example with Coco instrumentation and run the tests to generate coverage data"** > > Use the provided instructions file to build the parser example with Coco instrumentation and run the tests, which will generate `unittests(.exe).csmes` and `unittests(.exe).csexe` files. > [!TIP] > Prompt: **"Give me a report on decision coverage"** > > Import and analyze the coverage data and report the decision coverage percentage. > [!TIP] > Prompt: **"Increase the decision coverage of `parser.cpp` by writing additional test cases"** > > Use the generated report to suggest additional test cases to increase decision coverage of `parser.cpp` ## Testing The `tests` folder contains unit tests for the MCP server's internal functions, which can be run with `pytest`. To run the tests, first install the test dependencies, then run `pytest`: ```bash uv sync --extra test uv run pytest ```