# Local Testing Agent MCP Server

A comprehensive multi-language testing automation MCP (Model Context Protocol) server that enables AI assistants like Claude to discover, plan, and execute tests across multiple programming languages.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

## 🌟 Features

- **Multi-Language Support**: Automatically detect and test projects in 6 programming languages
- **Smart Test Discovery**: Comprehensive pattern matching for test files across different frameworks
- **Automated Test Execution**: Run language-specific test suites with proper frameworks
- **AI-Powered Test Planning**: Generate intelligent test plans for Claude and other AI assistants
- **Comprehensive Reporting**: JSON and Markdown reports with coverage maps
- **MCP Protocol**: Seamless integration with Claude Code, Gravity, and other MCP clients

## 🔧 Supported Languages & Frameworks

| Language | File Extensions | Test Framework | Test Patterns |
|----------|----------------|----------------|---------------|
| **Python** | `.py` | pytest | `test_*.py`, `*_test.py`, `tests/` |
| **JavaScript/TypeScript** | `.js`, `.jsx`, `.ts`, `.tsx` | jest | `*.test.js`, `*.spec.ts`, `__tests__/` |
| **Go** | `.go` | go test | `*_test.go` |
| **Rust** | `.rs` | cargo test | `*_test.rs`, `tests/` |
| **Java** | `.java` | Maven/Gradle | `*Test.java`, `test/` |
| **Ruby** | `.rb` | RSpec/Minitest | `*_spec.rb`, `*_test.rb`, `spec/` |

## 📦 Installation

### Prerequisites

- Python 3.11 or higher
- pip (Python package installer)

### Setup

1. Clone the repository:
```bash
git clone https://github.com/marcelkurvers/local-testing-agent.git
cd local-testing-agent
```

2. Create and activate a virtual environment:
```bash
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
```

4. Install language-specific test frameworks (optional, based on your needs):
```bash
# Python (already included)
pip install pytest

# JavaScript/TypeScript
npm install -g jest

# Go (already included with Go installation)
# Rust (already included with Cargo)
# Java - Maven or Gradle
# Ruby
gem install rspec
```

## 🚀 Usage

### As an MCP Server

#### With Claude Code

The server auto-discovers when running Claude Code. No additional configuration needed.

#### With Gravity (Google Antigravity)

1. Configure in `~/.gemini/antigravity/mcp_config.json`:
```json
{
  "mcpServers": {
    "local-testing-agent": {
      "command": "/path/to/local-testing-agent/.venv/bin/python",
      "args": [
        "/path/to/local-testing-agent/testing_agent.py"
      ],
      "env": {}
    }
  }
}
```

2. Restart Gravity completely to register the MCP server.

### MCP Tools Available

The server exposes three MCP tools:

#### 1. `scan_repository`
Scans a project directory and detects source files and test files for all supported languages.

```python
scan_repository(project_root=".")
```

**Returns:**
- Snapshot file (`.mcp_scan_snapshot.json`)
- Test plan file (`TEST_PLAN_AI.md`)
- Language detection results

#### 2. `run_all_tests`
Runs all detected tests for all languages with test files.

```python
run_all_tests(project_root=".")
```

**Returns:**
- Test report (`.mcp_test_report.json`)
- Coverage map (`TEST_COVERAGE_MAP.md`)
- Execution results for each framework

#### 3. `full_phase2_pipeline`
Convenience tool that runs scan → plan → test → coverage in one call.

```python
full_phase2_pipeline(project_root=".")
```

### Standalone Usage

Run the MCP server directly:
```bash
python testing_agent.py
```

Or use the Phase 1 testing engine:
```bash
python -c "from testing_engine.pipeline import full_test_pipeline; full_test_pipeline('.')"
```

## 📊 Output Files

The MCP server generates several files:

- **`.mcp_scan_snapshot.json`**: Complete scan results with all detected files
- **`.mcp_test_report.json`**: Test execution results with pass/fail status
- **`TEST_COVERAGE_MAP.md`**: Human-readable coverage summary
- **`TEST_PLAN_AI.md`**: AI-generated test plan with suggestions

## 🏗️ Architecture

### Project Structure

```
local-testing-agent/
├── testing_agent.py           # Phase 2 MCP server (main)
├── testing_engine/            # Phase 1 implementation
│   ├── file_scanner.py        # File discovery
│   ├── unit_test_generator.py # Test generation
│   └── pipeline.py            # Test orchestration
├── tests/                     # Test suite
│   ├── test_smoke.py         # Smoke tests
│   └── unit/                 # Unit tests
├── CLAUDE.md                  # Development guide
├── IMPROVEMENT_PLAN.md        # Roadmap
└── requirements.txt           # Dependencies
```

### Key Components

1. **Language Detection** (`detect_languages`): Walks the repository once and identifies all source and test files
2. **Test Planning** (`plan_test_runs`): Creates execution plans based on detected files
3. **Test Execution** (`execute_planned_runs`): Runs language-specific test commands
4. **Report Generation**: Produces JSON and Markdown reports

## 🔍 Test Detection Patterns

The agent uses comprehensive patterns to detect test files:

- **Directory-based**: `tests/`, `test/`, `spec/`, `__tests__/`
- **Naming conventions**: `test_*.py`, `*_test.go`, `*.spec.ts`, `*Test.java`
- **Framework-specific**: Adapts to Jest, RSpec, Minitest, etc.

## ⚙️ Configuration

### Excluded Directories

The following directories are automatically excluded from scanning:

- Virtual environments: `.venv`, `venv`, `site-packages`
- Version control: `.git`
- Build artifacts: `dist`, `build`, `out`
- Caches: `__pycache__`, `.cache`, `.pytest_cache`, `coverage`
- IDE/Editor: `.vscode`, `.idea`
- Framework-specific: `node_modules`, `.next`, `.turbo`, `.mcp`

### Customization

See `CLAUDE.md` for detailed development guidelines and customization options.

## 🧪 Testing

Run the test suite:
```bash
# Activate virtual environment
source .venv/bin/activate

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_smoke.py
```

## 🗺️ Roadmap

See [IMPROVEMENT_PLAN.md](IMPROVEMENT_PLAN.md) for the complete phased improvement plan.

### Completed ✅
- Phase 1: Multi-language support (Python, JS/TS, Go, Rust, Java, Ruby)
- Comprehensive test detection patterns
- MCP protocol integration

### In Progress 🚧
- Phase 2: Parallel test execution
- Phase 2: Coverage collection integration
- Phase 3: Comprehensive test suite

### Planned 📋
- PHP and C# language support
- Smart framework detection
- Configuration system
- Watch mode
- CI/CD integration helpers

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) for MCP protocol support
- Designed for use with [Claude Code](https://claude.ai/code)
- Compatible with Google Gravity (Antigravity)

## 📧 Contact

Marcel Kurvers - [@marcelkurvers](https://github.com/marcelkurvers)

Project Link: [https://github.com/marcelkurvers/local-testing-agent](https://github.com/marcelkurvers/local-testing-agent)

---

**Note**: This project is actively developed. See [IMPROVEMENT_PLAN.md](IMPROVEMENT_PLAN.md) for upcoming features and enhancements.