MCP Code Checker

MCP Tools Py

一个用于执行代码质量检查操作的模型上下文协议（MCP）服务，可轻松配置客户端。此服务按照 MCP 协议设计，提供 API，可在指定项目目录中执行代码质量检查。

概览

此 MCP 服务支持 AI 助手（如通过 Claude Desktop 使用的 Claude、配备 GitHub Copilot 的 VS Code）及其他兼容 MCP 的客户端，对 Python 项目执行代码质量检查、格式化和重构。完整列表请参阅可用工具。

**适用范围：**此服务仅支持 Python 项目。其他语言可通过具有类似功能的独立 MCP 服务提供支持。

为什么选择专用 MCP 服务，而不是使用 bash？

通用 bash MCP 工具更加灵活，但控制力较弱。此服务采取更专注的方式：

• **安全性：**只能执行一组明确指定的工具——请参阅可用工具。所有操作均限定在指定的 project_dir 范围内。
• **上下文管理：**结果经过格式化并限制大小，以减少 AI 助手的上下文负担。输出以可执行的提示词形式呈现，而非原始工具输出。
• **透明度：**此服务是开源的，并通过详细的结构化日志记录每次工具调用的参数、耗时和结果。

功能

所有工具均列于可用工具。以下各节 介绍最常用工具的参数。

Pylint 参数

pylint 工具提供以下可自定义参数：

参数	类型	默认值	说明
extra_args	list	None	可选的额外 pylint CLI 参数列表（例如 ["--disable=W0611"]）
target_directories	list	None（自动检测）	相对于 project_dir 的待分析目录。若未指定，则从 pyproject.toml 自动检测
max_issues	integer	1	详细显示的问题类型数量；其余问题仅汇总为计数。0 = 仅显示计数（按规则统计数量并按目录拆分）

Pylint 配置

Pylint 会自动读取项目的 pyproject.toml。通过在 pyproject.toml 中配置 [tool.pylint.messages_control]，控制要报告的问题。 示例和迁移指南请参阅 docs/pyproject-configuration.md。

目标目录自动检测

未指定 target_directories 时，接受该参数的工具（pylint、mypy、ruff check、ruff fix、bandit、vulture 和 run_format_code）会从 pyproject.toml 自动检测目录：

• 源代码目录：来自 [tool.setuptools.packages.find] where（回退值：["src"]）
• 测试目录：来自 [tool.pytest.ini_options] testpaths（回退值：["tests"]）

run_deptry_check 仅自动检测源代码目录，不包括测试路径。

仅包含磁盘上实际存在的目录。你可以传入显式列表，覆盖自动检测结果：

• ["src"] - 仅分析源代码目录
• ["src", "tests"] - 同时分析源代码目录和测试目录
• ["mypackage", "tests"] - 适用于包结构不同的项目
• ["."] - 分析整个项目目录（大型项目可能较慢）

Pytest 参数

run_pytest_check 提供以下参数以便自定义：

参数	类型	默认值	描述
markers	list	None	可选的 pytest 标记列表，用于筛选测试
extra_args	list	None	可选的附加 pytest 参数；使用 -v/-vv/-vvv 控制详细程度
env_vars	dictionary	None	可选的子进程环境变量
timeout_seconds	integer	None（从配置中解析，否则为 300）	等待测试运行的最长秒数。仅限正整数
coverage	boolean	False	使用 pytest-cov 测量覆盖率，并在回复中附加覆盖率摘要
coverage_source	list	None（自动检测）	要测量的目录。根据 [tool.setuptools.packages.find] where 自动检测，并排除测试路径
max_modules	integer	10	覆盖率摘要在各列表中详细列出的模块数量

注意： 默认启用使用 pytest-xdist 的并行测试执行（-n auto）。

