sast-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SAST MCP Server — a FastMCP-based MCP server that exposes 11 static/dynamic security scanners (Bandit, njsscan, Bearer, Semgrep, Trivy, CodeQL, Checkov, Gitleaks, OSV-Scanner, Grype, OWASP ZAP) as tools for AI agents (Gemini CLI, Claude Desktop, Cursor, OpenAI Agents, etc.). Findings are normalized into a typed Finding model, enriched with AST-aware code context, deduplicated across scanners, and can be exported as SARIF 2.1.0 for CI/CD.

Development Commands

# Install with dev dependencies (editable)
pip install -e ".[dev]"

# Run the full test suite
pytest tests/ -v

# Run a single test file
pytest tests/test_scanners.py -v

# Run a single test
pytest tests/test_scanners.py::TestBanditScanner::test_parse_findings -v

# Lint (this is what CI runs)
ruff check sast_mcp_server/

# Type check (configured in pyproject.toml, not enforced in CI)
mypy sast_mcp_server/

# Run the server locally (stdio transport, for MCP client integration)
python -m sast_mcp_server
# or, once installed:
sast-mcp-server

# Run as a remote HTTP server (Streamable HTTP is the current standard; SSE is deprecated)
sast-mcp-server --transport streamable-http --host 0.0.0.0 --port 8080

CI (.github/workflows/ci.yml) runs ruff check sast_mcp_server/ and pytest tests/ -v --tb=short across Python 3.10–3.13, then publishes to PyPI on v* tags.

Architecture

Entry point and server registration

sast_mcp_server/server.py builds the FastMCP instance and registers all @mcp.tool() functions (scan_vulnerabilities, scan_all, scan_git_history, run_active_scan, export_sarif, save_baseline, compare_baseline, list_scanners, ignore_vulnerability, unignore_vulnerability, list_ignored_vulnerabilities, plus the v0.6.0 tools upload_to_defectdojo, upload_to_github, generate_fix_prompt, apply_patch). register_resources(mcp) and register_prompts(mcp) wire up MCP Resources and Prompts from resources.py / prompts.py. The decorated tool functions stay directly callable, so tests import and await them as plain functions.