项目介绍
✨ Lucidity MCP 🔍
<div align="center">
代码清晰，创作自信
</div>Lucidity 是一个模型上下文协议（MCP）服务器，旨在通过智能、基于提示的分析来提高AI生成代码的质量。通过向AI编码助手提供结构化的指导，Lucidity有助于识别并解决常见的质量问题，从而产生更干净、更易于维护且更健壮的代码。
在提交之前，请让Lucidity分析更改，而不是自己陷入混乱的编程噩梦！ 😱 💥 🚫
💫 特性
- 🔮 全面问题检测 - 覆盖从复杂度到安全漏洞的10个关键质量维度
- 🔄 上下文分析 - 将更改与原始代码进行比较，以识别无意的修改
- 🌐 语言无关 - 可以与任何AI助手理解的编程语言一起工作
- 🎯 聚焦分析 - 根据项目需求选择特定的问题类型进行分析
- 📝 结构化输出 - 引导AI提供可操作的反馈和明确的建议
- 🤖 MCP集成 - 无缝集成到Claude和其他兼容MCP的AI助手
- 🪶 轻量级实现 - 简单的服务器设计，依赖项最少
- 🧩 可扩展框架 - 容易添加新的问题类型或细化分析标准
- 🔀 灵活传输 - 支持用于终端交互的stdio和用于网络通信的SSE
- 🔄 Git感知分析 - 直接从git diff分析更改，非常适合预提交审查
🚀 安装
# 克隆仓库
git clone https://github.com/hyperbliss/lucidity-mcp.git
cd lucidity-mcp
# 使用UV设置虚拟环境
uv venv .venv
source .venv/bin/activate # 在Windows上：.venv\Scripts\activate
# 使用UV安装依赖项
uv sync
📋 先决条件
- Python 3.13 或更高版本
- Git（用于分析代码更改）
- UV 包管理器（推荐用于依赖项管理）
🔮 快速开始
运行Lucidity服务器
# 使用stdio传输启动（适用于终端使用）
lucidity-mcp
# 使用SSE传输启动（适用于网络使用）
lucidity-mcp --transport sse --host 127.0.0.1 --port 6969
# 启用调试日志
lucidity-mcp --debug
# 启用文件日志
lucidity-mcp --log-file lucidity.log
与AI助手配合使用
-
在SSE模式下启动Lucidity：
lucidity-mcp --transport sse -
使用MCP协议URI连接您的AI助手：
sse://localhost:6969/sse -
现在AI可以调用
analyze_changes工具来获取代码质量反馈！
🧠 分析维度
Lucidity跨10个关键质量维度分析代码：
- 不必要的复杂性 - 识别过于复杂的算法、过度抽象和复杂的逻辑
- 差的抽象 - 检测泄漏或不适当的抽象以及不清楚的关注点分离
- 意外代码删除 - 捕获意外删除的关键功能或验证
- 幻觉组件 - 查找对不存在的功能、类或API的引用
- 风格不一致 - 发现偏离项目编码标准和惯例的地方
- 安全漏洞 - 识别代码更改中的潜在安全问题
- 性能问题 - 检测可能影响性能的低效算法或操作
- 代码重复 - 查找应重构的重复逻辑或功能
- 不完整的错误处理 - 发现缺失或不足的异常处理
- 测试覆盖率缺口 - 识别关键功能的缺失测试
📊 示例AI助手查询
连接到Lucidity的AI助手可以尝试以下查询：
- "分析我最新的git更改的代码质量"
- "检查我的JavaScript更改中的安全漏洞"
- "确保我的Python代码遵循最佳实践"
- "识别我在最近的代码更改中的任何性能问题"
- "最近的重构是否有任何意外的副作用？"
- "帮助我改进代码中的抽象"
- "确认我没有意外地删除任何重要的验证"
- "查找我最新提交中的幻觉API调用"
- "我的错误处理是否完整且健壮？"
- "新功能中是否存在任何测试覆盖率缺口？"
🛠️ 可用的MCP工具
工具
analyze_changes- 准备git更改以通过MCP进行分析- 参数：
workspace_root：工作区/ git仓库的根目录path：要分析的特定文件路径（可选）
- 参数：
💻 开发
Lucidity使用UV进行依赖管理和开发流程。UV是一个快速可靠的Python包管理和解析器。
# 更新依赖项
uv sync
# 运行测试
pytest
# 运行代码检查
ruff check .
# 运行类型检查
mypy .
🔧 日志行为
根据传输方式，Lucidity处理日志的方式不同：
- SSE传输：启用完整的控制台日志
- 带有--log-file的stdio传输：所有日志都写入文件，禁用控制台
- 没有--log-file的stdio传输：仅警告和错误写入stderr，禁用info日志
这确保了日志不会破坏stdio通信。
🎛️ 命令行选项
用法：lucidity-mcp [-h] [--debug] [--host HOST] [--port PORT] [--transport {stdio,sse}]
[--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--verbose]
[--log-file LOG_FILE]
选项：
-h, --help 显示此帮助信息并退出
--debug 启用调试日志
--host HOST 绑定服务器的主机（使用0.0.0.0绑定所有接口）
--port PORT 监听网络连接的端口
--transport {stdio,sse}
使用的传输类型（stdio用于终端，sse用于网络）
--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
设置日志级别
--verbose 启用HTTP请求的详细日志
--log-file LOG_FILE 日志文件路径（对于stdio传输，如果启用了日志，则需要）
🤝 贡献
欢迎贡献！请随意提交Pull Request。
- 分叉仓库
- 创建您的功能分支（
git checkout -b feature/amazing-feature） - 使用UV设置开发环境
- 进行更改
- 运行测试和代码检查
- 提交更改（
git commit -m '添加一些惊人的功能'） - 推送到分支（
git push origin feature/amazing-feature） - 打开Pull Request
📝 许可证
本项目采用Apache许可证2.0 - 详情见LICENSE文件。
<div align="center">
由 Stefanie Jane 🌠 创建
如果您觉得Lucidity有用，请我喝一杯Monster Ultra Violet ⚡️
</div>