Skip to main content
Glama
brettbergin

Adversary MCP Server

by brettbergin
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Hybrid

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.

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

Related MCP server: Orcho MCP Server

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.

Available Tools

7 tools
adv_get_statusB

Get comprehensive server status including session management capabilities, active sessions, and cache statistics

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what information is retrieved but doesn't describe how the data is formatted, whether it's real-time or cached, potential rate limits, authentication requirements, or error conditions. For a status tool with zero annotation coverage, this leaves significant gaps in understanding its operational behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose ('Get comprehensive server status') and lists key components without redundancy. Every word earns its place, making it easy for an agent to parse quickly. There's no wasted verbiage or structural issues.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (low, with no parameters) and lack of annotations/output schema, the description is minimally adequate. It covers what the tool does but lacks behavioral details (e.g., response format, performance characteristics). For a status tool, more context on data freshness or structure would be helpful, but it meets the basic threshold for a simple read operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and schema description coverage is 100% (empty schema). The description doesn't need to explain parameters, so it appropriately focuses on the tool's purpose. A baseline of 4 is justified since no parameter documentation is required, and the description doesn't introduce unnecessary parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and resource ('comprehensive server status'), specifying three components: session management capabilities, active sessions, and cache statistics. It distinguishes from siblings like 'adv_get_version' by focusing on operational status rather than version information. However, it doesn't explicitly differentiate from other status-related tools (none exist in the sibling list), so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, timing considerations, or comparisons to sibling tools like 'adv_scan_code' or 'adv_scan_file'. The agent must infer usage from the purpose alone, which is insufficient for optimal tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

adv_get_versionB

Get server version information

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. While 'Get' implies a read operation, the description doesn't disclose any behavioral traits - no information about authentication requirements, rate limits, error conditions, or what format the version information returns. For a tool with zero annotation coverage, this is insufficient disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise at just three words. It's front-loaded with the essential information - what the tool does - with zero wasted words. Every word earns its place in communicating the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 0-parameter read operation with no output schema, the description is minimally complete. It tells what the tool does but lacks important context about return format, authentication, or differentiation from similar tools. Without annotations or output schema, the agent has incomplete information about what to expect from this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and the schema already documents this completely. No additional parameter information is needed or provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get server version information' clearly states the verb ('Get') and resource ('server version information'), making the purpose immediately understandable. However, it doesn't distinguish this from sibling tools like 'adv_get_status' - both appear to retrieve server information but for different aspects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With siblings like 'adv_get_status' that also retrieve server information, the agent has no indication whether this should be used for version checking, system monitoring, or other contexts. No prerequisites or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

adv_mark_false_positiveC

Mark a finding as a false positive

ParametersJSON Schema
NameRequiredDescriptionDefault
finding_uuidYesUUID of the finding to mark as false positive
reasonNoReason for marking as false positive
marked_byNoWho marked it as false positiveuser
adversary_file_pathNoPath to .adversary.json file.adversary.json

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Mark') but doesn't explain what this entails—whether it's a write operation, requires permissions, affects the finding's status permanently, or has side effects. This is a significant gap for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste—it directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a mutation tool (marking findings) with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, side effects, or what happens after marking, nor does it explain the return value. This leaves gaps that could hinder correct tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds no additional meaning beyond what the schema provides, such as explaining parameter interactions or usage examples. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Mark') and resource ('a finding') with the specific action ('as a false positive'), making the purpose unambiguous. However, it doesn't explicitly differentiate from its sibling 'adv_unmark_false_positive' beyond the opposite action, missing a direct comparison that would elevate it to a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'adv_unmark_false_positive' or other scanning tools. It lacks context about prerequisites (e.g., after a scan) or exclusions, leaving the agent to infer usage based on the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

adv_scan_codeB

