MCP 服务器

Lucidity MCP

一个模型上下文协议服务器，通过对10个关键维度进行全面分析，从而提高人工智能生成的代码质量，帮助在问题出现之前识别它们。

README

✨ Lucidity MCP 🔍

代码清晰，创造自信

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

在 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 传输需要）