MCP Python Auditor

MCP Python审计员

为Python项目设计的高性能代码库审计和重构工具。它将多个静态分析工具（Ruff、Bandit、Vulture、Radon）集成到一个具有缓存、并行执行和AI驱动见解的统一管道中。

主要特点

• 统一CLI：使用单个命令运行10多个工具(python audit.py .).
• 并行执行：用途 AuditOrchestrator 以最大速度同时运行工具。
• 智能缓存：缓存结果，以避免在未更改的代码上重新运行缓慢的工具。
• 交互模式：具有表情符号支持、分数分解和人工智能分析集成的CLI。
• 自动修复：可以自动修复常见的linting问题并升级易受攻击的软件包。
• MCP集成：将审计功能作为模型上下文协议（MCP）工具公开。

技术栈

• 语言：Python 3.11+
• 核心：FastAPI，Pydantic
• 静态分析:

- 拉夫：快速梳理和格式化 - 匪徒：安全扫描 - 秃鹫：死码检测 - 氡：复杂性分析 - 检测秘密：秘密扫描 - pip审计：依赖性漏洞检查

• 测试：Pytest，封面.py
• 协议：模型上下文协议（fastmcp）

先决条件

• python：3.11或更高
• Git：用于文件更改检测

入门指南

1.克隆存储库

git clone https://github.com/Amitro123/mcp-python-auditor.git
cd mcp-python-auditor

2.创建虚拟环境

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3.安装依赖项

pip install -r requirements.txt

4.执行审计

最简单的开始方法是使用交互式CLI：

python audit.py

或者直接运行快速审计（跳过secrets/coverage等慢速工具）：

python audit.py . --fast

使用指南

CLI选项

交互式功能

在交互模式下运行时，您可以：

1. 选择审核深度（完整与快速）
2. 查看缓存状态的详细进度
3. 获得分数（0-100）和等级（a-F）
4. 请求 AI分析 （通过Groq或Ollama）解释问题
5. 自动应用修复程序 常见问题（Ruff linting、升级、缓存清理）

建筑

该项目遵循为可扩展性和性能而设计的模块化架构。

目录结构

├── app/
│   ├── core/
│   │   ├── audit_orchestrator.py  # Main engine: manages tool execution & caching
│   │   ├── cli_adapter.py         # Adapts legacy CLI to orchestrator
│   │   ├── cache_manager.py       # Caching logic
│   │   └── report_generator.py    # Report generation logic
│   ├── tools/                     # Individual tool implementations
│   │   ├── bandit_tool.py
│   │   ├── fast_audit_tool.py     # Wraps Ruff (linting + complexity)
│   │   ├── deadcode_tool.py       # Wraps Vulture
│   │   └── ...
│   └── main.py                    # FastAPI entry point for MCP
├── audit.py                       # CLI entry point
├── pyproject.toml                 # Tool configuration (Ruff, Pytest, Bandit)
└── requirements.txt               # Project dependencies

核心组件

1.审计协调人(app/core/audit_orchestrator.py) 系统的大脑。它处理：

• 并行化：使用以下命令同时运行独立工具 asyncio.
• 缓存：检查文件哈希值以跳过冗余工作。
• 文件发现：使用Git/文件系统高效地列出项目文件。

2.CLI适配器(app/core/cli_adapter.py) 连接面向用户的桥梁 audit.py 使用编排器编写脚本。它通过将旧工具名称映射到新架构并格式化结果来确保向后兼容性。

3.工具(app/tools/) 每个静态分析工具都封装在一个专用类中，该类继承自 BaseTool这使得在不接触核心引擎的情况下添加新工具变得容易。

评分系统

审核分数（0-100）的计算基于：

• 安全性（-40分）：Bandit、Secrets或Pip Audit发现的漏洞。
• 质量（-35分）：敲击错误（Ruff）、死代码、重复。
• 分析（-25分）：测试覆盖率低、复杂性高、打字问题。

测试

运行测试套件以确保审核员本身正常工作：

# Run all tests
pytest

# Run with coverage
pytest --cov=app

# Run specific test file
pytest tests/test_audit.py

故障排除

“秃鹫超时”

如果 deadcode 检查时间太长（>120秒），这通常意味着它递归扫描了太多文件。 修复：确保 file_discovery.py 正确识别项目文件并将其传递给工具（在v2.0+中修复）。

“找不到命令”

确保所有依赖项都已安装，并且您处于虚拟环境中。 修复: pip install -r requirements.txt

“WinError 206:文件名和扩展名太长”

这是由于在Windows上的单个命令行中传递了太多文件造成的。 修复：The BaseTool 自动处理分块，将大文件列表拆分为更小的批。

许可证

MIT许可证。看 许可证 了解详情。