Scan code content for security vulnerabilities using Clean Architecture. Automatically uses session-aware analysis with project context when available.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesSource code to analyze
languageYesProgramming language of the code
use_semgrepNoEnable Semgrep analysis
use_llmNoEnable LLM analysis
use_validationNoEnable LLM validation
severity_thresholdNoMinimum severity levelmedium
output_formatNoOutput format for persisted scan resultsjson

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'session-aware analysis' and 'project context,' which adds some behavioral context, but it doesn't describe critical aspects like authentication requirements, rate limits, error handling, or what the scan results look like. For a security scanning tool with no annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with zero waste. It's front-loaded with the core purpose and efficiently adds context about session-aware analysis. Every sentence earns its place by providing essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a security scanning tool with 7 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., what the tool returns, error cases), doesn't differentiate from siblings, and provides minimal usage guidance. The description should do more to compensate for the missing structured data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, such as explaining interactions between parameters (e.g., how use_semgrep and use_llm work together). Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Scan code content for security vulnerabilities using Clean Architecture.' It specifies the action (scan), target (code content), and objective (security vulnerabilities). However, it doesn't explicitly differentiate from sibling tools like adv_scan_file or adv_scan_folder, which appear to be related scanning tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some usage context: 'Automatically uses session-aware analysis with project context when available.' This implies the tool leverages existing context, but it doesn't explicitly state when to use this tool versus alternatives like adv_scan_file or adv_scan_folder, nor does it provide exclusions or prerequisites for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

adv_scan_fileB

Scan a file for security vulnerabilities using Clean Architecture. Automatically uses session-aware analysis when LLM is configured.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesPath to the file to scan
use_semgrepNoEnable Semgrep analysis
use_llmNoEnable LLM analysis
use_validationNoEnable LLM validation
severity_thresholdNoMinimum severity levelmedium
timeout_secondsNoScan timeout in seconds
languageNoProgramming language hint
output_formatNoOutput format for persisted scan resultsjson

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'session-aware analysis' and LLM configuration, but doesn't cover critical aspects like whether this is a read-only or destructive operation, authentication requirements, rate limits, error handling, or what the scan results look like. For a security scanning tool with 8 parameters, this leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences that efficiently convey the core functionality and a key behavioral aspect. It's front-loaded with the main purpose. However, the second sentence about 'session-aware analysis' could be more clearly integrated or expanded for better flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex security scanning tool with 8 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns, how results are structured, error conditions, or important behavioral constraints. The mention of 'Clean Architecture' and 'session-aware analysis' adds some context but doesn't compensate for the missing information needed for effective tool use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'Clean Architecture' and 'session-aware analysis' which provide some context but don't directly explain parameter usage. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Scan a file for security vulnerabilities using Clean Architecture.' It specifies the action (scan), target (file), and domain (security vulnerabilities). However, it doesn't explicitly differentiate from sibling tools like 'adv_scan_code' or 'adv_scan_folder' beyond mentioning 'file' versus 'code' or 'folder' in their names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some implied usage context: 'Automatically uses session-aware analysis when LLM is configured.' This suggests when LLM features might be relevant. However, it lacks explicit guidance on when to use this tool versus alternatives like 'adv_scan_code' or 'adv_scan_folder', and doesn't mention prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

adv_scan_folderB

