Lucidity MCP Server for AI Code Quality Analysis

Overview

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.

Key Slogan:
Clarity in Code, Confidence in Creation

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:
   shell 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 inefficient algorithms or operations that could impact performance.
8. Code Duplication: Finds repeated logic or functionality that should be refactored.
9. Incomplete Error Handling: Spots missing or inadequate exception handling.
10. Test Coverage Gaps: Identifies missing tests for critical functionality.

Example AI Assistant Queries

With an AI assistant connected to Lucidity, try these queries:

• "Analyze the code quality in my latest git changes"
• "Check for security vulnerabilities in my JavaScript changes"
• "Make sure my Python code follows best practices"
• "Identify any performance issues in my recent code changes"
• "Are there any unintended side effects in my recent refactoring?"
• "Help me improve the abstractions in my code"
• "Check if I've accidentally removed any important validation"
• "Find any hallucinated API calls in my latest commit"
• "Is my error handling complete and robust?"
• "Are there any test coverage gaps in my new feature?"

Available MCP Tools

Tools

• analyze_changes: Prepares git changes for analysis through MCP.
• Parameters:
  • workspace_root: The root directory of the workspace/git repository.
  • path: Optional specific file path to analyze.

Development

Lucidity uses UV for dependency management and development workflows. UV is a fast, reliable Python package manager and resolver.

# Update dependencies
uv sync

# Run tests
pytest

# Run linting
ruff check .

# Run type checking
mypy .

Logging Behavior

Lucidity handles logging differently depending on the transport:

• SSE transport: Full console logging is enabled.
• Stdio transport with --log-file: All logs go to the file, console is disabled.
• Stdio transport without --log-file: Only warnings and errors go to stderr, info logs are disabled.

This ensures that stdio communication isn't broken by logs appearing on stdout.

Command-line Options

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)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Set up your development environment with UV.
4. Make your changes.
5. Run tests and linting.
6. Commit your changes (git commit -m 'Add some amazing feature').
7. Push to the branch (git push origin feature/amazing-feature).
8. Open a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Created by Stefanie Jane 🌠
If you find Lucidity useful, buy me a Monster Ultra Violet ⚡️