lucidity-mcp

Lucidity MCP 是一个专为提升 AI 生成代码质量而设计的 Model Context Protocol（MCP）服务器。它通过基于提示的智能分析，为 AI 编程助手提供结构化指导，帮助识别和修复代码中的常见质量问题，最终产出更干净、可维护且健壮的代码。

用途

Lucidity 的主要用途是在代码提交前，对 git 变更进行质量审查。它适合与支持 MCP 协议的 AI 助手（如 Claude）配合使用，让 AI 能够更有效地分析代码变更，避免因“氛围编程”（vibe-coding）而产生的潜在问题。

主要能力

Lucidity 覆盖 10 个关键质量维度的分析：

1. 不必要的复杂性：识别过于复杂的算法、过度抽象和 convoluted 逻辑。
2. 糟糕的抽象：检测泄漏或不恰当的抽象以及不清晰的关注点分离。
3. 意外的代码删除：捕捉关键功能或验证逻辑的意外移除。
4. 幻觉组件：查找对不存在的函数、类或 API 的引用。
5. 风格不一致：发现偏离项目编码标准和约定的地方。
6. 安全漏洞：识别代码变更中的潜在安全问题。
7. 性能问题：检测可能影响性能的低效算法或操作。
8. 代码重复：查找应重构的重复逻辑或功能。
9. 不完整的错误处理：发现缺失或不充分的异常处理。
10. 测试覆盖缺口：识别关键功能缺失的测试。

此外，它还具备以下特性：

• 上下文分析：将变更与原始代码对比，以识别非预期的修改。
• 语言无关：适用于 AI 助手能理解的任何编程语言。
• 聚焦分析：可根据项目需求选择特定问题类型进行分析。
• 结构化输出：引导 AI 提供可操作的反馈和清晰的建议。
• MCP 集成：与 Claude 及其他兼容 MCP 的 AI 助手无缝集成。
• 轻量级实现：简单的服务器设计，依赖极少。
• 可扩展框架：易于添加新问题类型或优化分析标准。
• 灵活传输：支持标准输入输出（stdio）用于终端交互，以及服务器发送事件（SSE）用于网络通信。
• Git 感知分析：直接分析 git diff 中的变更，非常适合提交前审查。

使用方式

1. 前提条件：Python 3.13 或更高版本、Git（用于分析代码变更）、UV 包管理器（推荐用于依赖管理）。
2. 启动 Lucidity 服务器。
3. 与 AI 助手配合使用：
   • 以 SSE 模式启动 Lucidity：lucidity-mcp --transport sse
   • 使用 MCP 协议 URI 连接 AI 助手：sse://localhost:6969/sse
   • AI 现在可以调用 analyze_changes 工具来获取代码质量反馈。

可用的 MCP 工具：

• analyze_changes：准备 git 变更以供通过 MCP 分析。 参数：
  • workspace_root：工作区/git 仓库的根目录。
  • path：可选的特定文件路径进行分析。

适用场景

• 代码提交前的质量审查。
• AI 生成代码后的质量检查。
• 希望提升代码质量、安全性和可维护性的开发团队。
• 需要针对特定问题类型（如安全漏洞、性能问题等）进行聚焦分析的场景。

限制

• 需要 Python 3.13 或更高版本。
• 需要 Git 环境。
• 推荐使用 UV 包管理器进行依赖管理。
• 需要与支持 MCP 协议的 AI 助手配合使用。
• 日志行为因传输方式而异：SSE 传输启用完整控制台日志；带 --log-file 的 stdio 传输将所有日志写入文件，禁用控制台；不带 --log-file 的 stdio 传输仅将警告和错误输出到 stderr，信息日志禁用。

该项目使用 Apache License 2.0 许可，由 Stefanie Jane 创建。