CTF-MCP: 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

CTF-MCP is an MCP (Model Context Protocol) server that provides 140+ tools for CTF (Capture The Flag) challenges across Crypto, Web, Pwn, Reverse, Forensics, and Misc categories. It also includes an autonomous solving orchestrator and LLM agent integration.

Commands

# Install (editable mode)
pip install -e .
# Install with dev tools
pip install -e ".[dev]"
# Install with crypto/web deps
pip install -e ".[standard]"
# Install everything (Linux-only deps like pwntools excluded on Windows)
pip install -e ".[full]"
# Install LLM agent support
pip install -e ".[llm]"

# Run MCP server
ctf-mcp

# Run all tests
pytest

# Run a single test file
pytest tests/test_crypto.py

# Run a specific test
pytest tests/test_crypto.py::TestCryptoBase64::test_base64_encode -v

# Run with coverage
pytest --cov=ctf_mcp --cov-report=term-missing

# Lint
ruff check ctf_mcp/
black --check ctf_mcp/

# Format
black ctf_mcp/
ruff check --fix ctf_mcp/

# Security scan
bandit -r ctf_mcp/ -c pyproject.toml

# Pre-commit hooks
pre-commit install
pre-commit run --all-files

Architecture

Layer Overview

server.py (MCP entry point — dynamic tool registration via introspection)
  ├── tools/          6 tool classes exposed as MCP tools (prefix_method naming)
  ├── core/           Autonomous solving pipeline
  ├── engines/        Category-specific solving engines
  ├── adapters/       External binary tool wrappers
  ├── llm/            LLM-powered agent (ReAct pattern)
  ├── mcp/            MCP protocol extensions (streaming, tasks, registry)
  ├── network/        HTTP client, remote connections, exploit runner
  └── utils/          Security decorators, input validation, helpers

Tool Registration System

server.py dynamically discovers and registers all tools at startup:

1. Each tools/*.py module has a class (e.g., CryptoTools) with a get_tools() method returning {method_name: description}
2. register_tools() iterates modules, introspects method signatures via inspect, and generates JSON Schema for MCP
3. Tools are registered as {prefix}_{method_name} (e.g., crypto_base64_encode, web_sql_payloads)
4. The TOOL_REGISTRY dict maps tool names to (module_instance, method_name) tuples for dispatch