<div align="center">

🛡️ VibeDefender

Security Knowledge MCP Server for AI Coding Agents

Guide your AI agents through professional security assessments with methodology, documentation, and step-by-step workflows covering OWASP Top 10 and beyond.

Installation • Features • Quick Start • Configuration • Documentation

</div>

---

🌟 Why VibeDefender?

Your AI coding agent (Claude Code, Cursor, etc.) already knows how to run commands. VibeDefender teaches it WHEN, WHY, and HOW to run security tools like a professional pentester.

Instead of guessing which security tools to run, your AI gets:

• 📚 Step-by-step security methodology - Professional assessment workflows
• 🎯 Plain English guidance - No security expertise required
• 🔧 Tool installation guides - Automated setup assistance
• 📖 Always-current documentation - Live tool documentation proxy
• ✅ OWASP Top 10 coverage - Industry-standard vulnerability detection

⭐ If you find VibeDefender useful, please star this repo! It helps others discover professional security testing for AI agents.

📦 Installation

Direct from GitHub (Recommended)

npx github:yunusj/VibeDefender-MCP

This automatically clones, installs dependencies, builds, and runs the MCP server.

Global Installation

npm install -g github:yunusj/VibeDefender-MCP
vibedefender-mcp

✨ Features

🎯 What Makes VibeDefender Different

✅ Knowledge-First Approach - Guides AI agents instead of executing tools directly ✅ 5 Pre-Built Security Workflows - Setup, full scan, pre-push check, live testing, URL scanning ✅ OWASP Top 10 Coverage - Comprehensive vulnerability detection (injection, XSS, auth, etc.) ✅ Mandatory Runtime Analysis - Not just static analysis - tests your running application ✅ Artifact Generation - Saves all scan results as JSON + markdown reports ✅ Zero Security Knowledge Required - Plain English explanations for non-security developers ✅ Tool Agnostic - Works with any MCP-compatible AI editor (Claude Code, Cursor, etc.)

🔧 Integrated Security Tools

• Trivy - CVE and dependency vulnerability scanning
• Semgrep - Static code analysis with 2000+ security rules
• Nuclei - Runtime security testing with template-based scanning
• Metasploit - Optional integration for discovery and exploitation

🤖 Supported AI Editors

Editor	Status	Notes
Claude Code	✅ Fully Supported	Native MCP support
Cursor	✅ Fully Supported	MCP configuration required
Claude Desktop	✅ Fully Supported	Config in claude_desktop_config.json
Google Antigravity	✅ Fully Supported	Same config as Claude Desktop

🧠 Philosophy

The MCP GUIDES, not executes.

Your AI agent (Claude Code, Cursor, etc.) already has the ability to run CLI commands. This MCP provides:

• 📋 Step-by-step methodology for security assessments
• 🔧 Installation guides for required tools
• 💬 Plain English explanations for non-technical users
• 📚 Documentation proxy for always-current tool docs

⚡ Quick Start

1. Install and configure (one-time setup):

{
  "mcpServers": {
    "vibedefender": {
      "command": "npx",
      "args": ["github:yunusj/VibeDefender-MCP"]
    }
  }
}

2. Talk to your AI agent in plain English:

What You Say	What Happens
💬 "Help me set up security scanning"	🔧 AI installs Trivy, Semgrep, Nuclei with guided steps
💬 "Scan my code for security issues"	🔍 Full scan: dependencies + code + runtime + artifacts
💬 "Check my code before I push"	⚡ Fast critical-only check (< 30 seconds)
💬 "Test my app on localhost"	🌐 Starts dev server + runs live security tests
💬 "Check this URL for vulnerabilities"	🎯 Tests specific URL with authorization check

3. Get professional security reports with actionable fixes:

✅ All scans saved to: security-scan-20241220-143022/
   ├── trivy-results.json      (Dependency vulnerabilities)
   ├── semgrep-results.json    (Code security issues)
   ├── nuclei-results.json     (Runtime vulnerabilities)
   └── REPORT.md               (Human-readable summary)

