🧭 Vibe Check MCP

🧭 Vibe Check MCP

你的 AI 编码安全网，依托资深工程师的协作推理——毕竟，做到 90% 后卡上好几个星期，实在令人崩溃。

Vibe Check MCP v0.5.1 可防止你在 AI 生成的代码中把自己逼入绝境。它就像一支资深工程师团队在你身后把关，随时准备实时叫停糟糕的决策，并在你为无法修复的问题浪费好几天之前，帮你发现代价高昂的错误。

🧠 资深工程师协作推理

这项改变游戏规则的功能，能在灾难发生前真正防患于未然：

🚨 中断模式——及时叫停糟糕的决策

❌ You: "I'll build a custom HTTP client for this API"
✅ Mentor: "Have you checked if an official SDK exists?" (INTERRUPT!)

**当你即将犯下代价高昂的错误时，它真的会叫停你。**这就像一位资深工程师拍了拍你的肩膀，说：“嘿，等一下……”

🤝 多角色协作推理

同时获取来自多个工程视角的反馈：

• 👨‍💻 资深工程师：“这看起来像是过早优化。”
• 📋 产品经理：“这真的解决了用户的问题吗？”
• 🤖 AI/ML 工程师：“利用现有模型，有更简单的方案。”

🎯 它能防止的真实灾难：

• Auth0 已经存在，却还要构建自定义身份验证系统
• 已有 GraphQL 端点，却还要创建 REST API
• 库就能处理，却还要编写复杂的解析器
• Cognee 案例研究：发现已有官方 Docker 容器，避免了 2 周以上的自定义开发

专为 Claude Code MCP 集成打造——无缝集成到你现有的 Claude Code 工作流中，为你提供实时工程指导。

🎯 适合哪些人？

有没有花了好几个星期开发某个功能，最后才发现只需调用一个简单的 API？

你并不孤单。Vibe Check 专为氛围编码者设计——他们热爱 AI 编码工具，但需要有人帮忙把关，避免掉入 AI 经常造成的过度工程化陷阱。

如果你对以下情况感同身受：

🔥 “我花了 $417 用 Claude 开发文字游戏，结果发现 AI 生成的代码没有服务端验证，整个《蜜蜂总动员》的剧本都能用来发起 DDoS 攻击”
🔥 “大模型把整个 iOS 应用的数据库写进了 CSV 文件，而不是 Core Data——我完全没意识到！”
🔥 “把错误贴回 ChatGPT，让它继续生成代码，直到代码永远在两种错误状态之间来回振荡” 🔥 “人们已经开始不了解自己写的代码究竟在做什么。AI 能帮你更快地把代码写出来，但代码出问题时，调试和修复可能会困难得多”

如果你符合以下情况，你就是我们的目标用户：

• 🎮 热爱 AI 编码工具——使用 Claude、Cursor、Copilot，但有时会怀疑建议是否过度工程化
• 🤔 信任但希望验证——对 AI 方案感到兴奋，却缺乏深入的库知识来验证它们
• 🔄 陷入恶性循环——每次 AI 修复都会引发新问题，一次次循环往复
• 📚 不像专业人士那样审查代码——不做深入的技术审查就接受 AI 建议（这完全正常！）
• ⚡ 重视速度胜过完美——更喜欢能正常运行的方案，而不是架构上完美无缺的方案

你面临的实际痛点：

• 安全盲区：AI 自信地生成缺少关键验证的代码（例如，价值 417 美元的游戏遭到黑客攻击）
• 恶性循环：代码变更在错误状态之间不断反复，浪费数小时
• 过时方案：AI 推荐已弃用的做法，而非当前最佳实践
• 理解能力丧失：代码不可避免地出问题时，你无法调试 AI 编写的代码
• 混合语言语法：AI 在 Rust 代码中导入 Go 库，或做出其他毫无道理的混搭
• 自信满满地答错：AI 对完全错误的信息也说得头头是道

Vibe Check MCP 是你的 AI 编码安全网，让你享受氛围编码乐趣的同时，避开代价高昂的陷阱。

