✨ Lucidity MCP 🔍

✨ Lucidity MCP 🔍

Lucidity 是一款模型上下文协议（MCP）服务，旨在通过智能的提示词分析提升 AI 生成代码的质量。Lucidity 为 AI 编码助手提供结构化指导，帮助发现并解决常见的质量问题，从而产出更简洁、更易维护、更稳健的代码。

提交之前，不妨让 Lucidity 分析一下改动，别再凭感觉写代码，把自己带进噩梦般的困境！😱 💥 🚫

💫 功能

• 🔮 全面的问题检测 - 覆盖从复杂性到安全漏洞的 10 个关键质量维度
• 🔄 上下文分析 - 将改动与原始代码进行比较，找出非预期的修改
• 🌐 语言无关 - 支持 AI 助手能够理解的任何编程语言
• 🎯 聚焦分析 - 可根据项目需求选择特定的问题类型进行分析
• 📝 结构化输出 - 引导 AI 提供可执行的反馈和明确的建议
• 🤖 MCP 集成 - 与 Claude 和其他兼容 MCP 的 AI 助手无缝集成
• 🪶 轻量实现 - 服务设计简单，依赖项极少
• 🧩 可扩展框架 - 易于添加新的问题类型或完善分析标准
• 🔀 灵活传输 - 同时支持用于终端交互的 stdio 和用于网络通信的 SSE
• 🔄 Git 感知分析 - 直接从 git diff 分析改动，非常适合提交前审查

🚀 安装

# Clone the repository
git clone https://github.com/hyperbliss/lucidity-mcp.git
cd lucidity-mcp

# Set up a virtual environment with UV
uv venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies with UV
uv sync

📋 前提条件

• Python 3.13 或更高版本
• Git（用于分析代码改动）
• UV 包管理器（建议用于管理依赖项）

🔮 快速开始

运行 Lucidity 服务

# Start with stdio transport (for terminal use)
lucidity-mcp

# Start with SSE transport (for network use)
lucidity-mcp --transport sse --host 127.0.0.1 --port 6969

# Run with debug logging
lucidity-mcp --debug

# Run with file logging
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 包管理器和解析器。

# Update dependencies
uv sync

# Run tests
pytest

# Run linting
ruff check .

# Run type checking
mypy .

🔧 日志记录行为

Lucidity 会根据传输方式采用不同的日志记录方式：

• SSE 传输：启用完整的控制台日志记录
• 使用 --log-file 的 Stdio 传输：所有日志都写入文件，禁用控制台日志
• 不使用 --log-file 的 Stdio 传输：只有警告和错误会写入 stderr，禁用信息日志

这样可以确保日志不会输出到 stdout，从而避免破坏 stdio 通信。

🎛️ 命令行选项

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            show this help message and exit
  --debug               Enable debug logging
  --host HOST           Host to bind the server to (use 0.0.0.0 for all interfaces)
  --port PORT           Port to listen on for network connections
  --transport {stdio,sse}
                        Transport type to use (stdio for terminal, sse for network)
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set the logging level
  --verbose             Enable verbose logging for HTTP requests
  --log-file LOG_FILE   Path to log file (required for stdio transport if logs enabled)

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 使用 UV 设置开发环境
4. 进行更改
5. 运行测试和代码检查
6. 提交更改（git commit -m 'Add some amazing feature'）
7. 将分支推送到远程（git push origin feature/amazing-feature）
8. 创建 Pull Request

📝 许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

---