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:

2. Install dependencies:

3. Set up environment variables:

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

   • Add your 42crunch API token:

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:

Or use the module directly:

2. HTTP Mode (for web/remote clients)

Run the HTTP server:

Or with custom host/port:

With auto-reload for development:

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:

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:

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:

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:

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:

Project Structure

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:

For verbose output:

Integration Tests

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

Start servers:

Run tests:

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:

Test with specific IDs:

Simple quick test:

Test HTTP server:

Test MCP stdio server:

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:

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