🎯 功能介绍

Vibe Check MCP 提供 三种分析模式，帮助你在工程反模式酿成代价高昂的错误之前及时发现它们：

🧠 资深工程师导师（通过 MCP Sampling 集成增强！）

• 动态生成响应：通过原生 MCP 协议实现，无需 API 密钥
• 协作推理：由多个工程角色共同分析
• 混合路由：在静态（快速）和动态（灵活）响应之间切换
• 中断模式：实时阻止错误决策
• 架构指导：协助处理复杂的技术决策
• Claude 模型选择：根据分析需求选择 Haiku/Sonnet/Opus
• 亚毫秒级核心组件：具备企业级效率

🚀 快速分析（即时反馈）

• 快速检测模式：无需调用外部 API
• GitHub issue 分析：发现规划阶段的反模式
• PR 指标和基本审查：适用于开发工作流
• 文本分析：分析技术文档和计划

🧠 深度分析（全面审查）

• Claude 驱动的推理：检测复杂的反模式
• 教育性说明：解释这些模式为何有问题
• 真实案例研究：例如 Cognee 集成的经验教训
• 可执行的预防指导：提供具体的补救步骤

检测的核心反模式

验证结果：全面测试中，检测准确率为 87.5%，误报率为 0%，组件延迟低于 1 毫秒。

⚡ 全新：原生 MCP Sampling 集成（v0.5.1）

革命性的动态响应生成功能，让 Vibe Check 与所有竞品脱颖而出：

🚀 主要竞争优势

• 🔐 无需 API 密钥：原生 MCP 协议集成，完全离线运行
• ⚡ 优化的性能：具备企业级效率，核心组件延迟低于 1 毫秒
• 🧠 混合智能：在静态响应（<100ms）和动态生成（~2000ms）之间智能路由
• 🛡️ 内置安全防护：自动脱敏密钥、防止注入攻击并限制速率
• 🔄 熔断器模式：优雅降级，确保任何情况下都能可靠运行

🎯 工作原理

# High confidence queries → Static response (50ms)
"Use official Stripe SDK instead of custom HTTP client"

# Low confidence queries → Dynamic MCP sampling (2000ms)  
"Analyze this complex microservice architecture for anti-patterns"

# Hybrid approach for balanced speed/flexibility (500ms)
"Review this FastAPI + Supabase integration approach"

📊 性能指标

• 缓存命中优化：常见查询的延迟降低 85%
• P95 延迟：动态生成约为 2000 毫秒（远低于 3 秒目标）
• 静态响应：低于 100 毫秒，提供即时反馈
• 回退保护：30 秒超时后自动恢复

这项原生 MCP 集成无需管理外部 API，同时提供企业级性能与安全性。

🎯 新增：项目感知型上下文分析

告别泛泛而谈的建议！Vibe Check 现在能够理解你的特定技术栈，并提供针对具体库的建议。

❌ 之前（通用建议）

User: "Should I build a custom authentication system?"
Vibe Check: "Generally, avoid custom auth. Use established libraries."

✅ 之后（项目感知型）

User: "Should I build a custom authentication system?"
Vibe Check: "I see you're using FastAPI + Supabase. Supabase has built-in auth with 
JWT tokens and Row Level Security. Use the @supabase/auth-js client for 
frontend auth state management. This eliminates the need for custom auth entirely."

🏗️ 三层上下文系统

1. 🔍 库检测引擎

   • 自动扫描项目文件和依赖项
   • 可检测：FastAPI、React、Supabase、GitHub 集成、OpenAI 用法
   • 置信度评分：FastAPI 为 95%，Supabase 为 87%，React 为 92%

2. 📖 项目文档解析器

   • 读取 README.md、CONTRIBUTING.md、docs/
   • 提取团队规范和架构决策
   • 理解你的具体模式和例外情况

3. 🧠 上下文感知分析

   • 高级工程师：“对于 FastAPI + Supabase，使用内置的 RLS 身份验证”
   • 产品工程师：“Supabase 身份验证通过 @supabase/auth-js 与 React 集成”
   • AI 工程师：“利用 Supabase 的用户嵌入向量实现 ML 功能”

