星战科技xingzhan.cloud
返回市场
代码检查器

代码检查器

作者：MarcusJellinghaus12 星标更新：2025-11-06
安装使用来源：spider==github.com

项目介绍

MCP Code Checker

一个提供代码质量检查操作的Model Context Protocol (MCP)服务器，具有简单的客户端配置。此服务器提供了一个API，用于在指定的项目目录中执行代码质量检查，遵循MCP协议设计。

概述

这个MCP服务器使像Claude（通过Claude Desktop）、VSCode与GitHub Copilot或其他兼容MCP的系统这样的AI助手能够对你的代码进行质量检查。借助这些能力，AI助手可以：

  • 运行pylint检查以识别代码质量问题
  • 执行pytest以识别失败的测试
  • 运行mypy进行类型检查
  • 生成智能提示供LLMs解释问题并提出修复建议
  • 结合多个检查进行全面的代码质量分析

所有操作都安全地限制在你指定的项目目录内，这给你提供了控制权，同时支持强大的AI协作以提高代码质量。

通过将你的AI助手连接到你的代码检查工具，你可以改变你的调试工作流程——用自然语言描述你需要什么，并让AI直接在你的项目文件中识别和解决问题。

功能

  • run_pylint_check: 在项目代码上运行pylint并为LLMs生成智能提示
  • run_pytest_check: 在项目代码上运行pytest并为LLMs生成智能提示
  • run_mypy_check: 对项目代码进行mypy类型检查
  • run_all_checks: 运行所有代码检查（pylint、pytest和mypy）并生成综合结果

Pylint 参数

pylint工具暴露了以下参数供自定义：

参数类型默认值描述
categories列表['error', 'fatal']要包含的pylint消息类别列表
disable_codes列表None分析期间要禁用的pylint错误码列表
target_directories列表["src", "tests"]相对于project_dir要分析的目录列表

目标目录示例：

  • ["src"] - 仅分析源代码目录
  • ["src", "tests"] - 分析源代码和测试目录（默认）
  • ["mypackage", "tests"] - 对于具有不同包结构的项目
  • ["lib", "scripts", "tests"] - 对于复杂的多目录项目
  • ["."] - 分析整个项目目录（大型项目可能较慢）

Pytest 参数

run_pytest_check和run_all_checks都暴露了以下参数供自定义：

参数类型默认值描述
markers列表None可选的pytest标记列表，用于筛选测试
verbosity整数2pytest的详细程度级别（0-3）
extra_args列表None可选的额外pytest参数列表
env_vars字典None子进程的可选环境变量

Mypy 参数

mypy工具暴露了以下参数供自定义：

参数类型默认值描述
strict布尔值True使用严格的模式设置
disable_error_codes列表None要忽略的mypy错误码列表
target_directories列表["src", "tests"]相对于project_dir要检查的目录列表
follow_imports字符串'normal'在类型检查期间处理导入的方式

命令行界面 (CLI)

基本用法

mcp-code-checker --project-dir /path/to/project [选项]

必需参数

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

可选参数

Python 配置

参数类型默认值描述
--python-executable字符串sys.executable用于运行测试的Python解释器路径
--venv-path字符串None要激活的虚拟环境路径。当指定了此路径时，将使用该虚拟环境中的Python而不是--python-executable

测试配置

参数类型默认值描述
--test-folder字符串"tests"测试文件夹的路径（相对于project-dir）
--keep-temp-files标志False在测试执行后保留临时文件。当测试失败时，这对于调试很有用

日志配置

参数类型默认值描述
--log-level字符串"INFO"设置日志级别。选择：DEBUG, INFO, WARNING, ERROR, CRITICAL
--log-file字符串None结构化JSON日志的路径。如果没有指定，则只记录到控制台
--console-only标志False只记录到控制台，忽略--log-file参数

注意事项

  • 当指定了--venv-path时，它会优先于--python-executable
  • 在开发过程中，--console-only标志有助于避免创建日志文件
  • 日志文件以JSON格式创建，便于结构化分析
  • 除非指定了--keep-temp-files，否则临时文件会被自动清理

安装

请参阅INSTALL.md获取详细的安装说明。

快速安装：

# 从GitHub安装（推荐）
pip install git+https://github.com/MarcusJellinghaus/mcp-code-checker.git

# 验证安装
mcp-code-checker --help

开发安装：

# 克隆并安装以供开发
git clone https://github.com/MarcusJ
Jellinghaus/mcp-code-checker.git
cd mcp-code-checker
python -m venv .venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
pip install -e ".[dev]"
mcp-code-checker --help

MCP客户端配置

此服务器可以通过mcp-configPython工具轻松配置。mcp-config工具提供：

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

前提条件：安装Python和mcp-config工具。

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

作为依赖项使用

在requirements.txt中

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

mcp-code-checker @ git+https://github.com/MarcusJellinghaus/mcp-code-checker.git

在pyproject.toml中

在你的项目依赖项中添加：

