✨ Lucidity MCP 🔍

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.

Before you commit, just ask Lucidity to analyze the changes instead of vibe-coding yourself into a nightmare hellscape! 😱 💥 🚫

💫 Features

• 🔮 Comprehensive Issue Detection - Covers 10 critical quality dimensions from complexity to security vulnerabilities
• 🔄 Contextual Analysis - Compares changes against original code to identify unintended modifications
• 🌐 Language Agnostic - Works with any programming language the AI assistant understands
• 🎯 Focused Analysis - Option to target specific issue types based on project needs
• 📝 Structured Outputs - Guides AI to provide actionable feedback with clear recommendations
• 🤖 MCP Integration - Seamless integration with Claude and other MCP-compatible AI assistants
• 🪶 Lightweight Implementation - Simple server design with minimal dependencies
• 🧩 Extensible Framework - Easy to add new issue types or refine analysis criteria
• 🔀 Flexible Transport - Supports both stdio for terminal-based interaction and SSE for network-based communication
• 🔄 Git-Aware Analysis - Analyzes changes directly from git diff, making it ideal for pre-commit reviews

🚀 Installation

# 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

📋 Prerequisites

• Python 3.13 or higher
• Git (for analyzing code changes)
• UV package manager (recommended for dependency management)

🔮 Quick Start

Run the Lucidity server

# 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

Using with AI Assistants

1. Start Lucidity in SSE mode:

   lucidity-mcp --transport sse
   

2. Connect your AI assistant using the MCP protocol URI:

   sse://localhost:6969/sse
   

3. The AI can now invoke the analyze_changes tool to get code quality feedback!

🧠 Analysis Dimensions

Lucidity analyzes code across 10 critical quality dimensions:

1. Unnecessary Complexity - Identifies overly complex algorithms, excessive abstractions, and convoluted logic
2. Poor Abstractions - Detects leaky or inappropriate abstractions and unclear separation of concerns
3. Unintended Code Deletion - Catches accidental removal of critical functionality or validation
4. Hallucinated Components - Finds references to non-existent functions, classes, or APIs
5. Style Inconsistencies - Spots deviations from project coding standards and conventions
6. Security Vulnerabilities - Identifies potential security issues in code changes
7. Performance Issues - Detects

... View full README on GitHub