🛠️ 新增 MCP 工具

• detect_project_libraries - 扫描代码库以识别技术栈
• load_project_context - 获取全面的项目分析
• create_vibe_check_directory_structure - 设置 .vibe-check/ 配置

📖 完整的上下文文档指南 →

🛡️ 企业级安全功能

适用于生产环境的安全保障，不影响性能：

🔒 自动安全防护

• 机密检测与脱敏：自动识别并脱敏 API 密钥、密码和令牌
• 提示词注入防护：通过模式匹配防止恶意提示词操纵
• 路径验证：防止符号链接攻击和未经授权的文件访问
• 速率限制：每个会话每分钟 10 个请求，防止滥用
• 超时保护：限制为 30 秒，并提供平稳回退

📊 安全性能

• 性能优化：静态路径约 0.1ms，动态路径约 2000ms
• 已缓解 12 个漏洞：通过内置安全层提供全面防护
• 熔断恢复：安全事件发生后自动在 60 秒内恢复
• 无外部依赖项：所有安全功能均在 MCP 协议内部本地运行

🏢 企业优势

• 满足合规要求：数据不会离开你的环境
• 审计跟踪：提供全面的日志记录，便于安全审查
• 离线运行：无需互联网连接即可运行
• 零配置：默认启用安全功能

非常适合需要 AI 助手、又不想降低安全态势的团队。

⚡ 快速开始

前置条件

• 已安装并配置 Claude Code
• Python 3.8+ 和 pip
• GitHub 令牌（可选，用于 GitHub 集成）

🚀 安装选项

选择最适合你的设置的安装方式：

🎯 选项 1：NPX（即时设置）——推荐！

# Run directly without installation
npx vibe-check-mcp --stdio

# Add to Claude Code MCP config with GitHub token (for private repos)
claude mcp add vibe-check-npm -e GITHUB_TOKEN="your_github_token_here" -- npx vibe-check-mcp --stdio

# Or without GitHub token (public repos only)
claude mcp add vibe-check-npm -- npx vibe-check-mcp --stdio

优势：

• ✅ 无需本地安装
• ✅ 始终运行最新版本（v0.5.1+）
• ✅ 自动管理 Python 依赖项（aiohttp、PyYAML 等）
• ✅ 跨平台兼容
• ✅ MCP 服务连接可靠（在 v0.5.1 中通过 MCP sampling 增强）
• ✅ 可选 GitHub 令牌，用于分析私有代码库

🎯 选项 2：Smithery（生产环境推荐）

npx -y @smithery/cli install vibe-check-mcp --client claude

优势：

• ✅ 安装包含所有依赖项的 Vibe Check MCP
• ✅ 自动配置 Claude Code MCP 集成
• ✅ 设置适当的环境变量
• ✅ 验证安装和服务健康状态
• ✅ 通过 Smithery 启用自动更新
• ✅ 适用于生产环境的配置

🎯 选项 3：本地开发设置

非常适合为项目做贡献或自定义服务：

# 1. Clone and install dependencies
git clone https://github.com/kesslerio/vibe-check-mcp.git
cd vibe-check-mcp
pip install -r requirements.txt

# 2. Test server locally
PYTHONPATH=src python -m vibe_check.server --help

# 3. Add local development server to Claude Code (with GitHub token)
claude mcp add vibe-check-local -e PYTHONPATH="$(pwd)/src" -e GITHUB_TOKEN="your_github_token_here" -- python -m vibe_check.server --stdio

# Or without GitHub token (public repos only)
claude mcp add vibe-check-local -e PYTHONPATH="$(pwd)/src" -- python -m vibe_check.server --stdio

# 4. Restart Claude Code

适合本地开发的情况：

• ✅ 为项目做贡献
• ✅ 自定义反模式检测规则
• ✅ 添加新工具或功能
• ✅ 测试尚未发布的更改

🎯 选项 4：手动安装（高级）

