Mcp Tools Py

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](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

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | --python-executable | string | sys.executable | Path to Python interpreter for running pytest, pylint, and mypy. Should point to the environment where these tools are installed (the tool's own venv), not the project's runtime venv | | --venv-path | string | None | Path to the virtual environment where pytest, pylint, and mypy are installed. When specified, this venv's Python will be used instead of --python-executable. This should be the tool's own venv, not the project's runtime venv |

Test Configuration

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | --test-folder | string | "tests" | Path to the test folder (relative to project-dir) | | --keep-temp-files | flag | False | Keep temporary files after test execution. Useful for debugging when tests fail |

Logging Configuration

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | --log-level | string | "INFO" | Set logging level. Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL | | --log-file | string | None | Path for structured JSON logs. If not specified, logs only to console | | --console-only | flag | False | Log only to console, ignore --log-file parameter |

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

See [INSTALL.md](INSTALL.md) for detailed installation instructions.

Quick install:

# Install from GitHub (recommended)
pip install git+https://github.com/MarcusJellinghaus/mcp-tools-py.git

# Verify installation
mcp-tools-py --help

Development install:

# Clone and install for development
git clone https://github.com/MarcusJellinghaus/mcp-tools-py.git
cd mcp-tools-py
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
mcp-tools-py --help

MCP Client Configuration

This server can be easily configured using the mcp-config Python tool. The mcp-config tool provides:

• Interactive setup: Works with Claude Desktop and VSCode
• Configuration management: Add, remove, and view server configurations
• Server repository: Access to curated MCP server collection

Prerequisites: Install Python and the mcp-config tool.

Note: While other MCP clients like Windsurf and Cursor support MCP servers, they may require manual configuration.

Using as a Dependency

In requirements.txt

Add this line to your requirements.txt:

mcp-tools-py @ git+https://github.com/MarcusJellinghaus/mcp-tools-py.git

In pyproject.toml

Add to your project dependencies:

[project]
dependencies = [
    "mcp-tools-py @ git+https://github.com/MarcusJellinghaus/mcp-tools-py.git",
    # ... other dependencies
]

# Or as an optional dependency
[project.optional-dependencies]
dev = [
    "mcp-tools-py @ git+https://github.com/MarcusJellinghaus/mcp-tools-py.git",
]

Installation Commands

After adding to requirements.txt or pyproject.toml:

# Install from requirements.txt
pip install -r requirements.txt

# Install from pyproject.toml
pip install .
# Or with optional dependencies
pip install ".[dev]"

Running the Server

Using the CLI Command (Recommended)

After installation, you can run the server using the mcp-tools-py command:

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

Using Python Module (Alternative)

You can also run the server as a Python module:

python -m mcp_tools_py --project-dir /path/to/project [options]

# Or for development (from source directory)
python -m src.main --project-dir /path/to/project [options]

For detailed information about all available command-line options, see the [CLI section](#command-line-interface-cli).

Project Structure Support

The server automatically detects and analyzes Python code in standard project structures:

Default Analysis:

• src/ directory (if present) - Main source code
• tests/ directory (if present) - Test files

Custom Project Structures: Use the target_directories parameter to specify different directories:

# For a package-based structure
target_directories = ["mypackage", "tests"]

# For a simple project with code in root
target_directories = ["."]

# For complex multi-module projects
target_directories = ["module1", "module2", "shared", "tests"]

Structured Logging

The server provides comprehensive logging capabilities:

• Standard human-readable logs to console for development/debugging
• Structured JSON logs to file for analysis and monitoring
• Function call tracking with parameters, timing, and results
• Automatic error context capture with full stack traces
• Configurable log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• Default timestamped log files in project_dir/logs/mcp_tools_py_{timestamp}.log

Example structured log entries:

{
  "timestamp": "2025-08-05 14:30:15",
  "level": "info",
  "event": "Starting pylint check",
  "project_dir": "/path/to/project",
  "disable_codes": ["C0114", "C0116"],
  "target_directories": ["src", "tests"]
}

Use --console-only to disable file logging for simple development scenarios.

Quick MCP Client Setup

Automated Setup (Recommended)

1. First install the server:

``bash pip install git+https://github.com/MarcusJellinghaus/mcp-tools-py.git ``

1. Configure with mcp-config:

``bash mcp-config ` Then select "Add New" and search for this server, or run directly: `bash mcp-config mcp-tools-py ``

This will prompt you for your project directory and automatically configure your MCP client.

Manual Setup

If you prefer manual configuration, edit your MCP configuration file:

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows):

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

For development mode:

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "python",
            "args": [
                "-m",
                "src.main",
                "--project-dir",
                "/path/to/your/project"
            ],
            "env": {
                "PYTHONPATH": "/path/to/mcp-tools-py"
            }
        }
    }
}

VSCode (.vscode/mcp.json):

{
    "servers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": ["--project-dir", "."]
        }
    }
}

VSCode development mode:

{
    "servers": {
        "mcp-tools-py": {
            "command": "python",
            "args": ["-m", "src.main", "--project-dir", "."],
            "env": {
                "PYTHONPATH": "/path/to/mcp-tools-py"
            }
        }
    }
}

Testing with MCP Inspector

npx @modelcontextprotocol/inspector mcp-tools-py --project-dir /path/to/project

Available Tools

The server exposes the following MCP tools:

Run Pylint Check

• Runs pylint on the project code and generates smart prompts for LLMs
• Returns: A string containing either pylint results or a prompt for an LLM to interpret
• Helps identify code quality issues, style problems, and potential bugs
• Customizable with parameters for disabling specific pylint codes and targeting specific directories
• Supports flexible project structures through target_directories parameter

Run Pytest Check

• Runs pytest on the project code and generates smart prompts for LLMs
• Returns: A string containing either pytest results or a prompt for an LLM to interpret
• Identifies failing tests and provides detailed information about test failures
• Customizable with parameters for test selection, environment, and verbosity

Run Mypy Check

• Runs mypy type checking on the project code
• Returns: A string containing mypy results or a prompt for an LLM to interpret
• Identifies type errors and provides suggestions for better type safety
• Customizable with parameters for strict mode, error code filtering, and target directories

Development

Setting up the development environment

# Clone the repository
git clone https://github.com/MarcusJellinghaus/mcp-tools-py.git
cd mcp-tools-py

# Create and activate a virtual environment
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On Unix/MacOS:
source .venv/bin/activate

# Install dependencies
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

Running with MCP Dev Tools

# Set the PYTHONPATH and run the server module using mcp dev
set PYTHONPATH=. && mcp dev src/server.py

License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

The MIT License is a permissive license that allows reuse with minimal restrictions. It permits use, copying, modification, and distribution with proper attribution.

Links

• MCP Python SDK
• MCP Filesystem Tools

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MarcusJellinghaus
• Source: MarcusJellinghaus/mcp-tools-py
• License: MIT

Install and usage instructions live in the source repository linked above.