# Ceedling MCP Server

An MCP (Model Context Protocol) server that bridges LLMs to the **Ceedling** C unit testing framework. Designed for zero-setup execution via `uvx`.

## Features

| Tool | Description |
|------|-------------|
| `run_all_tests` | Execute the full Ceedling test suite |
| `run_module_tests` | Run tests for a specific module by name |
| `create_module` | Scaffold new source/header/test file triplets |

**Intelligent output filtering** — Successes are summarized compactly; failures are extracted with precise file, line number, and assertion error messages.

## Prerequisites

- **Python** ≥ 3.10
- **Ceedling** installed and on PATH (`gem install ceedling`)
- **uv** (for `uvx` execution): [https://docs.astral.sh/uv/](https://docs.astral.sh/uv/)

## Project Structure

```
ceedling-mcp-server/
├── pyproject.toml
├── README.md
└── src/
    ├── __init__.py
    ├── server.py       # FastMCP server + tool definitions
    └── parser.py        # Intelligent output parser
```

## Quick Start

### Run directly with uvx (no install needed)

From the project root:

```bash
uvx --from . ceedling-mcp
```

Or if published to PyPI:

```bash
uvx ceedling_mcp
```

### Install locally for development

```bash
uv venv
uv pip install .
ceedling-mcp
```

> **Note:** Editable installs (`-e`) are not supported with the `src/` → `ceedling_mcp` source remapping. Use `uv pip install .` instead.

### Use with the MCP Inspector

```bash
npx -y @modelcontextprotocol/inspector uvx --from . ceedling-mcp
```

## Client Configuration

### Gemini CLI / Claude Desktop

Add to your MCP config:

```json
{
  "mcpServers": {
    "ceedling": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/ceedling-mcp-server", "ceedling-mcp"]
    }
  }
}
```
## Output Examples

### All tests pass
```
✅ All 12 tests passed.
```

### Failures detected
```
❌ 2 of 12 tests FAILED (10 passed, 0 ignored)

--- Failure Details ---
  FAIL test/test_Foo.c:42 — test_Foo_should_ReturnOne
        Expected 1 Was 0
  FAIL test/test_Bar.c:18 — test_Bar_should_Initialize
        Expected TRUE Was FALSE
```

### Build error
```
🔴 BUILD ERRORS — tests did not execute
src/Foo.c:10: use of undeclared identifier 'x'
```

## License

MIT