Complexipy MCP Server

A Model Context Protocol (MCP) server that wraps complexipy to provide cognitive complexity analysis for Python codebases. This server uses the complexipy Python API for accurate and robust analysis.

Features

• Directory Scanning: Recursively analyze all .py files in a directory and filter by complexity threshold.

• File Scanning: Analyze a single Python file.

• Data Processing: Uses pandas for efficient data filtering and sorting.

• Clean Output: Returns JSON formatted results (list of objects).

• No Emojis: Pure data output suitable for machine consumption.

• Stdio Transport: Uses standard input/output for communication, making it compatible with most MCP clients.

Installation & Usage

Quick Start

You can run the server directly using uvx (no installation required):

uvx complexipy-mcp

Configuration for Claude Desktop

Add the following configuration to your MCP client settings (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "complexipy": {
      "command": "uvx",
      "args": [
        "complexipy-mcp"
      ]
    }
  }
}

Local Development

1. Clone the repository.

2. Install dependencies:

   uv sync

3. Run the server locally:

   uv run complexipy-mcp

Local Configuration for Claude Desktop

If you are developing locally, point the configuration to your local setup:

{
  "mcpServers": {
    "complexipy": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/complexipy-mcp",
        "run",
        "complexipy-mcp"
      ]
    }
  }
}

Tools

scan_directory

Scans a directory for files exceeding a cognitive complexity threshold.

• Arguments:

  • directory_path (string): Absolute path to the directory to scan.

  • threshold (integer): Complexity limit (default: 15).

• Returns: JSON string containing a list of files that exceed the threshold.

  [
    {
      "file_path": "/abs/path/to/file.py",
      "complexity": 25,
      "functions": [
        {
          "name": "function_name",
          "complexity": 10,
          "line_start": 5,
          "line_end": 15
        }
      ],
      "status": "exceeds_threshold"
    }
  ]

scan_file

Scans a single file for cognitive complexity.

• Arguments:

  • file_path (string): Absolute path to the file.

  • threshold (integer): Complexity limit (default: 15).

• Returns: JSON string containing the result if it exceeds the threshold.