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)

# 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

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

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

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