Adversary MCP Server

🔒 Clean Architecture security analysis with AI-powered vulnerability detection and validation

We think about your vulns so you don't have to.

Installation • Quick Start • Claude Code Setup • Cursor Setup • CLI Usage • MCP Tools • Architecture

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"]
        }
    }
}

Using pip installation:

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

For development:

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

Tool	Description	Example Usage
`adv_scan_code`	Scan code snippets directly	"Scan this code for vulnerabilities"
`adv_scan_file`	Scan specific files with full analysis	"Check security issues in auth.py"
`adv_scan_folder`	Scan entire directories recursively	"Analyze the src folder for vulnerabilities"
`adv_get_status`	Check server status and capabilities	"Is the security scanner configured?"
`adv_get_version`	Get server version information	"What version is running?"
`adv_mark_false_positive`	Mark findings as false positives	"Mark finding XYZ as false positive"
`adv_unmark_false_positive`	Remove false positive marking	"Unmark finding ABC as false positive"

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.

New Architecture Benefits

Separation of Concern: Business logic isolated from infrastructure
Dependency Inversion: High-level modules don't depend on low-level details
Testability: Pure domain logic enables comprehensive unit testing
Maintainability: Changes to infrastructure don't affect business rules
Scalability: New scan strategies and validators easily pluggable
Type Safety: Rich domain models with comprehensive validation

Architectural Layers

Domain Layer (Core Business Logic)

Entities: ScanRequest, ScanResult, ThreatMatch - Rich business objects
Value Objects: ScanContext, SeverityLevel, ConfidenceScore, FilePath - Immutable domain concepts
Domain Services: ScanOrchestrator, ThreatAggregator, ValidationService - Pure business orchestration
Interfaces: IScanStrategy, IValidationStrategy - Contracts for external dependencies

Application Layer (Use Cases & Coordination)

MCP Server: Handles Cursor IDE integration via Model Context Protocol
CLI Commands: Command-line interface for security scanning operations
Adapters: Bridge domain interfaces with infrastructure implementations
- SemgrepAdapter - Adapts Semgrep scanner to domain IScanStrategy
- LLMAdapter - Adapts LLM scanner to domain IScanStrategy
- ValidationAdapter - Adapts LLM validator to domain IValidationStrategy

Infrastructure Layer (External Services)

SemgrepScanner: Static analysis engine integration
LLMScanner: AI-powered vulnerability detection
LLMValidator: False positive filtering with LLM analysis
SQLAlchemy Database: Persistent storage for telemetry and results
File System: Code file access and Git operations
Telemetry System: Performance tracking and dashboard generation

Data Flow Architecture

Input Processing: ScanRequest created with ScanContext (file/directory/code)
Domain Orchestration: ScanOrchestrator coordinates scanning strategies
Parallel Analysis: Multiple IScanStrategy implementations execute concurrently
Threat Aggregation: ThreatAggregator deduplicates and merges findings
Validation Pipeline: ValidationService filters false positives using AI
Result Assembly: Rich ScanResult with comprehensive metadata
Presentation: Results formatted for CLI, MCP, or dashboard consumption

Key Design Patterns

Strategy Pattern: Pluggable scan and validation strategies
Adapter Pattern: Infrastructure integration without domain coupling
Factory Pattern: Bootstrap and dependency injection
Value Objects: Immutable domain concepts with validation
Domain Services: Complex business logic coordination

How It Works

Multi-Engine Analysis: Parallel execution of Semgrep static analysis and LLM AI analysis
Intelligent Validation: LLM-powered false positive reduction with confidence scoring
Threat Aggregation: Smart deduplication and merging using fingerprint and proximity strategies
Performance Optimization: Async processing, caching, and batch operations
Comprehensive Telemetry: SQLAlchemy-backed metrics with interactive Chart.js dashboard
Git Integration: Diff-aware scanning for efficient CI/CD pipeline integration
Zero-Config Operation: Auto-discovery and configuration with sensible defaults

Configuration

Environment Variables

# Core settings (optional)
ADVERSARY_LOG_LEVEL=INFO           # Set logging level
ADVERSARY_WORKSPACE_ROOT=/path     # Override workspace detection

Configuration File

Settings are automatically managed through the CLI and stored in ~/.adversary/config.json:

# Interactive configuration
adv configure setup

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

# Check current settings
adv status

CI/CD Integration

GitHub Actions

name: Security Scan
on: [pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          pip install adversary-mcp-server

      - name: Run security scan
        run: |
          adv scan-directory . \
            --use-llm \
            --use-validation \
            --severity medium \
            --output-format json \
            --output-file scan-results.json

      - name: Upload results
        uses: actions/upload-artifact@v3
        with:
          name: security-scan
          path: scan-results.json

Development

Setup Development Environment

# Clone repository
git clone https://github.com/brettbergin/adversary-mcp-server.git
cd adversary-mcp-server

# Create virtual environment (using uv or standard venv)
source .venv/bin/activate  # Activate existing venv

# Install in development mode
uv pip install -e .[dev]

# Run tests
make test

Running Tests

# Full test suite with coverage
make test

# Specific test categories
make test-unit          # Unit tests only
make test-integration   # Integration tests only
make test-security      # Security tests only

# Code quality checks

make format             # Auto-format code
make mypy               # Type checking
make lint               # Run all linting
make pre-commit         # Run same pre-commit in git commits.

Support

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

View all tools

A security-focused server that integrates with Cursor IDE to provide real-time vulnerability detection, exploit generation, and security insights during software development.

Related MCP Servers

AI Development Assistant MCP Server
kleneway
-
security
A
license
-
quality
An AI-powered development toolkit for Cursor providing intelligent coding assistance through advanced reasoning, UI screenshot analysis, and code review tools.
Last updated -
649
333
MIT License
Laravel Helpers MCP
jsonallen
-
security
A
license
-
quality
A collection of Laravel helper tools for integration with Cursor IDE, providing features like log viewing, error searching, artisan command execution, and model information display directly within the editor.
Last updated -
12
MIT License
MCP Montano Server
lucasmontano
-
security
F
license
-
quality
A TypeScript-based server project that can be integrated with Cursor IDE as an MCP (Model Control Protocol) server, enabling enhanced development capabilities.
Last updated -
137
MCP Server Pentest
9olidity
A
security
A
license
A
quality
A security testing tool that enables automated vulnerability detection including XSS and SQL injection, along with comprehensive browser interaction capabilities for web application penetration testing.
Last updated -
12
611
19
MIT License

View all related MCP servers

Appeared in Searches

A server that scans projects for security vulnerabilities and recommends fixes