[project]
dependencies = [
    "mcp-code-checker @ git+https://github.com/MarcusJellinghaus/mcp-code-checker.git",
    # ... 其他依赖项
]

# 或作为可选依赖项
[project.optional-dependencies]
dev = [
    "m
mcp-code-checker @ git+https://github.com/MarcusJellinghaus/mcp-code-checker.git",
]

安装命令

在添加到requirements.txt或pyproject.toml之后：

# 从requirements.txt安装
pip install -r requirements.txt

# 从pyproject.toml安装
pip install .
# 或带有可选依赖项
pip install ".[dev]"

运行服务器

使用CLI命令（推荐）

安装后，你可以使用mcp-code-checker命令运行服务器：

mcp-code-checker --project-dir /path/to/project [选项]

作为Python模块运行（替代方法）

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

python -m mcp_code_checker --project-dir /path/to/project [选项]

# 或从源目录运行开发模式
python -m src.main --project-dir /path/to/project [选项]

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

项目结构支持

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

默认分析：

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

自定义项目结构： 使用target_directories参数指定不同的目录：

# 对于基于包的结构
target_directories = ["mypackage", "tests"]

# 对于根目录中有代码的简单项目
target_directories = ["."]

# 对于复杂的多模块项目
target_directories = ["module1", "module2", "shared", "tests"]

结构化日志

服务器提供了全面的日志功能：

  • 标准的人类可读日志到控制台，用于开发/调试
  • 结构化的JSON日志到文件，用于分析和监控
  • 函数调用跟踪，包括参数、时间以及结果
  • 自动捕获错误上下文，带有完整的堆栈跟踪
  • 可配置的日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）
  • 默认的时间戳日志文件在project_dir/logs/mcp_code_checker_{时间戳}.log

结构化日志条目示例：

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

使用--console-only来禁用文件日志记录，适用于简单的开发场景。

快速MCP客户端设置

自动设置（推荐）

  1. 首先安装服务器：

    pip install git+https://github.com/MarcusJellinghaus/mcp-code-checker.git

  2. 使用mcp-config配置：

    mcp-config

    然后选择“添加新”，搜索此服务器，或者直接运行：

    mcp-config mcp-code-checker

这将提示你输入项目目录，并自动配置你的MCP客户端。

手动设置

如果你更喜欢手动配置，请编辑你的MCP配置文件：

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

{
    "mcpServers": {
        "code_checker": {
            "command": "mcp-code-checker",
            "args": ["--project-dir", "/path/to/your/project"]
        }
    }
}

开发模式：

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

VSCode（.vscode/mcp.json）：

{
    "servers": {
        "code-checker": {
            "command": "mcp-code-checker",
            "args": ["--project-dir", "."]
        }
    }
}

VSCode开发模式：

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

使用MCP Inspector进行测试

npx @modelcontextprotocol/inspector mcp-code-checker --project-dir /path/to/project

可用工具

服务器公开了以下MCP工具：

运行Pylint检查

  • 在项目代码上运行pylint并为LLMs生成智能提示
  • 返回：包含pylint结果或供LLMs解释的提示字符串
  • 帮助识别代码质量问题、风格问题和潜在的bug
  • 可通过参数自定义，禁用特定的pylint代码和针对特定目录
  • 通过target_directories参数支持灵活的项目结构

运行Pytest检查

  • 在项目代码上运行pytest并为LLMs生成智能提示
  • 返回：包含pytest结果或供LLMs解释的提示字符串
  • 识别失败的测试并提供有关测试失败的详细信息
  • 可通过参数自定义测试选择、环境和详细程度

运行Mypy检查

  • 对项目代码进行mypy类型检查
  • 返回：包含mypy结果或供LLMs解释的提示字符串
  • 识别类型错误并提供更好的类型安全建议
  • 可通过参数自定义严格模式、错误码过滤和目标目录

运行所有检查

  • 运行所有代码检查（pylint、pytest和mypy）并生成综合结果
  • 返回：包含所有检查结果和/或LLMs提示的字符串
  • 提供单次操作的全面代码质量分析
  • 支持所有三个工具的自定义参数，包括目标目录

安全特性

  • 所有检查都在指定的项目目录内执行
  • 代码执行仅限于项目内的Python测试文件
  • 结果格式化以便人类和LLMs易于解读
  • 通过验证目标目录防止目录遍历攻击

开发

设置开发环境

# 克隆存储库
git clone https://github.com/MarcusJellinghaus/mcp-code-checker.git
cd mcp-code-checker

# 创建并激活虚拟环境
python -m venv .venv
# 在Windows上：
.venv\Scripts\activate
# 在Unix/MacOS上：
source .venv/bin/activate

# 安装依赖项
pip install -e .

# 安装开发依赖项
pip install -e ".[dev]"

使用MCP开发工具运行

# 设置PYTHONPATH并使用mcp dev运行服务器模块
set PYTHONPATH=. && mcp dev src/server.py

许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。

MIT许可证是一种宽松的许可证，允许在最小限制下重复使用。它允许使用、复制、修改和分发，只要适当归因即可。

链接