marcelkurvers/local-testing-agent

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.

🌟 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

📦 Installation

Prerequisites

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

Setup

1. Clone the repository:

git clone https://github.com/marcelkurvers/local-testing-agent.git
cd local-testing-agent

2. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Install language-specific test frameworks (optional, based on your needs):

# 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:

{
  "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.

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.

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.

full_phase2_pipeline(project_root=".")

Standalone Usage

Run the MCP server directly:

python testing_agent.py

Or use the Phase 1 testing engine:

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:

# 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 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 for MCP protocol support
• Designed for use with Claude Code
• Compatible with Google Gravity (Antigravity)

📧 Contact

Marcel Kurvers - @marcelkurvers

Project Link: https://github.com/marcelkurvers/local-testing-agent

Note: This project is actively developed. See for upcoming features and enhancements.