内容
# FailFast 开发者 MCP
**适用于开发者和 CI/CD 管道的首个 Python 生产就绪性审查工具。**
> _FailFast 不仅仅是检查代码 - 它会告诉你代码是否已经准备好上线。_
[](https://github.com/MErblin/failfast-developer-mcp/actions/workflows/ci.yml)
[](https://python.org)
[](LICENSE)
[](https://modelcontextprotocol.io)
---
## 问题
每个代码扫描工具都会回答：_“这里有 247 个问题。”_
**FailFast 回答：** _“这个拉取请求不适合生产，因为重试逻辑可能导致雪崩效应，两个 HTTP 调用没有超时，并且一个函数有 21 个执行路径。首先修复这 5 个问题。”_
这种区别很重要。
## 功能
FailFast 结合了 **确定性静态分析** （Ruff、Bandit、Radon）和 **基于 AST 的自定义生产检查** （超时检测、重试安全性分析），以生成单一的评判结果：**通过**、**失败** 或 **警告**。
每个发现结果都映射到行业标准 - OWASP、NIST、RFC 9457、AWS Well-Architected - 而不仅仅是一种观点。
| 类别 | FailFast 检查内容 | 参考标准 |
|---|---|---|
| **安全** | Bandit 发现的问题映射到 OWASP Top 10 | OWASP Top 10, 安全编码实践 |
| **可靠性** | HTTP 调用无超时， unsafe 重试模式（无抖动，无最大尝试次数，雪崩风险） | AWS Backoff & Jitter, OWASP API4:2023 |
| **可维护性** | 圈复杂度 > 15, Ruff lint 违规 | McCabe Metric, NIST SSDF PW.5 |
| **AI 安全** | 无边界的智能体循环（ReAct/Reflexion），缺少云安全/防护（Bedrock, Vertex, Azure OpenAI），原始 LLM 输出解析，缺少可观察性跟踪（Langsmith, Langfuse），缺乏缓存和备用策略。 | OWASP Top 10 for LLMs (LLM01-LLM09), AWS/GCP 企业 AI 指南 |
| **API 质量** | _(路线图：RFC 9457 错误契约，身份验证检查)_ | RFC 9457, OWASP ASVS |
| **依赖项** | _(路线图：pip-audit 集成)_ | OpenSSF Scorecard |
## 快速开始
### 命令行界面
```bash
# 安装
git clone https://github.com/MErblin/failfast-developer-mcp.git
cd failfast-developer-mcp
uv sync
# 扫描一个项目
uv run failfast scan /path/to/your/project
# 仅扫描更改的文件（PR 模式）
uv run failfast scan /path/to/your/project --diff main
# 输出 JSON 格式结果用于 CI
uv run failfast scan /path/to/your/project --format json
# 输出 Markdown 报告用于 PR 评论
uv run failfast scan /path/to/your/project --format markdown
# 输出 SARIF 格式结果用于 GitHub 代码扫描
uv run failfast scan /path/to/your/project --format sarif
# 检查单个类别
uv run failfast check /path/to/your/project --category reliability
# 解释发现规则
uv run failfast explain FF-RETRY
```
### MCP 服务器
连接到任何与 MCP 兼容的客户端（Claude Desktop, Cursor 等）：
```bash
# 启动 MCP 开发服务器
uv run mcp dev src/failfast/server.py
```
或添加到您的 MCP 客户端配置：
```json
{
"mcpServers": {
"failfast": {
"command": "uv",
"args": ["--directory", "/path/to/failfast-developer-mcp", "run", "mcp", "run", "src/failfast/server.py"]
}
}
}
```
**可用的 MCP 工具：**
| 工具 | 描述 |
|---|---|
| `scan(path, profile)` | 完整的生产就绪性扫描 |
| `scan_diff(path, base_ref)` | 仅扫描自 git 引用的更改文件 |
| `check(path, category)` | 运行单个分析类别 |
| `explain(finding_id)` | 获取发现规则的详细解释 |
### 退出代码
| 代码 | 含义 |
|:---:|---|
| `0` | ✅ 通过 - 生产就绪 |
| `1` | ❌ 失败 - 发现阻塞问题 |
| `2` | ⚠️ 警告 - 需要审查的警告 |
## 示例输出
```
failfast scan ./my-api-project
```
```
╭──────────────── FailFast 生产就绪性 ────────────────╮
│ 判决：失败 │
│ 不适合生产。3 个阻塞问题，2 个警告。 │
│ 路径：/home/dev/my-api-project │
│ 配置文件：python-api │
╰────────────────────────────────────────────────────────────────╯
类别摘要
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
┃ 类别 ┃ 判决 ┃ 阻塞问题 ┃ 警告 ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
│ 安全 │ 通过 │ 0 │ 0 │
│ 可靠性 │ 失败 │ 2 │ 1 │
│ 可维护性 │ 失败 │ 1 │ 1 │
│ API 质量 │ 通过 │ 0 │ 0 │
│ 依赖项 │ 通过 │ 0 │ 0 │
└─────────────────┴─────────┴──────────┴──────────┘
⛔ 阻塞问题
1. [FF-TIMEOUT-0042] HTTP 调用无超时：requests.get()
src/client.py:42
原因：HTTP 调用无显式超时可能导致无限期挂起...
解决方法：在 requests.get() 调用中添加 timeout=10。
参考：OWASP API4:2023, AWS Well-Architected
2. [FF-RETRY-NOJITTER-0087] 重试循环无抖动
src/client.py:87
原因：无抖动时，所有客户端同时重试（雪崩效应）...
解决方法：使用 `delay = min(max_delay, base * 2**attempt); sleep(random.uniform(0, delay))`
参考：AWS 指数退避和抖动
3. [FF-COMPLEXITY-D] 函数 'process_order' 的圈复杂度为 21
src/orders.py:15
原因：21 个执行路径 - 几乎无法穷举测试...
解决方法：提取帮助函数，使用提前返回，用查找表替换条件语句。
参考：McCabe 复杂度指标，NIST SSDF PW.5
```
## 架构
核心引擎是 **与传输无关** 的 - 它不知道 MCP 或 CLI。两者都是同一引擎上的薄适配器。
```
failfast-developer-mcp/
├── src/failfast/
│ ├── models.py # 发现结果、记分卡、判决、严重程度
│ ├── engine.py # 协调器 + 规则目录
│ ├── server.py # MCP 服务器（薄包装）
│ ├── cli.py # CLI（Click + Rich）
│ ├── analyzers/
│ │ ├── ruff.py # Ruff 检测器包装
│ │ ├── bandit.py # Bandit 安全包装 + OWASP 映射
│ │ ├── complexity.py # Radon CC 包装
│ │ ├── timeout.py ★ # 自定义 AST：HTTP 调用无超时
│ │ ├── retry.py ★ # 自定义 AST：不安全的重试模式
│ │ ├── ai_loops.py ★ # 自定义 AST：失控的智能体循环（无边界循环）
│ │ ├── ai_providers.py ★ # 自定义 AST：Bedrock / Vertex / Azure 配置防护
│ │ ├── ai_parsing.py ★ # 自定义 AST：不安全的 LLM JSON 加载解析
│ │ ├── ai_observability.py ★ # 自定义 AST：缺少 AI 跟踪（Langfuse, Langsmith）
│ │ ├── ai_guardrails.py ★ # 自定义 AST：缺少模型输入/输出防护
│ │ ├── ai_prompts.py ★ # 自定义 AST：硬编码的内联提示模板
│ │ ├── ai_cache.py ★ # 自定义 AST：缺少 LLM 完成缓存
│ │ └── ai_fallback.py ★ # 自定义 AST：缺少高可用性备用策略
│ └── reporters/
│ ├── json_reporter.py # 结构化 JSON
│ ├── markdown_reporter.py # 人类可读的报告
│ └── sarif_reporter.py # SARIF v2.1.0 用于 GitHub 代码扫描
└── tests/
├── fixtures/ # 故意构造的损坏 Python 文件
├── test_analyzers/ # 分析器单元测试
├── test_engine.py # 集成测试
├── test_models.py # 数据模型测试
└── test_reporters.py # 报告测试
```
**★ 自定义 AST 分析器** - 这些是区分因素。Ruff 和 Bandit 无法检测到缺少的 HTTP 超时、不安全的重试模式或 AI/智能体漏洞（失控循环、缺少防护、未缓存的完成、缺少跟踪/遥测和内联提示）。FailFast 可以。
### 分析器工作原理
每个分析器都实现了一个简单的协议：
```python
class Analyzer(Protocol):
@property
def name(self) -> str: ...
def analyze(self, context: AnalysisContext) -> list[Finding]: ...
```
添加新的分析器只需要一个文件和测试。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 为什么不使用 Ruff/Bandit/SonarQube？
FailFast 不会取代这些工具 - 它 **集成** 了它们，并添加了它们缺少的内容：
| 功能 | Ruff | Bandit | SonarQube | **FailFast** |
|---|:---:|:---:|:---:|:---:|
| 检测规则 | ✅ 900+ | ❌ | ✅ | ✅ via Ruff |
| 安全扫描 | 部分 | ✅ | ✅ | ✅ via Bandit |
| 缺少 HTTP 超时 | ❌ | ❌ | ❌ | **✅** |
| 不安全重试检测 | ❌ | ❌ | ❌ | **✅** |
| 雪崩风险 | ❌ | ❌ | ❌ | **✅** |
| 标准映射（OWASP/NIST） | ❌ | 部分 | 部分 | **✅** |
| 生产就绪性判决 | ❌ | ❌ | ✅ | **✅** |
| IDE/编辑器的 MCP 集成 | ❌ | ❌ | ✅ | **✅** |
| 无边界智能体循环检查 | ❌ | ❌ | ❌ | **✅** |
| AI 云防护验证 | ❌ | ❌ | ❌ | **✅** |
| 不安全的 LLM 输出解析 | ❌ | ❌ | ❌ | **✅** |
| 缺少 LLM 跟踪/可观察性 | ❌ | ❌ | ❌ | **✅** |
| 缺少 LLM 备用策略/缓存 | ❌ | ❌ | ❌ | **✅** |
| 免费和开源 | ✅ | ✅ | 增值 | **✅** |
## 路线图
- [x] 具有可插拔分析器协议的核心引擎
- [x] Ruff、Bandit、Radon 集成
- [x] 自定义 AST：超时检测
- [x] 自定义 AST：重试安全分析
- [x] 具有 Rich 终端输出的 CLI
- [x] 具有 4 个工具的 MCP 服务器
- [x] JSON、Markdown、SARIF 报告器
- [ ] pip-audit 依赖项扫描
- [ ] FastAPI 路由发现 + 身份验证检查
- [ ] RFC 9457 错误契约验证
- [ ] 生产配置文件（YAML 配置）
- [ ] GitHub Actions 可重用工作流
- [ ] PyPI 发布
## 开发
```bash
uv sync # 安装依赖
uv run pytest tests/ -v # 运行测试
uv run ruff check src/ tests/ # 检测
uv run failfast scan src/ # 自检：扫描自己
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取完整指南。
## 许可证
[MIT](LICENSE)
