✨ Lucidity MCP 🔍

代码清晰，创作自信

Lucidity 是一款模型上下文协议 (MCP) 服务器，旨在通过智能的、基于提示的分析来提升 AI 生成代码的质量。通过为 AI 编码助手提供结构化的指导，Lucidity 可以帮助识别和解决常见的质量问题，从而生成更简洁、更易于维护、更健壮的代码。

在你做出决定之前，只需让 Lucidity 分析一下这些变化，而不是把自己编码成一个噩梦般的地狱！😱 💥 🚫

💫 功能

🔮全面的问题检测- 涵盖从复杂性到安全漏洞的 10 个关键质量维度
🔄上下文分析- 将更改与原始代码进行比较，以识别意外的修改
🌐语言无关- 适用于 AI 助手理解的任何编程语言
🎯重点分析- 根据项目需求选择针对特定问题类型
📝结构化输出- 引导 AI 提供可操作的反馈和明确的建议
🤖 MCP 集成- 与 Claude 和其他兼容 MCP 的 AI 助手无缝集成
🪶轻量级实现- 简单的服务器设计，具有最少的依赖性
🧩可扩展框架- 轻松添加新的问题类型或改进分析标准
🔀灵活传输- 支持基于终端交互的 stdio 和基于网络通信的 SSE
🔄 Git-Aware Analysis - 直接从 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

与人工智能助手一起使用

以 SSE 模式启动 Lucidity：
lucidity-mcp --transport sse
使用 MCP 协议 URI 连接您的 AI 助手：
sse://localhost:6969/sse
AI 现在可以调用analyze_changes工具来获取代码质量反馈！

🧠 分析维度

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

不必要的复杂性——识别过于复杂的算法、过度的抽象和复杂的逻辑
糟糕的抽象——检测漏洞百出或不恰当的抽象以及不明确的关注点分离
意外代码删除- 捕获意外删除的关键功能或验证
幻觉组件- 查找对不存在的函数、类或 API 的引用
风格不一致——发现与项目编码标准和惯例的偏差
安全漏洞——识别代码更改中的潜在安全问题
性能问题- 检测可能影响性能的低效算法或操作
代码重复- 查找需要重构的重复逻辑或功能
不完整的错误处理——缺失或不充分的异常处理
测试覆盖率差距——识别关键功能缺失的测试

📊 AI 助手查询示例

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

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

🛠️ 可用的 MCP 工具

工具

analyze_changes - 准备 git 更改以便通过 MCP 进行分析
- 参数：
  - workspace_root ：workspace/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，信息日志被禁用

这确保了 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            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 请求。

分叉存储库
创建你的功能分支（ git checkout -b feature/amazing-feature ）
使用 UV 设置您的开发环境
进行更改
运行测试和 linting
提交您的更改（ git commit -m 'Add some amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

📝 许可证

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

由Stefanie Jane 🌠创建

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

Lucidity MCP

Integrations