Scan a directory for security vulnerabilities using Clean Architecture. Automatically uses session-aware project analysis when LLM is configured.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoPath to the directory to scan.
use_semgrepNoEnable Semgrep analysis
use_llmNoEnable LLM analysis
use_validationNoEnable LLM validation
severity_thresholdNoMinimum severity levelmedium
timeout_secondsNoScan timeout in seconds
recursiveNoScan subdirectories
output_formatNoOutput format for persisted scan resultsjson

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'session-aware project analysis' and implies automation with LLM configuration, but fails to describe critical behaviors such as whether the scan is destructive, what permissions are required, how results are returned (e.g., format, persistence), or any rate limits. This leaves significant gaps for a security scanning tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences that efficiently convey the core functionality and a key behavioral aspect. It's front-loaded with the main purpose, though it could be slightly more structured by explicitly mentioning the tool's scope relative to siblings.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex security scanning tool with 8 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., safety, permissions), output handling, and differentiation from sibling tools, making it inadequate for full contextual understanding by an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, providing clear documentation for all 8 parameters. The description adds no additional parameter semantics beyond what's in the schema, such as explaining interactions between parameters (e.g., how 'use_llm' and 'use_validation' relate). Given the high schema coverage, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Scan a directory for security vulnerabilities using Clean Architecture.' It specifies the verb ('scan'), resource ('directory'), and methodology ('Clean Architecture'), but doesn't explicitly differentiate it from sibling tools like 'adv_scan_code' or 'adv_scan_file' which likely perform similar scanning on different targets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some usage context with 'Automatically uses session-aware project analysis when LLM is configured,' which implies when LLM analysis is enabled. However, it doesn't offer explicit guidance on when to choose this tool over alternatives like 'adv_scan_code' or 'adv_scan_file,' nor does it specify prerequisites or exclusions for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

adv_unmark_false_positiveB

Remove false positive marking from a finding

