# 🛡️ DevGuard-MCP

[![CI / Automated Testing](https://github.com/YoruichiYams/devguard-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/YoruichiYams/devguard-mcp/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/devguard-mcp.svg)](https://pypi.org/project/devguard-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/devguard-mcp.svg)](https://pypi.org/project/devguard-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**DevGuard-MCP** is a fast, local, deterministic developer workspace auditor, safe cleaner, advanced security secret scanner, and Model Context Protocol (MCP) server.

---

## ✨ Features

- **🔍 Workspace Auditing**: Detects reclaimable build artifacts, dependencies, and caches (`node_modules`, `.venv`, `.pytest_cache`, `__pycache__`, `target/`, `build/`, `dist/`, `.next/`, logs).
- **🔒 Advanced Security Engine**:
  - **High-Confidence Signatures**: Real-time regex pattern matching for AWS Access Keys (`AKIA...`), GitHub Tokens (`ghp_...`, `github_pat_...`), OpenAI API keys (`sk-...`), and Private RSA/SSH/EC keys.
  - **Shannon Information Entropy ($H$)**: Flags suspicious high-entropy pseudo-random tokens and passwords in configuration files.
  - **Automated Secret Masking**: Obfuscates sensitive credentials in logs and outputs (e.g. `sk-proj-abc1...****`).
- **📜 SQLite History & Delta Tracking**: Automatically logs workspace scans and cleanup events to a local SQLite database (`~/.devguard/history.db`) to track workspace hygiene changes over time.
- **🗑️ Safe Cleanup**: Built-in safety mechanisms with dry-run previews, OS Recycle Bin / Trash quarantine (`send2trash`), and protected system path verification.
- **📊 Rich CLI**: Beautiful terminal user interface powered by Typer and Rich (tables, progress bars, colored summaries, JSON outputs).
- **🤖 MCP Server**: Native Model Context Protocol support to let AI assistants (Claude, Antigravity, Cursor, etc.) safely audit workspaces and diagnose security hygiene.

---

## 🚀 Quick Start

### Installation

Install via pip or run directly using uvx:

```bash
# Using pip
pip install devguard-mcp

# Or run ephemerally with uvx
uvx devguard-mcp --help
```

### CLI Usage

```bash
# 🔍 Scan workspace for reclaimable artifacts
devguard scan

# 🔒 Run deep security audit (detects .env exposures and leaked API keys)
devguard audit

# 📜 View historical audit timeline and metric deltas
devguard history --limit 10

# 🗑️ Preview safe cleanup (dry-run simulation by default)
devguard clean --dry-run

# 🗑️ Clean specific artifacts into OS Recycle Bin
devguard clean --type node_modules --trash --execute
```

---

## 🤖 MCP Server Configuration

Configure DevGuard with your MCP client (Claude Desktop, Antigravity IDE, Cursor):

### Example `mcp_config.json`:

```json
{
  "mcpServers": {
    "devguard": {
      "command": "uvx",
      "args": ["devguard-mcp"]
    }
  }
}
```

### Available MCP Tools

- `scan_workspace(path, max_depth, artifact_types, min_size_mb)`: Discover cleanable artifacts and disk usage.
- `audit_workspace_secrets(path)`: Deep security audit detecting exposed credentials, `.env` files, and health scores.
- `get_audit_history(path, limit)`: Query historical scan reports and cleanup logs.
- `preview_cleanup(path, target_paths, artifact_types, older_than_days)`: Dry-run simulation of safe cleanup.
- `clean_workspace(path, target_paths, artifact_types, mode, dry_run)`: Clean artifacts with safety boundaries.
- `get_workspace_health(path)`: High-level overview of disk footprint and security health.

---

## 📄 License

MIT License © 2026 DevGuard Team