Lucidity MCP 🔍

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