ParametersJSON Schema
NameRequiredDescriptionDefault
finding_uuidYesUUID of the finding to unmark
adversary_file_pathNoPath to .adversary.json file.adversary.json

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Remove') but doesn't explain what happens after unmarking (e.g., does the finding reappear in reports, is it reversible, are permissions required?). This leaves critical behavioral traits like mutation effects and security implications unclear, making it inadequate for a tool that modifies data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with zero wasted words, front-loading the core action. It efficiently communicates the essential purpose without redundancy or unnecessary elaboration, making it highly concise and well-structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity as a mutation operation with no annotations and no output schema, the description is insufficient. It lacks details on behavioral outcomes, error handling, or return values, leaving gaps in understanding how the tool functions in practice. For a tool that alters data, more context is needed to ensure safe and correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the input schema fully documents both parameters ('finding_uuid' and 'adversary_file_path'). The description adds no additional parameter semantics beyond what's in the schema, such as format details or examples. This meets the baseline for high schema coverage but doesn't enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Remove') and target ('false positive marking from a finding'), making the purpose immediately understandable. It distinguishes itself from siblings like 'adv_mark_false_positive' by specifying the opposite operation. However, it doesn't explicitly mention the resource type (e.g., security finding) or context, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a finding was previously marked as a false positive and needs to be reverted, but doesn't explicitly state when to use it versus alternatives. No guidance is provided on prerequisites, side effects, or when not to use it, leaving usage context partially inferred rather than clearly defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 9 tool updatesv1.0.0
    • Removedadv_clear_cache
    • Removedadv_diff_scan
    • Changedadv_get_status1 field changed
      • removedInput schema / required
        Removed value: -[]
    • Changedadv_get_version1 field changed
      • removedInput schema / required
        Removed value: -[]
    • Changedadv_mark_false_positive5 fields changed
      • addedInput schema / properties / adversary_file_path
        Added value: +{
+  "default": ".adversary.json",
+  "description": "Path to .adversary.json file",
+  "type": "string"
+}
      • changedInput schema / properties / marked_by / default
        Previous value: -"MCP User"New value: +"user"
      • changedInput schema / properties / marked_by / description
        Previous value: -"Name of the person marking this as false positive"New value: +"Who marked it as false positive"
      • removedInput schema / properties / path
        Removed value: -{
-  "default": ".",
-  "description": "Path to directory containing .adversary.json or direct path to .adversary.json file",
-  "type": "string"
-}
      • changedInput schema / properties / reason / default
        Previous value: -"Manually marked via MCP tool"New value: +""
    • Changedadv_scan_code14 fields changed
      • changedInput schema / properties / content / description
        Previous value: -"Source code content to scan"New value: +"Source code to analyze"
      • removedInput schema / properties / include_exploits
        Removed value: -{
-  "default": true,
-  "description": "Whether to include exploit examples",
-  "type": "boolean"
-}
      • addedInput schema / properties / language
        Added value: +{
+  "description": "Programming language of the code",
+  "type": "string"
+}
      • changedInput schema / properties / output_format / description
        Previous value: -"Output format for results (json or markdown)"New value: +"Output format for persisted scan results"
      • changedInput schema / properties / output_format / enum
        Previous value: -[
-  "json",
-  "markdown"
-]New value: +[
+  "json",
+  "md",
+  "markdown",
+  "csv"
+]
      • removedInput schema / properties / path
        Removed value: -{
-  "default": ".",
-  "description": "Directory path where results should be saved",
-  "type": "string"
-}
      • changedInput schema / properties / severity_threshold / description
        Previous value: -"Minimum severity threshold (low, medium, high, critical)"New value: +"Minimum severity level"
      • removedInput schema / properties / severity_threshold / enum
        Removed value: -[
-  "low",
-  "medium",
-  "high",
-  "critical"
-]
      • changedInput schema / properties / use_llm / default
        Previous value: -falseNew value: +true
      • changedInput schema / properties / use_llm / description
        Previous value: -"Whether to include LLM analysis prompts (for use with your client's LLM)"New value: +"Enable LLM analysis"
      • changedInput schema / properties / use_semgrep / description
        Previous value: -"Whether to include Semgrep analysis"New value: +"Enable Semgrep analysis"
      • changedInput schema / properties / use_validation / default
        Previous value: -trueNew value: +false
      • changedInput schema / properties / use_validation / description
        Previous value: -"Whether to use LLM validation to filter false positives"New value: +"Enable LLM validation"
      • changedInput schema / required
        Previous value: -[
-  "content"
-]New value: +[
+  "content",
+  "language"
+]
    • Changedadv_scan_file12 fields changed
      • removedInput schema / properties / include_exploits
        Removed value: -{
-  "default": true,
-  "description": "Whether to include exploit examples",
-  "type": "boolean"
-}
      • addedInput schema / properties / language
        Added value: +{
+  "description": "Programming language hint",
+  "type": "string"
+}
      • changedInput schema / properties / output_format / description
        Previous value: -"Output format for results (json or markdown)"New value: +"Output format for persisted scan results"
      • changedInput schema / properties / output_format / enum
        Previous value: -[
-  "json",
-  "markdown"
-]New value: +[
+  "json",
+  "md",
+  "markdown",
+  "csv"
+]
      • changedInput schema / properties / path / description
        Previous value: -"Path to the file to scan (must be a file, not a directory)"New value: +"Path to the file to scan"
      • changedInput schema / properties / severity_threshold / description
        Previous value: -"Minimum severity threshold"New value: +"Minimum severity level"
      • removedInput schema / properties / severity_threshold / enum
        Removed value: -[
-  "low",
-  "medium",
-  "high",
-  "critical"
-]
      • addedInput schema / properties / timeout_seconds
        Added value: +{
+  "description": "Scan timeout in seconds",
+  "type": "integer"
+}
      • changedInput schema / properties / use_llm / description
        Previous value: -"Whether to include LLM analysis prompts (for use with your client's LLM)"New value: +"Enable LLM analysis"
      • changedInput schema / properties / use_semgrep / description
        Previous value: -"Whether to include Semgrep analysis"New value: +"Enable Semgrep analysis"
      • changedInput schema / properties / use_validation / default
        Previous value: -trueNew value: +false
      • changedInput schema / properties / use_validation / description
        Previous value: -"Whether to use LLM validation to filter false positives"New value: +"Enable LLM validation"
    • Changedadv_scan_folder13 fields changed
      • removedInput schema / properties / include_exploits
        Removed value: -{
-  "default": true,
-  "description": "Whether to include exploit examples",
-  "type": "boolean"
-}
      • changedInput schema / properties / output_format / description
        Previous value: -"Output format for results (json or markdown)"New value: +"Output format for persisted scan results"
      • changedInput schema / properties / output_format / enum
        Previous value: -[
-  "json",
-  "markdown"
-]New value: +[
+  "json",
+  "md",
+  "markdown",
+  "csv"
+]
      • changedInput schema / properties / path / description
        Previous value: -"Path to the directory to scan (must be a directory, not a file)"New value: +"Path to the directory to scan"
      • changedInput schema / properties / recursive / description
        Previous value: -"Whether to scan subdirectories"New value: +"Scan subdirectories"
      • changedInput schema / properties / severity_threshold / description
        Previous value: -"Minimum severity threshold"New value: +"Minimum severity level"
      • removedInput schema / properties / severity_threshold / enum
        Removed value: -[
-  "low",
-  "medium",
-  "high",
-  "critical"
-]
      • addedInput schema / properties / timeout_seconds
        Added value: +{
+  "description": "Scan timeout in seconds",
+  "type": "integer"
+}
      • changedInput schema / properties / use_llm / description
        Previous value: -"Whether to include LLM analysis prompts (for use with your client's LLM)"New value: +"Enable LLM analysis"
      • changedInput schema / properties / use_semgrep / description
        Previous value: -"Whether to include Semgrep analysis"New value: +"Enable Semgrep analysis"
      • changedInput schema / properties / use_validation / default
        Previous value: -trueNew value: +false
      • changedInput schema / properties / use_validation / description
        Previous value: -"Whether to use LLM validation to filter false positives"New value: +"Enable LLM validation"
      • removedInput schema / required
        Removed value: -[]
    • Changedadv_unmark_false_positive2 fields changed
      • addedInput schema / properties / adversary_file_path
        Added value: +{
+  "default": ".adversary.json",
+  "description": "Path to .adversary.json file",
+  "type": "string"
+}
      • removedInput schema / properties / path
        Removed value: -{
-  "default": ".",
-  "description": "Path to directory containing .adversary.json or direct path to .adversary.json file",
-  "type": "string"
-}
  2. 9 tool updates
    • First observedadv_clear_cache
    • First observedadv_diff_scan
    • First observedadv_get_status
    • First observedadv_get_version
    • First observedadv_mark_false_positive
    • First observedadv_scan_code
    • First observedadv_scan_file
    • First observedadv_scan_folder
    • First observedadv_unmark_false_positive
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no ambiguity. The three scanning tools (code, file, folder) target different input types, while status/version tools serve administrative functions and false positive tools handle annotation management. There is no functional overlap between tools.

