repo-guardian

MCP server exposing repo-health tools so any agent can guard repositories — detect pinned/unpinned dependencies, license compliance issues, hardcoded secrets, and dead code.

Features

• audit_dependencies — Parse pyproject.toml, requirements*.txt, and setup.py; flag exact pins that may miss security patches and dependencies with no version constraints.
• check_licenses — Scan declared dependency licenses for compliance issues (GPL/AGPL copyleft, unknown licenses, license incompatibilities with the project license).
• scan_for_secrets — Search for AWS keys, GitHub tokens, Slack tokens, Google API keys, Stripe keys, private key blocks, password assignments, bearer tokens, and high-entropy strings.
• find_dead_code — Detect unused Python imports, unused functions, and orphaned files.

All scanners are dependency-free (stdlib only) and never crash the MCP session — errors are returned as tool results.

Installation

pip install repo-guardian

For development:

git clone https://github.com/prem-the-dev/repo-guardian.git
cd repo-guardian
pip install -e ".[dev]"

Quickstart (Claude Desktop / Cursor / Windsurf)

Add to your MCP client config:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "repo-guardian": {
      "command": "python",
      "args": ["-m", "repo_guardian"]
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "repo-guardian": {
      "command": "python",
      "args": ["-m", "repo_guardian"]
    }
  }
}

Windsurf (.codeium/windsurf/mcp.json)

Same config as Cursor above.

Gemini CLI (gemini/.gemini/.mcp.json)

{
  "mcpServers": {
    "repo-guardian": {
      "command": "python",
      "args": ["-m", "repo_guardian"]
    }
  }
}

Hermes Agent

Copy the bundled mcp.json into your Hermes profile or merge it with your existing MCP server config:

cp mcp.json ~/.hermes/profiles/mcp-specialist/mcp.json
hermes profile reload

{
  "mcpServers": {
    "repo-guardian": {
      "command": "python",
      "args": ["-m", "repo_guardian"]
    }
  }
}

Usage Examples

Once configured, any agent can call the tools:

Audit Dependencies

audit_dependencies(path="/path/to/my-project")

Returns:

{
  "status": "ok",
  "scanned_files": ["pyproject.toml", "requirements.txt"],
  "total_dependencies": 4,
  "pinned_dependencies": [
    {"name": "Django", "version_spec": "==4.2.7", "classification": "pinned"}
  ],
  "potential_issues": [
    {"type": "pinned_exact", "dependency": "Django", "message": "..."}
  ]
}

Check Licenses

check_licenses(path="/path/to/my-project")

Returns:

{
  "status": "ok",
  "project_license": "MIT",
  "restricted_licenses": [],
  "unknown_licenses": [...],
  "potential_issues": []
}

Scan for Secrets

scan_for_secrets(path="/path/to/my-project", max_file_size_mb=5)

Returns:

{
  "status": "ok",
  "total_findings": 3,
  "findings": [
    {"type": "aws_access_key", "file": ".env", "line": 2, "confidence": "high"},
    {"type": "github_token", "file": "config.py", "line": 5, "confidence": "high"}
  ]
}

Find Dead Code

find_dead_code(path="/path/to/my-project")

Returns:

{
  "status": "ok",
  "unused_imports": [
    {"type": "unused_import", "file": "main.py", "line": 3, "name": "unused_module"}
  ],
  "unused_functions": [
    {"type": "unused_function", "file": "main.py", "line": 12, "name": "unused_function"}
  ],
  "orphaned_files": [...]
}

Running Tests

python -m pytest tests/ -v

Architecture

graph TD
    A[MCP Client<br/>Claude/Cursor/Windsurf/Hermes] -->|stdio JSON-RPC| B[MCP Server<br/>repo_guardian]
    B --> C[Tool Registry<br/>tools/list + tools/call]
    C --> D[audit_dependencies]
    C --> E[check_licenses]
    C --> F[scan_for_secrets]
    C --> G[find_dead_code]
    D --> D1[pyproject.toml parser]
    D --> D2[requirements.txt parser]
    D --> D3[setup.py parser]
    E --> E1[SPDX license DB<br/>offline lookup]
    E --> E2[Project license<br/>detect]
    F --> F1[Pattern matchers<br/>AWS/GH/Slack/etc]
    F --> F2[Shannon entropy<br/>high-entropy scan]
    G --> G1[AST parser<br/>imports + defs]
    G --> G2[Cross-file<br/>usage tracker]

License

MIT