Adversary MCP Server

Adversary MCP Server

Features

• AI-Powered Analysis - OpenAI/Anthropic LLM integration for intelligent vulnerability detection
• Smart Validation - Reduces false positives with LLM validation (70% confidence threshold)
• Multi-Engine Scanning - Combines Semgrep static analysis & AI analysis
• Automatic Persistence - Auto-saves scan results in JSON, Markdown, and CSV formats
• MCP Integration - Native support for Claude Code and Cursor IDE
• Comprehensive CLI - Full command-line interface with all scanning capabilities
• Rich Telemetry - Comprehensive tracking with dashboard visualization

Installation

Prerequisites

• Python 3.10+ (tested on 3.11, 3.12, 3.13)
• Semgrep - Static analysis engine (install)

Quick Install

# Install python uv
brew install uv

# Install Semgrep (required)
brew install semgrep  # macOS
# or
pip install semgrep   # Other platforms

# Install Adversary MCP Server
uv pip install adversary-mcp-server

Verify Installation

adv --version
adv status

Quick Start

1. Configure Security Engine

# Initial setup (interactive)
adv configure setup

# Or configure directly with options
adv configure --llm-provider openai --llm-api-key $OPENAI_API_KEY
adv configure --llm-provider anthropic --llm-api-key $ANTHROPIC_API_KEY

# Check configuration status
adv status

2. Run Your First Scan

# Scan a single file (basic)
adv scan-file path/to/file.py

# Scan with AI analysis and validation (recommended)
adv scan-file path/to/file.py --use-llm --use-validation

# Scan entire directory
adv scan-folder ./src --use-llm --use-validation

# Scan code snippet directly
adv scan-code "print('Hello World')" --language python

3. View Comprehensive Dashboard

# Launch interactive telemetry dashboard
adv dashboard

Claude Code Setup

Configure MCP Server

Create or update ~/.config/claude-code/mcp.json:

{
    "mcpServers": {
        "adversary": {
            "command": "uvx",
            "args": ["adversary-mcp-server"]
        }
    }
}

Using MCP Tools in Claude Code

Once configured, these tools are available in Claude Code:

• Ask Claude: "Scan this file for security issues using adv_scan_file"
• Ask Claude: "Check for vulnerabilities in the current project with adv_scan_folder"
• Ask Claude: "Analyze this code snippet for security issues using adv_scan_code"

Cursor IDE Setup

Configure MCP Server

Create .cursor/mcp.json in your project:

{
    "mcpServers": {
        "adversary": {
            "command": "uvx",
            "args": ["adversary-mcp-server"]
        }
    }
}

{
  "mcpServers": {
    "adversary": {
      "command": "python",
      "args": ["-m", "adversary_mcp_server.sync_main"]
    }
  }
}

{
  "mcpServers": {
    "adversary": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "adversary_mcp_server.sync_main"]
    }
  }
}

Using MCP Tools in Cursor

Once configured, these tools are available in Cursor's chat:

• Ask Cursor: "Scan this file for security issues using adv_scan_file"
• Ask Cursor: "Check for vulnerabilities in the current project with adv_scan_folder"
• Ask Cursor: "Analyze this code snippet for security issues using adv_scan_code"

CLI Usage

Basic Commands

# Configure the scanner
adv configure setup

# Check status and configuration
adv status

# Scan individual files
adv scan-file <file-path> [options]

# Scan directories
adv scan-folder <directory-path> [options]

# Scan code snippets
adv scan-code <code-content> --language <lang> [options]

# Launch comprehensive telemetry dashboard
adv dashboard

Scanning Examples

# Basic file scan
adv scan-file app.py

# Scan with AI analysis and validation (recommended)
adv scan-file app.py --use-llm --use-validation

# Directory scan with full analysis
adv scan-folder ./src --use-llm --use-validation

# Code snippet scan
adv scan-code "SELECT * FROM users WHERE id = ?" --language sql

# Scan with specific severity threshold
adv scan-file app.py --severity high

# Output results in different formats
adv scan-file app.py --output-format json --output-file results.json
adv scan-file app.py --output-format markdown --verbose

Configuration Commands

# Interactive setup
adv configure setup

# Direct configuration
adv configure --llm-provider openai --llm-api-key your-key
adv configure --llm-provider anthropic --llm-api-key your-key

# Reset configuration
adv configure reset

# Check current configuration
adv status

Available Options

--use-llm / --no-llm              # Enable/disable AI analysis
--use-validation / --no-validation # Enable/disable false positive filtering
--use-semgrep / --no-semgrep      # Enable/disable Semgrep analysis (default: true)
--severity [low|medium|high|critical] # Minimum severity threshold
--output-format [json|markdown|csv]   # Output format for results
--output-file <file>              # Save results to specific file
--verbose                         # Verbose output with detailed information

MCP Tools

Available Tools

MCP Tool Examples

// In Claude Code or Cursor, ask the AI assistant:

// Scan current file with full analysis
"Use adv_scan_file to check this file for security issues with LLM validation"

// Scan directory with specific options
"Run adv_scan_folder on the src directory with severity threshold of high"

// Scan code snippet
"Use adv_scan_code to analyze this SQL query for injection vulnerabilities"

// Check scanner status
"Use adv_get_status to see what scan engines are available"

Automatic Result Persistence

All MCP tools automatically save scan results in multiple formats:

• JSON: .adversary.json - Machine-readable results with full metadata
• Markdown: .adversary.md - Human-readable report with remediation guidance
• CSV: .adversary.csv - Spreadsheet-compatible format for analysis

Results are automatically placed alongside scanned files/directories with intelligent conflict resolution.

Dashboard & Telemetry

Comprehensive HTML Dashboard

The scanner includes a rich web-based dashboard for comprehensive telemetry analysis:

# Launch interactive dashboard
adv dashboard

Dashboard Features:

• MCP Tool Analytics - Track tool usage, success rates, and performance
• Scan Engine Metrics - Monitor Semgrep, LLM, and validation performance
• Threat Analysis - Categorize findings by severity and confidence
• System Health - Performance monitoring and statistics
• Language Analysis - Track scanning efficiency by programming language
• Recent Activity - Timeline view of recent scans and operations

Telemetry System

Adversary MCP Server includes comprehensive telemetry tracking:

• Automatic Collection - All MCP tools, CLI commands, and scan operations are automatically tracked
• Local Storage - All data stored locally, never transmitted to external services
• Zero Configuration - Telemetry works out-of-the-box with no setup required
• Performance Insights - Identify bottlenecks and optimize scanning workflows
• Usage Analytics - Understand tool usage patterns and effectiveness

Architecture

Implementation

Adversary MCP Server is built using Clean Architecture principles with Domain-Driven Design (DDD), ensuring separation of concerns, maintainability, and testability.

graph TB
    subgraph "🖥️ **Presentation Layer**"
        A[Cursor IDE]
        B[CLI Interface]
        C[Web Dashboard]
    end

    subgraph "🔧 **Application Layer**"
        D[MCP Server]
        E[CLI Commands]
        F[Adapters]
        subgraph "Adapters"
            F1[SemgrepAdapter]
            F2[LLMAdapter]
            F3[Validati

---

*README truncated. [View full README on GitHub](https://github.com/brettbergin/adversary-mcp-server).*