覆盖率： coverage=True 要求项目环境中已安装 pytest-cov。摘要会提供总覆盖率、缺失语句最多的模块及其各函数对应的行范围、没有任何覆盖的模块，以及生成这些数据时选用的测试。项目的 fail_under 会在报告中显示，但不会被应用，因此通过或失败仅取决于测试结果。如需排除代码，请使用 coverage 自带的 [tool.coverage.run] omit 或 # pragma: no cover。

Mypy 参数

mypy 工具提供以下参数以便自定义：

参数	类型	默认值	描述
disable_error_codes	list	None	要忽略的 mypy 错误代码列表
target_directories	list	None（自动检测）	相对于 project_dir 的待检查目录。省略时会从 pyproject.toml 自动检测
follow_imports	string	None（不传递标志；由项目的 [tool.mypy] 决定）	类型检查期间如何处理导入
cache_dir	string	None（不传递标志；由 MYPY_CACHE_DIR 决定，否则使用 [tool.mypy] cache_dir，再否则使用 .mypy_cache）	增量检查的自定义缓存目录
timeout_seconds	integer	None（从配置中解析，否则为 120）	等待 mypy 的最长秒数。仅限正整数
max_issues	integer	None	详细显示的错误代码数量（每项 5 个位置）；其余错误代码各显示一行摘要。None 表示详细显示每个错误代码；0 = 仅显示计数（每个错误代码的数量及目录分布）

Mypy 配置

mypy 会自动读取项目的 pyproject.toml，而 [tool.mypy] 是标志集的唯一依据——该工具只会添加输出格式标志，除非你传入 follow_imports、cache_dir 或 disable_error_codes。如果项目本身没有 [tool.mypy] 部分，就没有最低配置限制：如果作用范围内没有配置，mypy 会使用默认设置运行，检查内容很少便报告“passed”；如果作用范围内存在父目录的配置（mypy 1.15 及更高版本），或用户级 ~/.config/mypy/config 或 ~/.mypy.ini，则会按这些设置运行，并可能报告项目从未要求检查的错误。迁移指南以及对 mypy 缓存的影响，请参阅 docs/pyproject-configuration.md。

命令行界面（CLI）

基本用法

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

必需参数

参数	类型	描述
--project-dir	string	必需。代码检查操作的基础目录

可选参数

Python 配置

参数	类型	默认值	描述
--python-executable	string	sys.executable	项目环境中 Python 解释器的路径。pytest、pylint、mypy 和 deptry 会在该解释器中运行，库和符号查找也会基于该解释器，因此它必须指向存有项目依赖项且已安装 deptry 的环境。black、isort、ruff、bandit、vulture、tach 和 lint-imports 来自 mcp-tools-py 自身的环境，无需在此环境中安装。裸名称会在 PATH 中查找；若路径不存在或无法解析，则会在启动时失败
--venv-path	string	None	已弃用，不会显示在 --help 中。仍可使用，也仍会解析解释器（优先级高于 --python-executable），但不再用于查找工具。请改用 --python-executable

测试配置

参数	类型	默认值	描述
--test-folder	string	"tests"	测试文件夹的路径（相对于 project-dir）
--keep-temp-files	flag	False	测试执行后保留临时文件。测试失败时便于调试

日志配置

参数	类型	默认值	描述
--log-level	string	"INFO"	设置日志级别。可选值：DEBUG、INFO、WARNING、ERROR、CRITICAL
--log-file	string	None	结构化 JSON 日志的路径。若未指定，日志会写入 project_dir/logs/mcp_tools_py_{timestamp}.log
--console-only	flag	False	仅记录到控制台：不创建默认日志文件，并忽略 --log-file

工具配置

参数	类型	默认值	描述
--check-timeout	integer	None (120; pytest 300)	每个检查器和格式化工具子进程的超时时间，单位为秒。可由项目 pyproject.toml 中的 [tool.mcp-tools-py] 按工具覆盖——请参阅项目配置
--refactoring-timeout	integer	120	rope 重构操作的超时时间，单位为秒
--vulture-whitelist	string	"vulture_whitelist.py"	vulture 白名单文件的路径，相对于 project-dir。文件存在时，run_vulture_check 会自动将其纳入检查

