🦡 codebadger-toolkit

A containerized Model Context Protocol (MCP) server providing static code analysis using Joern's Code Property Graph (CPG) technology with support for Java, C/C++, JavaScript, Python, Go, Kotlin, C#, Ghidra, Jimple, PHP, Ruby, and Swift.

Prerequisites

Before you begin, make sure you have:

• Docker and Docker Compose installed
• Python 3.10+ (Python 3.13 recommended)
• pip (Python package manager)

To verify your setup:

docker --version
docker-compose --version
python --version

Quick Start

1. Install Python Dependencies

# Create a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Start the Docker Services (Joern + Redis)

docker compose up -d

This starts:

• Joern Server: Static code analysis engine (runs CPG generation and queries)
• Redis: Metadata storage (tracks codebases, ports, and CPG information)

Verify services are running:

docker compose ps

3. Start the MCP Server

# Set the correct Redis port (maps to container's 6379)
REDIS_PORT=6380 python main.py

The MCP server will be available at http://localhost:4242.

4. Stop All Services

# Stop MCP server (Ctrl+C in terminal)

# Stop Docker services
docker-compose down

# Optional: Clean up everything
bash cleanup.sh

Cleanup Script

Use the provided cleanup script to reset your environment:

bash cleanup.sh

This will:

• Stop and remove Docker containers
• Kill orphaned Joern/MCP processes
• Clear Python cache (__pycache__, .pytest_cache)
• Optionally clear the playground directory (CPGs and cached codebases)

Integrations

GitHub Copilot Integration

Edit the MCP configuration file for VS Code (GitHub Copilot):

Path:

~/.config/Code/User/mcp.json

Example configuration:

{
  "inputs": [],
  "servers": {
    "codebadger-toolkit": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

---

Claude Code Integration

To integrate codebadger-toolkit into Claude Desktop, edit:

Path:

Claude → Settings → Developer → Edit Config → claude_desktop_config.json

Add the following:

{
  "mcpServers": {
    "codebadger-toolkit": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

Available Tools

Core Tools (hash-based)

• generate_cpg: Generate a CPG for a codebase (from local path or GitHub URL)
• get_cpg_status: Get status and existence of a CPG by codebase_hash
• run_cpgql_query: Execute CPGQL queries (synchronous)

Code Browsing Tools

• get_codebase_summary: Get codebase overview
• list_files: List source files
• list_methods: Discover methods/functions
• get_method_source: Retrieve method source code
• list_calls: Find function call relationships
• get_call_graph: Build call graphs
• list_parameters: Get parameter information
• find_literals: Search for hardcoded values
• get_code_snippet: Retrieve code snippets

Security Analysis Tools

• find_taint_sources: Locate external input points
• find_taint_sinks: Locate dangerous sinks
• find_taint_flows: Find dataflow paths
• find_argument_flows: Find expression reuse
• check_method_reachability: Check call graph connections
• list_taint_paths: List detailed taint paths
• get_program_slice: Build program slices

Contributing & Tests

Thanks for contributing! Here's a quick guide to get started with running tests and contributing code.

Prerequisites

• Python 3.10+ (3.13 is used in CI)
• Docker and Docker Compose (for integration tests)

Local Development Setup

1. Create a virtual environment and install dependencies

python -m venv venv
pip install -r requirements.txt

2. Start Docker services (for integration tests)

docker-compose up -d

3. Run unit tests

pytest tests/ -q

4. Run integration tests (requires Docker Compose running)

# Start MCP server in background
REDIS_PORT=6380 python main.py &

# Run integration tests
pytest tests/integration -q

# Stop MCP server
pkill -f "python main.py"

5. Run all tests

pytest tests/ -q

6. Cleanup after testing

bash cleanup.sh
docker-compose down

Code Contributions

Please follow these guidelines when contributing:

1. Follow repository conventions
2. Write tests for behavioral changes
3. Ensure all tests pass before submitting PR
4. Include a clear changelog in your PR description
5. Update documentation if needed

Configuration

The MCP server can be configured via environment variables or config.yaml.

Environment Variables

Key settings (optional - defaults shown):

# Server
MCP_HOST=0.0.0.0
MCP_PORT=4242

# Redis (running inside Docker container)
REDIS_HOST=localhost
REDIS_PORT=6380        # ⚠️  IMPORTANT: Port 6380 on host maps to 6379 in container

# Joern
JOERN_BINARY_PATH=joern
JOERN_JAVA_OPTS="-Xmx4G -Xms2G -XX:+UseG1GC -Dfile.encoding=UTF-8"

# CPG Generation
CPG_GENERATION_TIMEOUT=600
MAX_REPO_SIZE_MB=500

# Query
QUERY_TIMEOUT=30
QUERY_CACHE_ENABLED=true
QUERY_CACHE_TTL=300

Config File

Create a config.yaml from config.example.yaml:

cp config.example.yaml config.yaml

Then customize as needed.

Important: Redis Port Configuration

Since Redis runs inside the Docker container:

• Inside container: Redis listens on 6379
• Host mapping: Docker maps 6380:6379
• MCP server should use: REDIS_PORT=6380

Always start the MCP server with:

REDIS_PORT=6380 python main.py