Skip to content
Back to search

lucidity-mcp

AI-powered code quality analysis using MCP to help AI assistants review code more effectively. Analyze git changes for complexity, security issues, and more through structured prompts.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hyperb1iss--lucidity-mcp/badge.svg)](/listings/hyperb1iss--lucidity-mcp)

HTML

<a href="/listings/hyperb1iss--lucidity-mcp"><img src="/api/listings/hyperb1iss--lucidity-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 199 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ✨ Lucidity MCP 🔍
  2. <div align="center">
  3. [![Python 3.13+](https://img.shields.io/badge/python-3.13+-9D00FF.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
  4. [![License](https://img.shields.io/badge/license-Apache_2.0-FF00FF.svg?style=for-the-badge)](LICENSE)
  5. [![Status](https://img.shields.io/badge/status-active_development-39FF14.svg?style=for-the-badge)](docs/plan.md)
  6. [![Code Style](https://img.shields.io/badge/code_style-ruff-00FFFF.svg?style=for-the-badge)](https://github.com/astral-sh/ruff)
  7. [![Type Check](https://img.shields.io/badge/type_check-mypy-FFBF00.svg?style=for-the-badge)](https://mypy.readthedocs.io/en/stable/)
  8. **Clarity in Code, Confidence in Creation**
  9. </div>
  10. Lucidity is a Model Context Protocol (MCP) server designed to enhance the quality of AI-generated code through intelligent, prompt-based analysis. By providing structured guidance to AI coding assistants, Lucidity helps identify and address common quality issues, resulting in cleaner, more maintainable, and more robust code.
  11. Before you commit, just ask Lucidity to analyze the changes instead of vibe-coding yourself into a nightmare hellscape! 😱 💥 🚫
  12. ## 💫 Features
  13. - 🔮 **Comprehensive Issue Detection** - Covers 10 critical quality dimensions from complexity to security vulnerabilities
  14. - 🔄 **Contextual Analysis** - Compares changes against original code to identify unintended modifications
  15. - 🌐 **Language Agnostic** - Works with any programming language the AI assistant understands
  16. - 🎯 **Focused Analysis** - Option to target specific issue types based on project needs
  17. - 📝 **Structured Outputs** - Guides AI to provide actionable feedback with clear recommendations
  18. - 🤖 **MCP Integration** - Seamless integration with Claude and other MCP-compatible AI assistants
  19. - 🪶 **Lightweight Implementation** - Simple server design with minimal dependencies
  20. - 🧩 **Extensible Framework** - Easy to add new issue types or refine analysis criteria
  21. - 🔀 **Flexible Transport** - Supports both stdio for terminal-based interaction and SSE for network-based communication
  22. - 🔄 **Git-Aware Analysis** - Analyzes changes directly from git diff, making it ideal for pre-commit reviews
  23. ## 🚀 Installation
  24. ```bash
  25. # Clone the repository
  26. git clone https://github.com/hyperbliss/lucidity-mcp.git
  27. cd lucidity-mcp
  28. # Set up a virtual environment with UV
  29. uv venv .venv
  30. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  31. # Install dependencies with UV
  32. uv sync
  33. ```
  34. ## 📋 Prerequisites
  35. - Python 3.13 or higher
  36. - Git (for analyzing code changes)
  37. - UV package manager (recommended for dependency management)
  38. ## 🔮 Quick Start
  39. ### Run the Lucidity server
  40. ```bash
  41. # Start with stdio transport (for terminal use)
  42. lucidity-mcp
  43. # Start with SSE transport (for network use)
  44. lucidity-mcp --transport sse --host 127.0.0.1 --port 6969
  45. # Run with debug logging
  46. lucidity-mcp --debug
  47. # Run with file logging
  48. lucidity-mcp --log-file lucidity.log
  49. ```
  50. ### Using with AI Assistants
  51. 1. Start Lucidity in SSE mode:
  52. ```bash
  53. lucidity-mcp --transport sse
  54. ```
  55. 2. Connect your AI assistant using the MCP protocol URI:
  56. ```
  57. sse://localhost:6969/sse
  58. ```
  59. 3. The AI can now invoke the `analyze_changes` tool to get code quality feedback!
  60. ## 🧠 Analysis Dimensions
  61. Lucidity analyzes code across 10 critical quality dimensions:
  62. 1. **Unnecessary Complexity** - Identifies overly complex algorithms, excessive abstractions, and convoluted logic
  63. 2. **Poor Abstractions** - Detects leaky or inappropriate abstractions and unclear separation of concerns
  64. 3. **Unintended Code Deletion** - Catches accidental removal of critical functionality or validation
  65. 4. **Hallucinated Components** - Finds references to non-existent functions, classes, or APIs
  66. 5. **Style Inconsistencies** - Spots deviations from project coding standards and conventions
  67. 6. **Security Vulnerabilities** - Identifies potential security issues in code changes
  68. 7. **Performance Issues** - Detects inefficient algorithms or operations that could impact performance
  69. 8. **Code Duplication** - Finds repeated logic or functionality that should be refactored
  70. 9. **Incomplete Error Handling** - Spots missing or inadequate exception handling
  71. 10. **Test Coverage Gaps** - Identifies missing tests for critical functionality
  72. ## 📊 Example AI Assistant Queries
  73. With an AI assistant connected to Lucidity, try these queries:
  74. - "Analyze the code quality in my latest git changes"
  75. - "Check for security vulnerabilities in my JavaScript changes"
  76. - "Make sure my Python code follows best practices"
  77. - "Identify any performance issues in my recent code changes"
  78. - "Are there any unintended side effects in my recent refactoring?"
  79. - "Help me improve the abstractions in my code"
  80. - "Check if I've accidentally removed any important validation"
  81. - "Find any hallucinated API calls in my latest commit"
  82. - "Is my error handling complete and robust?"
  83. - "Are there any test coverage gaps in my new feature?"
  84. ## 🛠️ Available MCP Tools
  85. ### Tools
  86. - `analyze_changes` - Prepares git changes for analysis through MCP
  87. - Parameters:
  88. - `workspace_root`: The root directory of the workspace/git repository
  89. - `path`: Optional specific file path to analyze
  90. ## 💻 Development
  91. Lucidity uses UV for dependency management and development workflows. UV is a fast, reliable Python package manager and resolver.
  92. ```bash
  93. # Update dependencies
  94. uv sync
  95. # Run tests
  96. pytest
  97. # Run linting
  98. ruff check .
  99. # Run type checking
  100. mypy .
  101. ```
  102. ## 🔧 Logging Behavior
  103. Lucidity handles logging differently depending on the transport:
  104. - **SSE transport**: Full console logging is enabled
  105. - **Stdio transport with --log-file**: All logs go to the file, console is disabled
  106. - **Stdio transport without --log-file**: Only warnings and errors go to stderr, info logs are disabled
  107. This ensures that stdio communication isn't broken by logs appearing on stdout.
  108. ## 🎛️ Command-line Options
  109. ```
  110. usage: lucidity-mcp [-h] [--debug] [--host HOST] [--port PORT] [--transport {stdio,sse}]
  111. [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--verbose]
  112. [--log-file LOG_FILE]
  113. options:
  114. -h, --help show this help message and exit
  115. --debug Enable debug logging
  116. --host HOST Host to bind the server to (use 0.0.0.0 for all interfaces)
  117. --port PORT Port to listen on for network connections
  118. --transport {stdio,sse}
  119. Transport type to use (stdio for terminal, sse for network)
  120. --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
  121. Set the logging level
  122. --verbose Enable verbose logging for HTTP requests
  123. --log-file LOG_FILE Path to log file (required for stdio transport if logs enabled)
  124. ```
  125. ## 🤝 Contributing
  126. Contributions are welcome! Please feel free to submit a Pull Request.
  127. 1. Fork the repository
  128. 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
  129. 3. Set up your development environment with UV
  130. 4. Make your changes
  131. 5. Run tests and linting
  132. 6. Commit your changes (`git commit -m 'Add some amazing feature'`)
  133. 7. Push to the branch (`git push origin feature/amazing-feature`)
  134. 8. Open a Pull Request
  135. ## 📝 License
  136. This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
  137. ---
  138. <div align="center">
  139. Created by [Stefanie Jane 🌠](https://github.com/hyperb1iss)
  140. If you find Lucidity useful, [buy me a Monster Ultra Violet ⚡️](https://ko-fi.com/hyperb1iss)
  141. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.