MCP Code Checker

MCP Tools Py

A Model Context Protocol (MCP) server providing code quality checking operations with easy client configuration. This server offers an API for performing code quality checks within a specified project directory, following the MCP protocol design.

Overview

This MCP server enables AI assistants like Claude (via Claude Desktop), VSCode with GitHub Copilot, or other MCP-compatible clients to run code quality checks on Python projects. The tools provided are:

- Run pylint checks to identify code quality issues
- Execute pytest to identify failing tests
- Run mypy for type checking

Scope: This server covers Python projects only. Further Python-specific extensions are planned, including architecture and layering checks (vulture, tach, import-linter) and refactoring tools. Support for other languages can be provided through separate, dedicated MCP servers with similar functionality.

Why a dedicated MCP server instead of bash access?

A general-purpose bash MCP tool allows more flexibility, but at the expense of less control. This server takes a more focused approach:

- Security: Only a defined set of tools (pylint, pytest, mypy) can be executed. All operations are scoped to the specified project_dir.
- Context management: Results are formatted and size-limited to reduce context load on the AI assistant. Output is structured as actionable prompts rather than raw tool output.
- Transparency: The server is open source, and detailed structured logging records every tool call with parameters, timing, and results.

Features

- run_pylint_check: Run pylint on the project code and generate smart prompts for LLMs
- run_pytest_check: Run pytest on the project code and generate smart prompts for LLMs
- run_mypy_check: Run mypy type checking on the project code

Pylint Parameters

The pylint tools expose the following parameters for customization:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| extra_args | list | None | Optional list of additional pylint CLI arguments (e.g. ["--disable=W0611"]) |
| target_directories | list | None (auto-detected) | Directories to analyze relative to project_dir. Auto-detected from pyproject.toml when omitted |

Pylint Configuration

Pylint reads your project's pyproject.toml automatically. Control which issues
are reported by configuring [tool.pylint.messages_control] in your pyproject.toml.
See docs/pyproject-configuration.md for examples
and migration guidance.

Target Directory Auto-Detection

When target_directories is not specified, all checker tools (pylint, mypy, vulture)
auto-detect directories from pyproject.toml:

- Source dirs from [tool.setuptools.packages.find] where (fallback: ["src"])
- Test dirs from [tool.pytest.ini_options] testpaths (fallback: ["tests"])

Only directories that exist on disk are included. You can override auto-detection
by passing an explicit list:

- ["src"] - Analyze only source code directory
- ["src", "tests"] - Analyze both source and test directories
- ["mypackage", "tests"] - For projects with different package structures
- ["."] - Analyze entire project directory (may be slow for large projects)

Pytest Parameters

run_pytest_check exposes the following parameters for customization:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| markers | list | None | Optional list of pytest markers to filter tests |
| verbosity | integer | 2 | Pytest verbosity level (0-3) |
| extra_args | list | None | Optional list of additional pytest arguments |
| env_vars | dictionary | None | Optional environment variables for the subprocess |

Note: Parallel test execution is enabled by default using pytest-xdist (-n auto).

Mypy Parameters

The mypy tools expose the following parameters for customization:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| strict | boolean | True | Use strict mode settings |
| disable_error_codes | list | None | List of mypy error codes to ignore |
| target_directories | list | None (auto-detected) | Directories to check relative to project_dir. Auto-detected from pyproject.toml when omitted |
| follow_imports | string | 'normal' | How to handle imports during type checking |

Command Line Interface (CLI)

Basic Usage

mcp-tools-py --project-dir /path/to/project [options]

Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| --project-dir | string | Required. Base directory for code checking operations |

Optional Parameters

Python Configuration

Test Configuration

Logging Configuration

Notes

- When --venv-path is specified, it takes precedence over --python-executable
- The --console-only flag is useful during development to avoid creating log files
- Log files are created in JSON format for structured analysis
- Temporary files are automatically cleaned up unless --keep-temp-files is specified

Environment Configuration

The --python-executable and --venv-path options must point to the environment where pytest, pylint, and mypy are installed — this is typically the tool's own virtual environment, not your project's runtime venv.

Correct Configuration

Point to the venv where mcp-tools-py and its tools are installed:

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": [
                "--project-dir", "/path/to/your/project",
                "--venv-path", "${VIRTUAL_ENV}"
            ]
        }
    }
}

Incorrect Configuration

Do not point to your project's runtime venv if it doesn't have pytest/pylint/mypy installed:

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": [
                "--project-dir", "/path/to/your/project",
                "--venv-path", "/path/to/your/project/.venv"
            ]
        }
    }
}

This will fail if your project's .venv doesn't have the required tools installed.

Troubleshooting

- "No module named pytest" (or pylint/mypy): Your --python-executable or --venv-path points to an environment that doesn't have the required tools installed. Update the configuration to point to the correct environment.
- After installing missing tools, restart the MCP server for changes to take effect. Tool availability is checked at startup and cached for the session.

Installation

…