⚙️ Configuration

Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "vibedefender": {
      "command": "npx",
      "args": ["github:yunusj/VibeDefender-MCP"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vibedefender": {
      "command": "npx",
      "args": ["github:yunusj/VibeDefender-MCP"]
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings → Features → MCP):

{
  "mcpServers": {
    "vibedefender": {
      "command": "npx",
      "args": ["github:yunusj/VibeDefender-MCP"]
    }
  }
}

Google Antigravity

Same configuration as Claude Desktop.

🧪 Testing with MCP Inspector

Test the server before configuring in your editor:

npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector npx github:yunusj/VibeDefender-MCP

Expected: Web UI shows "Connected", lists all security:// resources and 5 workflow prompts.

🎯 Available Workflows

Workflow	Trigger Phrase	What It Does
🔧 setup	"Help me set up security scanning"	Checks installed tools, guides installation
🔍 scan	"Scan my code for security issues"	Full scan: static + runtime + artifacts
⚡ pre-push	"Check my code before I push"	Fast check: critical issues only (< 30s)
🌐 scan-live	"Test my app on localhost"	Starts dev server + runs live tests
🎯 scan-url	"Check this URL for vulnerabilities"	Tests specific URL (requires authorization)

🛠️ Required Tools

The MCP guides you through installing these (just say "help me set up"):

Tool	Purpose	Install (macOS)
🔍 Trivy	CVE/dependency scanning	brew install aquasecurity/trivy/trivy
📝 Semgrep	Static code analysis	brew install semgrep
🌐 Nuclei	Runtime testing (mandatory)	brew install nuclei

🎖️ Metasploit Integration

Metasploit Framework is integrated for both discovery (reconnaissance) and exploitation phases.

Setup

1. Install external Metasploit MCP server:

# Clone the Metasploit MCP repository
git clone https://github.com/your-org/MetasploitMCP ~/MetasploitMCP

2. Set environment variable (add to ~/.bashrc or ~/.zshrc):

export METASPLOIT_MCP_PATH="$HOME/MetasploitMCP/start_mcp.sh"

3. Verify installation:

npm run mcp:metasploit
# Should output: "Metasploit MCP Proxy running on stdio"

Usage

Discovery Phase (Automatic):

• Runs safe auxiliary modules for service detection
• Port scanning and version detection
• Correlates findings with CVE database
• No exploitation attempts

Exploitation Phase (Requires Approval):

• Executes exploits against validated vulnerabilities
• Requires explicit human approval
• Full session management and post-exploitation
• Evidence gathering only (read-only)

Safety

⚠️ CRITICAL: Authorization Required

• Only use on systems you own OR have written permission to test
• Unauthorized access to computer systems is illegal
• Discovery phase: Basic authorization sufficient
• Exploitation phase: Explicit approval required

📖 Documentation

• See security://methodology/exploitation for complete exploitation workflow
• See security://docs/metasploit for detailed tool usage
• Includes safety guidelines, workflow examples, and troubleshooting

📚 Available Resources

📋 Methodology Guides

Resource	Description
security://methodology/discovery	🔍 How to find attack surface
security://methodology/scanning	📊 What to scan, in what order
security://methodology/validation	✅ How to validate on live targets
security://methodology/reporting	📝 How to structure reports

📖 Reference Documentation

Resource	Description
security://reference/severity	🚨 What CRITICAL/HIGH/MEDIUM/LOW mean
security://reference/cwe-top-25	🐛 Common weakness types
security://reference/owasp-top-10	🛡️ OWASP vulnerability categories
security://reference/browser-options	🌐 Browser automation choices

🔧 Tool Documentation

Resource	Description
security://docs/overview	📚 Overview of all tools
security://docs/trivy	🔍 Trivy quick start
security://docs/semgrep	📝 Semgrep quick start
security://docs/nuclei	🌐 Nuclei quick start
security://docs/playwright	🎭 Playwright MCP info
security://docs/metasploit	🎖️ Metasploit basics

💡 Example Workflows

First Time Setup

You: Help me set up security scanning

AI: I'll check what tools you have installed...
    [Runs version checks]

    You're missing Trivy and Semgrep. Let me help you install them.

    Trivy checks your dependencies for known vulnerabilities.
    Run this to install: brew install aquasecurity/trivy/trivy
    ...

Before Pushing Code

You: Check my code before I push

AI: Running quick pre-push security check...
    [Runs trivy + semgrep for CRITICAL issues only]

    ✅ All clear! No critical security issues found. Safe to push.

    For a comprehensive scan including runtime testing, use the 'scan' workflow.

Full Security Scan

You: Scan my code for security issues

AI: I see this is a Node.js project using Express.

    First, checking for known vulnerabilities in dependencies...
    [Runs trivy]

    Found 3 critical issues in your packages:
    1. lodash < 4.17.21 - allows prototype pollution
       Fix: npm update lodash
    ...

📁 Project Structure

src/
├── index.ts              # Main MCP server entry point
├── resources/
│   ├── static.ts         # Bundled methodology & references
│   └── dynamic.ts        # Tool documentation with search guidance
└── prompts/
    └── workflows.ts      # 5 user-friendly workflow prompts

🎨 Design Decisions

1. 🚫 No execution tools - AI agents already have CLI access. We provide knowledge.
2. 💬 Plain English - Everything explained for non-technical users.
3. 📋 Step-by-step - Prompts tell the AI exactly what to do at each step.
4. 📖 Documentation proxy - Search patterns for always-current tool docs.
5. 📦 Minimal files - 4 files total, easy to understand and maintain.
6. 🌐 GitHub-based distribution - No npm publish, direct from source via npx.

🌐 Browser Automation Options

For live testing that needs a browser:

Option	When to Use
Playwright MCP	Claude Code, Cursor, most IDEs
Browser Agent	Google Antigravity IDE (built-in)
Puppeteer	If already in project

🔧 Troubleshooting

Build Errors

If you see TypeScript compilation errors when installing from GitHub:

npm cache clean --force
npx github:yunusj/VibeDefender-MCP

MCP Server Not Connecting

1. Test with MCP Inspector first (see "Testing" section above)
2. Check Node.js version: node --version (requires >= 22.0.0)
3. Verify the server runs standalone:

   npx github:yunusj/VibeDefender-MCP
   # Should output: "Security Knowledge MCP server running on stdio"
   

4. Check editor configuration file syntax (valid JSON)
5. Restart your AI editor after configuration changes

Permission Errors

If you get EACCES errors:

# On Unix-like systems, the shebang should make it executable
# If not, manually set permissions on global install:
chmod +x $(which vibedefender-mcp)

Update to Latest Version

npm cache clean --force
npx github:yunusj/VibeDefender-MCP

# Or for global install
npm uninstall -g vibedefender-mcp
npm install -g github:yunusj/VibeDefender-MCP

⚠️ Security Notice

• ✅ Only scan systems you are authorized to test
• 🔒 Live validation (scan-url, scan-live) requires explicit authorization
• 🤝 The AI will ask for confirmation before testing URLs
• 📄 Always get written permission before security testing
• 🛡️ Follow responsible disclosure practices

---

<div align="center">

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE for details

⭐ Show Your Support

If VibeDefender helps secure your code, please star this repository!

Made with 🛡️ by security professionals, for developers

</div>