42crunch MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with the 42crunch API security platform. This server provides tools to search collections, retrieve API definitions, and access security assessments.

Features

• List Collections: Search and retrieve API collections from 42crunch

• Get Collection APIs: Retrieve all APIs within a specific collection

• Get API Details: Access detailed API information including OpenAPI definitions, assessments, and scan results

Prerequisites

• Python 3.8 or higher

• A 42crunch account and API token

Installation

1. Clone or navigate to this directory:

cd mcp

2. Install dependencies:

pip install -r requirements.txt

3. Set up environment variables:

   • Copy .env.example to .env (if available) or create a .env file

   • Add your 42crunch API token:

42C_TOKEN=your_42crunch_api_token_here

You can get your API token from the 42crunch platform.

Usage

Running the MCP Server

The server can run in two modes:

1. Stdio Mode (Default - for MCP clients)

Run the server directly in the foreground:

python main.py

Or use the module directly:

python -m src.server

2. HTTP Mode (for web/remote clients)

Run the HTTP server:

python http_main.py

Or with custom host/port:

python http_main.py --host 0.0.0.0 --port 8000

With auto-reload for development:

python http_main.py --reload

HTTP Server Endpoints:

• POST /jsonrpc - JSON-RPC 2.0 endpoint

• GET /health - Health check

• GET /tools - List available tools

• GET /docs - Interactive API documentation (Swagger UI)

• GET /redoc - Alternative API documentation (ReDoc)

Background/Daemon Mode

Run the server as a daemon in the background:

# Using command-line options (PID file in project directory)
python main.py --daemon --pidfile ./42crunch-mcp.pid

# Using helper scripts (automatically uses project directory)
./scripts/start_daemon.sh

Daemon Options:

• --daemon: Run as background daemon

• --pidfile: Path to PID file (required with --daemon)

• --workdir: Working directory for daemon (default: /)

Helper Scripts:

• scripts/start_daemon.sh - Start server as daemon

• scripts/stop_daemon.sh - Stop running daemon

• scripts/status_daemon.sh - Check daemon status

Systemd Service (Linux)

For production deployments, use the provided systemd service file:

# Copy service file
sudo cp 42crunch-mcp.service /etc/systemd/system/

# Edit the service file to match your installation paths
sudo nano /etc/systemd/system/42crunch-mcp.service

# Reload systemd
sudo systemctl daemon-reload

# Enable and start service
sudo systemctl enable 42crunch-mcp
sudo systemctl start 42crunch-mcp

# Check status
sudo systemctl status 42crunch-mcp

# View logs
sudo journalctl -u 42crunch-mcp -f

Note: MCP servers typically communicate via stdio (stdin/stdout). When running as a daemon, ensure your MCP client is configured to connect via the appropriate transport mechanism (named pipes, sockets, or HTTP if implemented).

MCP Tools

The server exposes three tools:

1. list_collections

List all API collections with pagination support.

Parameters:

• page (optional, int): Page number (default: 1)

• per_page (optional, int): Items per page (default: 10)

• order (optional, str): Sort order (default: "default")

• sort (optional, str): Sort field (default: "default")

Example:

result = list_collections(page=1, per_page=20)

2. get_collection_apis

Get all APIs within a specific collection.

Parameters:

• collection_id (required, str): Collection UUID

• with_tags (optional, bool): Include tags in response (default: True)

Example:

result = get_collection_apis(
    collection_id="3dae40d4-0f8b-42f9-bc62-2a2c8a3189ac",
    with_tags=True
)

3. get_api_details

Get detailed information about a specific API.

Parameters:

• api_id (required, str): API UUID

• branch (optional, str): Branch name (default: "main")

• include_definition (optional, bool): Include OpenAPI definition (default: True)

• include_assessment (optional, bool): Include assessment data (default: True)

• include_scan (optional, bool): Include scan results (default: True)

Example:

result = get_api_details(
    api_id="75ec1f35-8261-402f-8240-1a29fbcb7179",
    branch="main",
    include_definition=True,
    include_assessment=True,
    include_scan=True
)

Project Structure