注意事项

• 指定已弃用的 --venv-path 时，其优先级高于 --python-executable。现在它唯一的作用是解析解释器
• 在开发期间，--console-only 标志可用于避免创建日志文件
• 日志文件以 JSON 格式创建，便于进行结构化分析
• 除非指定 --keep-temp-files，否则会自动清理临时文件

环境配置

涉及两个环境，但只有一个可配置：

• 项目环境 — 由 --python-executable 指定。它包含项目的依赖项，以及 pytest、pylint、mypy 和 deptry；这些工具需要导入或检查这些依赖项才能完成工作。库和符号解析（get_library_source、list_symbols、find_references）使用同一个解释器，因此如果将该标志指向错误的虚拟环境，这些工具就会针对错误的软件包进行解析。
• 工具环境 — mcp_tools_py 本身的安装位置。它提供 black、isort、ruff、bandit、vulture、tach 和 lint-imports，这些都是 mcp-tools-py 自身的依赖项。此环境不可配置。

因此，这七个工具都使用工具环境中的版本，这些版本可能与项目锁定的版本不同；所以，如果项目需要与 CI 保持一致，就应在两处都使用兼容的版本范围。lint-imports 仍会检查你的工作树：它从工具环境运行，但会通过项目解释器找到项目的根包；根包由 import-linter 配置指定。根包内部自定义的 contract_types 条目仍会通过相同的桥接机制解析；如果该条目位于仅安装在项目环境中的独立发行包里，则不会解析，因为传递过去的只有根包的目录。

下面的第一个示例通过插入环境变量来构造该路径，因此，如果变量未设置或已过时，--python-executable 就会指向不存在的位置。此时，服务会在启动时失败，并报告包含该标志的 FileNotFoundError，而不会启动后再报告缺少项目工具。像 python3 这样的裸解释器名称则会在 PATH 中查找。

正确配置

在此处指向项目的虚拟环境，并确保其中安装了 pytest、pylint 和 mypy。以下示例适用于 Windows：

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

在 macOS 和 Linux 上，解释器则位于 bin 目录中：

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

错误配置

不要指向非项目环境中的解释器：

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

系统解释器或任何非项目环境中的虚拟环境都会报告缺少 pytest、pylint 和 mypy，并针对错误的软件包解析库和符号。如果项目自己的 .venv 中没有安装这三个工具，也会出现同样的问题——应将它们安装到该环境中，而不是将标志指向别处。

故障排除

• 启动时出现 “Python interpreter not found”：--python-executable 指向不存在的路径，通常是因为插入的环境变量未设置。错误消息会指出提供该路径的标志。
• 出现 “No module named pytest”（或 pylint/mypy）：--python-executable 指向的环境中没有安装所需工具。将它指向项目环境，并在该环境中安装这些工具。
• 出现 “ruff is not available”（或 black/isort/bandit/vulture/tach/lint-imports）：这些控制台脚本来自工具环境，而非 --python-executable，因此问题不在该标志。这些工具是 mcp-tools-py 的依赖项，错误消息会指出搜索过的工具环境目录：重新安装 mcp-tools-py 及其依赖项，然后重启服务。
• 安装缺失的工具后：pytest、pylint 和 mypy 通过对已配置解释器的探测来响应；该探测只运行一次，并在进程生命周期内缓存，因此安装这三个工具中的任何一个后，都要重启 MCP 服务。

安装

请参阅 INSTALL.md，了解详细的安装说明。

快速安装：

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

# Verify installation
mcp-tools-py --help

开发安装：

# 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 客户端配置

此服务可使用 mcp-config 进行配置。它是一个需要单独安装的 Python 工具，并非此软件包的依赖项。它提供：

• 交互式设置：适用于 Claude Desktop 和 VSCode
• 配置管理：添加、移除和查看服务配置
• 服务仓库：访问精选的 MCP 服务集合

**先决条件：**安装 Python，然后单独安装 mcp-config。

