# 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

```bash
pip install repo-guardian
```

For development:

```bash
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`)

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

### Cursor (`.cursor/mcp.json`)

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

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

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

```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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

```bash
python -m pytest tests/ -v
```

## Architecture

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