# 1. Clone and install
git clone https://github.com/kesslerio/vibe-check-mcp.git
cd vibe-check-mcp
pip install -r requirements.txt

# 2. Add to Claude Code with GitHub token
claude mcp add vibe-check -e PYTHONPATH="$(pwd)/src" -e GITHUB_TOKEN="your_github_token_here" -- python -m vibe_check.server --stdio

# Or without GitHub token (public repos only)
claude mcp add vibe-check -e PYTHONPATH="$(pwd)/src" -- python -m vibe_check.server --stdio

# 3. Restart Claude Code and start using!

💡 **Tip**: Add `-s project` to share with your team via .mcp.json, or `-s user` to use across all your projects.

🎯 选项 5：基于脚本的安装

curl -fsSL https://raw.githubusercontent.com/kesslerio/vibe-check-mcp/main/install.sh | bash

🔧 配置

🔐 设置 GitHub 令牌

以下情况需要： 私有仓库、组织仓库、更高的速率限制

适用场景：

• ✅ 分析私有 GitHub 仓库
• ✅ 分析组织仓库
• ✅ 更高的 API 速率限制（每小时 5000 次，而非 60 次）
• ❌ 分析公开仓库时不需要

如何获取 GitHub 令牌：

1. 前往 GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. 点击“Generate new token (classic)”
3. 选择以下权限：
   • ✅ repo（用于访问私有仓库）
   • ✅ read:org（用于访问组织仓库）
4. 复制令牌（以 ghp_ 开头）

如何使用令牌：

# Option A: Set as environment variable (recommended)
export GITHUB_TOKEN="ghp_your_token_here"
# Add to ~/.zshrc or ~/.bashrc for persistence

# Option B: Pass directly in MCP config (see installation options above)

安全提示： 请妥善保管令牌！不要将其提交到版本控制系统。

⚙️ 工具架构配置（Issue #237）

根据使用需求控制公开哪些工具：

生产模式（默认）- 30 个工具：

# No environment variables needed - this is the default
# Includes all core anti-pattern detection and analysis tools

诊断模式 - 额外提供 11 个诊断工具：

export VIBE_CHECK_DIAGNOSTICS=true

# Enables:
# - Claude CLI diagnostics (2 tools: status, diagnostics)
# - Configuration validation (2 tools: validate_mcp, check_integration)
# - Async LLM monitoring (7 tools: async analysis, health, metrics, status)

开发模式 - 额外提供 2 个开发/实验性工具：

export VIBE_CHECK_DEV_MODE=true

# Enables:
# - demo_large_prompt_handling (experimental features)
# - reset_session_tracking (dev utility)

综合测试模式：

export VIBE_CHECK_DEV_MODE_OVERRIDE=true

# Enables all dev tools + comprehensive test suite
# For contributors and advanced debugging

基于环境变量进行限制的优势：

• ✅ 默认工具数量减少 30%（43 → 30 个工具）
• ✅ 每次请求约节省 650 个令牌
• ✅ 为最终用户提供更清晰的工具发现体验
• ✅ 外观更专业（不公开内部测试工具）
• ✅ 需要排查问题时可选择启用诊断功能
• ✅ 向后兼容——所有工具仍然可用

🚀 Claude Code 快速设置

由于本项目专为集成 Claude Code 而设计，以下是最快的设置方法：

步骤 1：添加到 Claude Code（推荐）

# With GitHub token (for private repositories)
claude mcp add vibe-check -e GITHUB_TOKEN="your_github_token_here" -- npx vibe-check-mcp --stdio

# Or without GitHub token (public repositories only)
claude mcp add vibe-check -- npx vibe-check-mcp --stdio

步骤 2：重启 Claude Code

# Restart Claude Code to load the new MCP server
# No installation, dependencies, or local setup required!

步骤 3：测试是否正常运行

# Test that the MCP server is working
claude "Show vibe check server status"

# Test a quick analysis
claude "Quick vibe check: analyze this text for any engineering anti-patterns"

🔍 验证安装

# Check Claude Code version and MCP integration
claude --version

