✨ Lucidity MCP 🔍

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 服务器

# 使用标准输入输出传输（适用于终端）
lucidity-mcp

# 使用 SSE 传输（适用于网络）
lucidity-mcp --transport sse --host 127.0.0.1 --port 6969

# 启用调试日志
lucidity-mcp --debug

# 使用文件日志
lucidity-mcp --log-file lucidity.log

与 AI 助手一起使用

1. 以 SSE 模式启动 Lucidity：

   lucidity-mcp --transport sse
   

2. 使用 MCP 协议 URI 连接您的 AI 助手：

   sse://localhost:6969/sse
   

3. 现在 AI 可以调用 analyze_changes 工具获取代码质量反馈！

🧠 分析维度

Lucidity 跨越 10 个关键质量维度分析代码：

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

📊 示例 AI 助手查询

连接到 Lucidity 的 AI 助手可以尝试以下查询：

• "分析我最新 git 变更的代码质量"
• "检查我的 JavaScript 变更中的安全漏洞"
• "确保我的 Python 代码遵循最佳实践"
• "识别我最近代码变更中的任何性能问题"
• "我最近的重构中有任何无意的副作用吗？"
• "帮助我改进代码中的抽象"
• "检查我是否意外删除了任何重要验证"
• "在我的最新提交中找到任何幻觉 API 调用"
• "我的错误处理是否完整且健壮？"
• "我的新功能中是否存在测试覆盖率差距？"

🛠️ 可用的 MCP 工具

工具

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

💻 开发

Lucidity 使用 UV 进行依赖管理和开发工作流。UV 是一个快速可靠的 Python 包管理器和解析器。

# 更新依赖
uv sync

# 运行测试
pytest

# 运行代码风格检查
ruff check .

# 运行类型检查
mypy .

🔧 日志行为

Lucidity 根据传输方式不同处理日志：

• SSE 传输：启用完整控制台日志
• stdio 传输带 --log-file：所有日志都写入文件，控制台被禁用
• stdio 传输不带 --log-file：仅警告和错误输出到 stderr，信息日志被禁用

这确保了 stdio 通信不会被出现在 stdout 上的日志中断。

🎛️ 命令行选项

usage: 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。

1. 分叉仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 使用 UV 设置开发环境
4. 进行您的更改
5. 运行测试和代码风格检查
6. 提交您的更改 (git commit -m '添加一些 amazing 功能')
7. 推送到分支 (git push origin feature/amazing-feature)
8. 打开 Pull Request

📝 许可证

本项目根据 Apache License 2.0 许可 - 详细内容请参阅 LICENSE 文件。