mcp/
├── .env                    # Environment variables (42C_TOKEN)
├── requirements.txt        # Python dependencies
├── README.md              # This file
├── src/
│   ├── __init__.py
│   ├── server.py          # Main MCP server implementation
│   ├── client.py          # 42crunch API client
│   └── config.py          # Configuration management
└── tests/
    ├── __init__.py
    ├── test_server.py     # Server tests
    └── test_client.py     # API client tests

Configuration

The server uses environment variables for configuration:

• 42C_TOKEN: Your 42crunch API token (required)

The token is automatically loaded from the .env file or environment variables.

Error Handling

The server handles various error scenarios:

• Authentication failures: Returns error message if token is invalid

• Rate limiting: Handles 429 responses appropriately

• Invalid IDs: Validates collection and API IDs before making requests

• Network errors: Provides clear error messages for connection issues

All tools return a response dictionary with:

• success: Boolean indicating if the operation succeeded

• data: Response data (if successful)

• error: Error message (if failed)

• error_type: Type of error (if failed)

Testing

Unit Tests

Run unit tests using pytest:

pytest tests/

For verbose output:

pytest tests/ -v

Integration Tests

Integration tests assume the servers are running. Start them first:

Start servers:

# Terminal 1: Start HTTP server
python http_main.py

# Terminal 2: Start MCP stdio server (for stdio tests)
python main.py

Run tests:

# Run all unit tests
pytest tests/unit/ -v

# Run all integration tests
pytest tests/integration/ -v

# Test HTTP server only
pytest tests/integration/test_http.py -v

# Test MCP stdio server only
pytest tests/integration/test_mcp.py -v

# Test both servers (comparison tests)
pytest tests/integration/test_combined.py -v

# Run all tests
pytest tests/ -v

# Run with specific options
pytest tests/integration/test_http.py --api-id <uuid> -v
pytest tests/integration/test_mcp.py --skip-collection-tests -v

Integration test options:

• --skip-collection-tests - Skip collection-related tests

• --skip-api-tests - Skip API-related tests

• --api-id <uuid> - Provide API ID for testing get_api_details

Integration Tests with Test Client

Use the provided test client to test the MCP server end-to-end:

Full test suite:

python test_client.py

Test with specific IDs:

# Test with a collection ID
python test_client.py --collection-id <collection-uuid>

# Test with an API ID
python test_client.py --api-id <api-uuid>

# Test with both
python test_client.py --collection-id <uuid> --api-id <uuid>

Simple quick test:

python test_simple.py

Test HTTP server:

# First, start the HTTP server in another terminal:
python http_main.py

# Then in another terminal, run the HTTP test client:
python tests/clients/test_http_client.py

# Or test with specific IDs:
python tests/clients/test_http_client.py --collection-id <uuid> --api-id <uuid>

Test MCP stdio server:

# Run the stdio test client (starts server automatically):
python tests/clients/test_client.py

# Or test with specific IDs:
python tests/clients/test_client.py --collection-id <uuid> --api-id <uuid>

The test clients will:

1. Start/connect to the MCP server

2. Send JSON-RPC requests (via stdio or HTTP)

3. Read responses

4. Validate the responses

5. Report test results

Example output:

============================================================
42crunch MCP Server Test Client
============================================================
Starting MCP server: python main.py
Server started (PID: 12345)

============================================================
TEST: list_collections
============================================================
📤 Request: {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_collections",
    "arguments": {
      "page": 1,
      "per_page": 10
    }
  }
}
📥 Response: {
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "data": {...}
  }
}
✅ list_collections succeeded

Development

Adding New Tools

To add a new MCP tool:

1. Add the corresponding method to src/client.py

2. Create a tool function in src/server.py using the @mcp.tool() decorator

3. Wire up the client method to the tool

4. Add tests in tests/test_server.py

Code Style

This project follows PEP 8 style guidelines. Consider using a formatter like black or ruff for consistent code style.

License

[Add your license here]

Support

For issues related to:

• 42crunch API: Contact 42crunch support

• MCP Server: Open an issue in this repository

References

• 42crunch Platform

• FastMCP Documentation

• Model Context Protocol