✨ 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 助手一起使用

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 助手查询

在 AI 助手连接到 Lucidity 后，尝试以下查询：

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

🛠️ 可用的 MCP 工具

工具

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

💻 开发

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

# 更新依赖
uv sync

# 运行测试
pytest

# 运行 linting
ruff check .

# 运行类型检查
mypy .

🔧 日志行为

Lucidity 根据传输方式以不同的方式处理日志记录：

• SSE 传输: 启用完整的控制台日志记录
• 带有 --log-file 的 Stdio 传输: 所有日志都写入文件，控制台被禁用
• 没有 --log-file 的 Stdio 传输: 只有警告和错误会输出到 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]

options:
  -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. Fork 仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 使用 UV 设置您的开发环境
4. 进行更改
5. 运行测试和 linting
6. 提交您的更改 (git commit -m 'Add some amazing feature')
7. 推送到分支 (git push origin feature/amazing-feature)
8. 打开一个 Pull Request

📝 许可证

该项目根据 Apache License 2.0 获得许可 - 有关详细信息，请参阅 LICENSE 文件。

---

<div align="center">

由 Stefanie Jane 🌠 创建

如果您觉得 Lucidity 有用，请给我买一罐 Monster Ultra Violet ⚡️

</div>