**注意：**虽然 Windsurf 和 Cursor 等其他 MCP 客户端支持 MCP 服务，但可能需要手动配置。

用作依赖项

在 requirements.txt 中

在你的 requirements.txt 中添加这一行：

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

在 pyproject.toml 中

将其添加到项目依赖项中：

[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",
]

安装命令

将其添加到 requirements.txt 或 pyproject.toml 后：

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

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

运行服务

使用 CLI 命令（推荐）

安装后，你可以使用 mcp-tools-py 命令运行服务：

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

使用 Python 模块（替代方式）

你也可以将服务作为 Python 模块运行：

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]

有关所有可用命令行选项的详细信息，请参阅 CLI 部分。

项目结构支持

此服务会自动检测并分析标准项目结构中的 Python 代码：

默认分析：

• src/ 目录（如果存在）——主源代码
• tests/ 目录（如果存在）——测试文件

自定义项目结构： 使用 target_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"]

结构化日志记录

此服务提供全面的日志记录功能：

• 标准的易读日志输出到控制台，供开发/调试使用
• 结构化 JSON 日志输出到文件，供分析和监控使用
• 函数调用跟踪，包含参数、耗时和结果
• 自动捕获错误上下文，包含完整堆栈跟踪
• 可配置的日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）
• 默认的带时间戳日志文件位于 project_dir/logs/mcp_tools_py_{timestamp}.log

结构化日志条目示例：

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

在简单的开发场景中，可使用 --console-only 禁用文件日志记录。

快速设置 MCP 客户端

自动设置（推荐）

1. 首先安装服务：

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

2. 使用 mcp-config 配置（需单独安装——此软件包不会安装它）：

   mcp-config
   

   然后选择“Add New”并搜索此服务。

系统会提示你输入项目目录，并自动配置 MCP 客户端。

**注意：**mcp-config 的服务注册表尚未收录 mcp-tools-py，因此如果找不到此服务，请使用下方的手动设置。

手动设置

如果你更倾向于手动配置，请编辑 MCP 配置文件：

Claude Desktop（Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

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

开发模式：

{
    "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 开发模式：

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

使用 MCP Inspector 进行测试

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

可用工具

该服务提供 19 个 MCP 工具。

工具	功能
run_pylint_check	静态分析；将发现的问题作为 LLM 可执行的提示词返回
run_pytest_check	运行测试套件，解析 JSON 报告并总结失败情况
run_mypy_check	根据项目的 [tool.mypy] 配置进行类型检查，并支持配置错误代码
run_ruff_check	Ruff lint 分析，只读
run_ruff_fix	原地应用 ruff 的安全修复；不安全的修复需选择启用
run_bandit_check	安全 lint
run_deptry_check	检查声明的依赖与导入项是否匹配（deptry）
run_vulture_check	根据 vulture_whitelist.py 检测无用代码
run_tach_check	根据 tach.toml 验证架构边界
run_lint_imports_check	根据 .importlinter 验证导入约定
run_format_code	按 pyproject.toml 的声明先运行 isort 再运行 black，或先运行 ruff 的导入排序再运行 ruff format；check_only 仅报告结果，不写入文件
list_symbols	列出文件中的顶层函数、类和变量
find_references	查找项目中某个符号的所有引用
move_symbol	将顶层符号移至其他模块，并更新导入
rename_symbol	在整个项目中重命名模块级符号
move_module	将模块移至其他包，并更新引用
get_library_source	在配置的项目环境中解析带点的导入路径并返回其源代码
search_library_files	在已安装包的源文件中进行 grep 或 glob 搜索，包括标准库
sleep	暂停执行指定秒数

pylint、pytest 和 mypy 的参数详见功能。

开发

设置开发环境

# 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]"

使用 MCP Dev Tools 运行

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

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

MIT 许可证是一种宽松的许可证，允许在几乎不受限制的情况下重复使用。只要注明出处，即可使用、复制、修改和分发。

链接

• MCP Python SDK
• MCP 文件系统工具