Naming Consistency5/5

All tools follow a perfect 'adv_verb_noun' pattern with consistent snake_case throughout. The naming convention is highly predictable, making it easy for agents to understand tool purposes from their names alone.

Tool Count5/5

Seven tools is an excellent number for this security scanning domain. The set covers core scanning operations (code/file/folder), administrative functions (status/version), and annotation management (mark/unmark false positives) without being overwhelming or sparse.

Completeness4/5

The tool surface covers the essential security scanning workflow well, including scanning different input types and managing false positives. A minor gap exists in result retrieval/management tools - there's no way to list, filter, or export findings beyond the scanning operations themselves, but agents can work around this limitation.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Orcho MCP Server

    guardd
    A
    license
    A
    quality
    D
    maintenance
    Provides real-time security risk assessment for AI coding prompts, analyzing potential dangers, blast radius, and complexity before code execution in Cursor.
    1
    16
    MIT

  • Laraguard MCP

    ecr17dev
    A
    license
    A
    quality
    D
    maintenance
    A security audit server for Laravel projects that performs static code analysis, dependency CVE checks, and configuration audits. It enables developers to detect vulnerabilities like SQL injection and XSS while providing active attack simulations directly within MCP-compatible IDEs.
    8
    2
    AGPL 3.0

  • secscan-mcp

    openjkai
    A
    license
    A
    quality
    A
    maintenance
    MCP server for Cursor that scans codebases for security issues including hardcoded secrets, SAST, vulnerable dependencies, and IaC misconfigurations.
    7
    MIT

Appeared in Searches

Latest Blog Posts

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