Skip to main content
Glama

Adversary MCP Server

by brettbergin

Adversary MCP Server

PyPI version Python 3.10+ License: MIT Tests Coverage Version

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

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

InstallationQuick StartClaude Code SetupCursor SetupCLI UsageMCP ToolsArchitecture


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.

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[ValidationAdapter] end end subgraph "🏛️ **Domain Layer (Business Logic)**" subgraph "Entities" G[ScanRequest] H[ScanResult] I[ThreatMatch] end subgraph "Value Objects" J[ScanContext] K[SeverityLevel] L[ConfidenceScore] M[FilePath] end subgraph "Domain Services" N[ScanOrchestrator] O[ThreatAggregator] P[ValidationService] end subgraph "Interfaces" Q[IScanStrategy] R[IValidationStrategy] end end subgraph "⚙️ **Infrastructure Layer**" S[SemgrepScanner] T[LLMScanner] U[LLMValidator] V[SQLAlchemy Database] W[File System] X[Git Operations] Y[Telemetry System] end A -->|MCP Protocol| D B --> E C --> Y D --> F E --> F F1 --> N F2 --> N F3 --> P N --> O N --> P G --> N H --> O I --> P J --> G K --> I L --> I M --> G N --> Q P --> R F1 -.-> S F2 -.-> T F3 -.-> U S --> W T --> W U --> V Y --> V X --> W style N fill:#e1f5fe,stroke:#0277bd,stroke-width:3px style O fill:#e1f5fe,stroke:#0277bd,stroke-width:3px style P fill:#e1f5fe,stroke:#0277bd,stroke-width:3px style G fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style H fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style I fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style F1 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px style F2 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px style F3 fill:#e8f5e8,stroke:#388e3c,stroke-width:2px

New Architecture Benefits

  1. Separation of Concern: Business logic isolated from infrastructure

  2. Dependency Inversion: High-level modules don't depend on low-level details

  3. Testability: Pure domain logic enables comprehensive unit testing

  4. Maintainability: Changes to infrastructure don't affect business rules

  5. Scalability: New scan strategies and validators easily pluggable

  6. 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

  1. Input Processing: ScanRequest created with ScanContext (file/directory/code)

  2. Domain Orchestration: ScanOrchestrator coordinates scanning strategies

  3. Parallel Analysis: Multiple IScanStrategy implementations execute concurrently

  4. Threat Aggregation: ThreatAggregator deduplicates and merges findings

  5. Validation Pipeline: ValidationService filters false positives using AI

  6. Result Assembly: Rich ScanResult with comprehensive metadata

  7. 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

  1. Multi-Engine Analysis: Parallel execution of Semgrep static analysis and LLM AI analysis

  2. Intelligent Validation: LLM-powered false positive reduction with confidence scoring

  3. Threat Aggregation: Smart deduplication and merging using fingerprint and proximity strategies

  4. Performance Optimization: Async processing, caching, and batch operations

  5. Comprehensive Telemetry: SQLAlchemy-backed metrics with interactive Chart.js dashboard

  6. Git Integration: Diff-aware scanning for efficient CI/CD pipeline integration

  7. 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.


Related MCP Servers

  • -
    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 -
    504
    336
    MIT License
  • -
    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
  • -
    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 -
    139
  • 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
    567
    20
    MIT License

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/brettbergin/adversary-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server