# Test the mentor feature (Enhanced in v0.5.1 with MCP sampling)
claude "Should I build a custom HTTP client for the Stripe API?"

# Test fast pattern detection
claude "Quick vibe check issue 42"

GitHub 令牌权限（用于 GitHub 集成）：

• ✅ repo（用于访问私有仓库）
• ✅ read:org（用于访问组织仓库）

故障排查：

• 私有仓库出现“HTTP 404”错误：检查 GitHub 令牌是否具有 repo 权限范围
• 找不到 MCP 服务：安装后重启 Claude Code
• 导入错误：确保已安装 Python 3.8+ 和相关依赖项

🚀 使用示例

🧠 资深工程师导师（全新！）

# Get architectural guidance
"Should I build a custom auth system for this project?"
→ 🤝 Multi-persona feedback from Senior Engineer, Security Expert, Product Manager

# Interrupt mode for real-time prevention
"I'm planning to build a custom HTTP client for the Stripe API"
→ 🚨 INTERRUPT: "Have you checked if stripe-python SDK exists?"

# Claude model selection for different analysis depths
"Use Haiku to quickly validate this API design"
"Use Opus for deep architectural review of this microservice"

自然语言命令

# Quick pattern detection (fast)
"Quick vibe check issue 42"
"Fast analysis of this PR"
"Basic check on this technical document"

# Deep analysis with educational coaching
"Deep vibe check issue 42 with full Claude analysis"
"Comprehensive review of this integration plan"
"Analyze this code for over-engineering patterns"

防止实际故障

# Before building integrations
"Validate building custom HTTP client for Stripe API"
→ ⚠️ Risk detected: Use stripe-python SDK instead

# During code review
"Review this PR for complexity anti-patterns"
→ 🎓 Educational: Why this abstraction adds unnecessary complexity

# Planning phase analysis
"Analyze issue 23 for infrastructure anti-patterns"
→ 🛡️ Prevention: Research official SDK before building custom solution

📊 Vibe Check 的重要性

防止系统性故障

• Cognee 案例研究：由于没有使用文档中说明的 API，而是构建自定义解决方案，导致数天的无谓工作
• 行业研究：43% 的集成失败源于“有基础设施、无实现”的模式
• 节约成本：常规用户的集成失败率平均降低 40%

教育式方法

与只标记问题的代码分析工具不同，Vibe Check 会解释：

• 为什么这些模式有问题，并提供真实案例研究
• 这些问题如何随着时间推移累积成技术债务
• 应该做什么，并提供具体的预防步骤

🛠️ 提供 45+ 个 MCP 工具

核心分析工具：

安全与配置工具：

• 配置验证与诊断
• Claude CLI 集成健康检查
• 异步分析系统监控
• 项目上下文检测与库扫描

总计 45+ 个工具，涵盖上下文文档、恶性循环检测、生产力干预和全面调试能力。

🧠 全新导师工具功能：

• 多角色推理，提供资深工程师、产品经理和安全专家视角
• 中断模式，实时防止错误决策
• Claude 模型选择（Haiku 速度快，Sonnet 均衡，Opus 深度强）
• 协作会话，在多个问题之间保留上下文

📖 文档

• 使用指南 - 完整示例和命令
• 技术架构 - 实现细节与验证
• 产品需求 - 愿景、市场分析与路线图
• 贡献指南 - 如何贡献新模式与功能

🚀 部署选项

原生部署（推荐）

• 启动快速（约 2s），内存占用低（约 50MB）
• 通过 Python 直接集成 Claude Code

Docker

• 通过容器化部署实现隔离
• 包含所有依赖项和环境配置

桥接模式

• 适用于复杂环境或故障排查
• 提供详细日志和调试能力

完整配置说明请参阅 MCP 部署指南。

🎯 实际影响

🧠 资深工程师指导（在 v0.5.1 中通过 MCP 采样增强）

• 之前：独自做出代价高昂的架构决策
• 之后：在确定方案前获得多角色反馈
• 影响：中断模式已在我们的开发中避免了多起工程灾难

