# GitHub Auditor MCP Server

**A Professional-Grade Heritage Clean-Up Tool for Git Repositories.**

The **GitHub Auditor** is a Model Context Protocol (MCP) server designed to professionalize legacy codebases. It transforms "trial and error" commit histories into structured, clean, and secure repositories ready for public deployment or enterprise use.

## Features

### 🛡️ Security & Integrity

- **`audit_secrets`**: Deep-scans commit history for high-entropy strings, API keys, and passwords using `trufflehog`.
- **`audit_gitignore`**: Identifies tracked files that should be ignored (e.g., binaries, system logs, `.env` files) and validates `.gitignore` completeness.
- **`setup_pre_commit_hooks`**: Installs industry-standard pre-commit hooks to prevent future leaks.

### 🧹 History Sanitization

- **`clean_repository_history`**: The core orchestrator. Automatically creates a sandboxed `mcp-audit-branch` to ensure safety before any destructive operations.
- **`purge_history`**: permanently removes sensitive data or large files from the entire git history using `git-filter-repo`.
- **`scrub_ignored_files`**: Retroactively removes files from tracking that match current `.gitignore` rules.

### 🧠 Semantic Rewriting

- **`squash_noise_commits`**: Intelligently groups "noisy" commits (e.g., "fix typo", "try again") based on time windows, authorship, and goal heurisitics.
- **`generate_semantic_history`**: Analyzes diffs and generates professional **Conventional Commits** messages.

### 📊 Reporting

- **`generate_cleanup_report`**: visualization of code reduction and commit cleanup (Before vs. After).
- **`generate_security_audit_report`**: Generates a signed markdown certificate validating the repository's security posture.

## Installation

### Prerequisites

**For Docker (Recommended):**

- Docker installed and running
- `python3` (for generating configuration and local testing)

**For Manual Installation:**

- Python 3.10+
- `git`
- `git-filter-repo` (System install usually required: `pip install git-filter-repo`)

### Setup

**Option A: Docker (Recommended)**

```bash
# Clone the repository
git clone https://github.com/westkevin12/repo-mcp.git
cd repo-mcp

# Build the Docker image
docker build -t mcp-auditor .

# Generate your local MCP configuration
python3 generate_config.py
```

The `generate_config.py` script automatically creates an `antigravity_config_snippet.json` file tailored to the absolute path of your local machine.
Copy the contents of this generated file into your MCP Client configuration file (e.g., your Claude Desktop `claude_desktop_config.json`).

**Option B: Manual Installation**

```bash
# Clone the repository
git clone https://github.com/westkevin12/repo-mcp.git
cd repo-mcp

# Install dependencies (will use pyproject.toml)
pip install .
```

## Usage

**Running via Docker (Recommended)**
Once configured in your MCP client, the tool will automatically use the `start_mcp_server.sh` script to run an isolated, containerized session safe from your host system.

**Running Manually**
Start the MCP server to use it directly with your AI agent (Claude Desktop, Cursor, etc.):

```bash
# Start the server
mcp start git_auditor_mcp.py
```

### Troubleshooting / Testing

You can manually verify that the server script is working correctly by running the handshake tester:

```bash
python3 test_handshake.py
```

### Example Agent Prompt

> "I want to open source this old project. Run the GitHub Auditor. First, scan for any secrets in the history. If clean, audit the gitignore and remove any tracked garbage files. Finally, look at the last 100 commits and propose a squash plan to hide my trial-and-error."

## License

This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the [LICENSE](LICENSE) file for details.

By using or contributing to this project, you agree that any modifications or derivative works will also be open-source under the same terms.

## Contact

**Kevin West**  
*West@DigitalServerHost.com*  
[DigitalServerHost.com](https://digitalserverhost.com)