🛡️ DevGuard-MCP

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:

# Using pip
pip install devguard-mcp

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

CLI Usage

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

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