mcp-tools-py MCP工具

Required Parameters

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

Or as an optional dependency

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

Install from requirements.txt

pip install -r requirements.txt

Or with optional dependencies

pip install ".[dev]" ```

Install dependencies

pip install -e .

Install development dependencies

pip install -e ".[dev]" ```

Installation

See INSTALL.md for detailed installation instructions.

Quick install:

```bash

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 ```

Installation Commands

After adding to requirements.txt or pyproject.toml:

```bash

Install from pyproject.toml

pip install .

Quick MCP Client Setup

Automated Setup (Recommended)

1. First install the server:

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

2. Configure with mcp-config (install it separately — it is not pulled in by this package):

   mcp-config
   

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

Note: mcp-config's server registry does not yet carry an entry for mcp-tools-py, so use the Manual Setup below if it cannot find this server.

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"
            }
        }
    }
}

Basic Usage

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

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.

Mypy Configuration

Mypy reads your project's pyproject.toml automatically, and [tool.mypy] is the single source of truth for the flag set — the tool adds only output-formatting flags, unless you pass follow_imports, cache_dir or disable_error_codes. A project with no [tool.mypy] section of its own has no floor: with no config in scope it runs at mypy's defaults and reports "passed" having checked very little; with a parent directory's config (mypy 1.15 and later) or a user-level ~/.config/mypy/config or ~/.mypy.ini in scope it runs at those settings and can report errors the project never asked for. See docs/pyproject-configuration.md for migration guidance and the effect on mypy's cache.

Optional Parameters

#### Python Configuration <div class="rdm-tbl-wrap"><table class="rdm-tbl"><thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>--python-executable</td><td>string</td><td>sys.executable</td><td>Path to the Python interpreter of the project's environment. The checkers run in it and library/symbol lookups resolve against it, so it must be the environment holding the project's dependencies and the checker tools. A bare name is looked up on PATH; a path that neither exists nor resolves fails at startup</td></tr><tr><td>--venv-path</td><td>string</td><td>None</td><td>Deprecated, hidden from --help. Still accepted, and still resolves the interpreter (taking precedence over --python-executable), but no longer used to locate tools. Use --python-executable instead</td></tr></tbody></table></div>

#### Test Configuration <div class="rdm-tbl-wrap"><table class="rdm-tbl"><thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>--test-folder</td><td>string</td><td>&quot;tests&quot;</td><td>Path to the test folder (relative to project-dir)</td></tr><tr><td>--keep-temp-files</td><td>flag</td><td>False</td><td>Keep temporary files after test execution. Useful for debugging when tests fail</td></tr></tbody></table></div>

#### Logging Configuration <div class="rdm-tbl-wrap"><table class="rdm-tbl"><thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>--log-level</td><td>string</td><td>&quot;INFO&quot;</td><td>Set logging level. Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL</td></tr><tr><td>--log-file</td><td>string</td><td>None</td><td>Path for structured JSON logs. If not specified, logs go to project_dir/logs/mcp_tools_py_{timestamp}.log</td></tr><tr><td>--console-only</td><td>flag</td><td>False</td><td>Log only to console: no default log file, and --log-file is ignored</td></tr></tbody></table></div>

#### Tool Configuration <div class="rdm-tbl-wrap"><table class="rdm-tbl"><thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>--check-timeout</td><td>integer</td><td>None (120; pytest 300)</td><td>Timeout in seconds for every checker and formatter subprocess. Overridden per tool by [tool.mcp-tools-py] in the project's pyproject.toml — see Project configuration</td></tr><tr><td>--refactoring-timeout</td><td>integer</td><td>120</td><td>Timeout in seconds for rope refactoring operations</td></tr><tr><td>--vulture-whitelist</td><td>string</td><td>&quot;vulture_whitelist.py&quot;</td><td>Path to the vulture whitelist file, relative to project-dir. Auto-included by run_vulture_check when the file exists</td></tr></tbody></table></div>

Environment Configuration

There is one configurable environment: the project env, the virtual environment holding your project's dependencies and the checker tools. --python-executable names its interpreter. The two cannot be separated — pytest, pylint and mypy all import the project's dependencies to do their work — so the tools have to be installed alongside them. pytest, pylint, mypy, black and isort are run through that interpreter, while ruff, bandit, vulture, tach and lint-imports are console scripts located next to it.

The tool env, where mcp_tools_py itself is installed, is a different environment and is not configured through this flag.

Library and symbol resolution (get_library_source, list_symbols, find_references) follows the same interpreter, so pointing the flag at the wrong venv makes those tools resolve against the wrong packages.

The first example below builds that path by interpolating an environment variable, so an unset or stale variable leaves --python-executable pointing nowhere. The server then fails at startup with a FileNotFoundError naming the flag, rather than starting up and reporting every tool as missing. A bare interpreter name such as python3 is looked up on PATH instead.

Correct Configuration

Point to the project's venv, with the checker tools installed in it, here on Windows:

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": [
                "--project-dir", "/path/to/your/project",
                "--python-executable", "${VIRTUAL_ENV}\\Scripts\\python.exe"
            ]
        }
    }
}

On macOS and Linux the interpreter sits in bin instead:

                "--python-executable", "${VIRTUAL_ENV}/bin/python"

Incorrect Configuration

Do not point to a venv without the checker tools installed:

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

A system interpreter, or any venv that is not the project's, reports the tools as missing and resolves library and symbol lookups against the wrong packages. Your project's own .venv fails the same way if it doesn't have the required tools installed — install them there rather than pointing the flag elsewhere.

MCP Client Configuration

This server can be configured with mcp-config, a separate Python tool you install yourself — it is not a dependency of this package. It 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, then install mcp-config separately.

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

Setting up the development environment

```bash

Create and activate a virtual environment

python -m venv .venv

Command Line Interface (CLI)

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]

For a package-based structure

target_directories = ["mypackage", "tests"]

For complex multi-module projects

target_directories = ["module1", "module2", "shared", "tests"] ```

Set the PYTHONPATH and run the server module using mcp dev

set PYTHONPATH=. && mcp dev src/server.py ```

Using Python Module (Alternative)

You can also run the server as a Python module:

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

Troubleshooting

• "Python interpreter not found" at startup: --python-executable points at a path that doesn't exist — usually because the environment variable it interpolates is unset. The message names the flag that supplied the path.
• "No module named pytest" (or pylint/mypy/black/isort): Your --python-executable points to an environment that doesn't have the required tools installed. Point it at the project's environment and install them there.
• "ruff is not available" (or bandit/vulture/tach/lint-imports): these tools are console scripts, looked for next to --python-executable. The message names the directory searched; point --python-executable at the project's environment and install them there. A bare name such as python3 resolving to a system interpreter reports all five as unavailable, because they are not installed next to it.
• After installing missing tools: the console-script tools (ruff, bandit, vulture, tach, lint-imports) are looked for on disk on every call, so they work as soon as they are installed — no restart needed. pytest, pylint, mypy, black and isort are answered by a probe of the configured interpreter that runs once and is cached for the process lifetime, so restart the MCP server after installing one of those five.