# 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.
[](https://opensource.org/licenses/MIT)
[](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.