预防技术债务

• 之前：团队花费数月构建无法奏效的定制解决方案
• 之后：在规划阶段发现基础设施反模式，并获得教育性指导

教育性辅导

• 之前：在不同项目中反复犯架构错误
• 之后：通过真实失败案例研究，学习具体的预防策略

赋能个人

• 之前：依赖不一致的同行评审流程
• 之后：将个人辅导系统集成到开发工作流中

🤝 贡献

欢迎贡献！Vibe Check MCP 由社区打造，服务社区。

优先级较高的贡献：

• 🎯 新的反模式检测算法
• 📚 教育内容和真实案例研究
• 🛠️ MCP 工具增强与性能改进

详细指南请参阅 CONTRIBUTING.md。

📊 验证与结果

• ✅ 在经过验证的模式测试套件中，检测准确率达 87.5%
• ✅ 对已知良好的架构决策，误报率为 0%
• ✅ 延迟经过优化——满足企业级效率要求
• ✅ 响应时间 <30s，适用于实时开发工作流
• ✅ 原生集成 MCP 协议，无需 API 密钥
• ✅ 提供 45+ 个专用工具，覆盖全面的开发工作流
• ✅ 经真实工程失败分析案例验证

📄 许可证

Apache 2.0 许可证——详情请参阅 LICENSE。

🙏 致谢

基于 FastMCP 构建，旨在与 Claude Code 无缝集成。

准备好防止下一次工程故障了吗？

安装 Vibe Check MCP v0.5.1，获得一位具备上下文感知能力、真正能在灾难发生前加以防范的资深工程师导师。

🚀 立即获取 v0.5.1 | 📖 发行说明 | 🧠 试用 MCP Sampling 集成

🏆 为何 Vibe Check MCP 引领市场

唯一原生集成 MCP sampling 的 AI 编码助手：

原生 MCP 集成为你提供企业级 AI 助手能力，无需承受企业级复杂性。

别再构建错误的东西。开始更快地构建正确的东西。

🧪 测试

Vibe Check MCP 包含全面的测试覆盖，其中包括用于 MCP 集成的 E2E 测试。

前置条件

Python 测试：

pip install -r requirements.txt

Node E2E 测试：

npm install  # Installs mcp-test-client and dependencies

运行测试

Python 单元测试：

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/unit/test_response_relevance_validator.py -v

Node E2E 测试：

# Run individual E2E tests
node tests/e2e/mcp/mentor_basic.mjs               # Basic mentor functionality
node tests/e2e/mcp/mentor_interrupt_mode.mjs      # Interrupt mode validation
node tests/e2e/mcp/mentor_relevance.mjs           # Response relevance guard

# Run via pytest wrapper (skips if mcp-test-client not installed)
pytest tests/e2e/test_mentor_relevance_e2e.py -v

E2E 测试功能

• 自动传递 PYTHONPATH - 无需 pip install -e .
• 妥善清理服务 - SIGTERM/SIGKILL 回退机制可防止遗留进程
• 验证响应相关性 - 防止返回预设或无关的响应
• 缺少 Node 软件包时平稳跳过 - 不会阻碍开发工作流

测试覆盖范围

故障排除

MCP 服务连接问题

问题： 服务报错 log_level validation error 或 Input should be 'DEBUG', 'INFO', 'WARNING', 'ERROR' or 'CRITICAL'

原因： FastMCP 对环境变量采用区分大小写的验证。像 LOG_LEVEL=error 这样的值会导致失败。

解决方案： 确保 .env 文件中的 LOG_LEVEL 为大写：

# ❌ This will fail
LOG_LEVEL=error

# ✅ This works
LOG_LEVEL=ERROR

服务无法启动

1. 检查 Python 路径： 确保 PYTHONPATH 包含 vibe-check-mcp 源目录
2. 验证依赖项： 运行 pip install -r requirements.txt
3. 检查日志： 在启动输出中查找具体错误消息
4. 测试基本连接： 尝试直接运行 python -m vibe_check.server --stdio