Lucidity MCP

What hyperb1iss/lucidity-mcp MCP server does

The hyperb1iss/lucidity-mcp MCP server helps an AI coding assistant inspect recent code changes before they are committed. Rather than running a language-specific linter or scanner, it prepares context for prompt-based analysis and guides the assistant toward structured, actionable feedback.

Analysis covers 10 quality dimensions:

• Unnecessary complexity
• Poor or leaky abstractions
• Accidental deletion of functionality
• References to nonexistent components or APIs
• Style inconsistencies
• Potential security vulnerabilities
• Performance problems
• Duplicated logic
• Incomplete error handling
• Missing tests or test coverage gaps

The project describes the analysis as language agnostic, provided the connected AI assistant understands the programming language being reviewed. It can also focus on particular issue types when the project needs a narrower review.

How it works

The main MCP tool is analyze_changes. Give it workspace_root, pointing to the root of the workspace or Git repository, and optionally provide path to limit the review to a specific file. The server prepares the relevant Git changes for the assistant rather than directly making edits or committing code.

Lucidity compares changes with the original code to help identify unintended modifications. This makes it suitable for checking generated patches, refactors, new features, and changes where removed validation or altered behavior could be easy to miss. The resulting guidance is structured around recommendations that the assistant can explain and act on.

The hyperb1iss/lucidity-mcp MCP server can communicate over stdio for local terminal-based use or SSE for network-based access. With SSE, an assistant connects through the server's MCP endpoint; the documented example uses sse://localhost:6969/sse.

Setup and configuration

The project requires Python 3.13 or newer, Git, and the UV package manager. The documented setup clones the repository, creates a UV-managed virtual environment, activates it, and runs uv sync to install dependencies. Once installed, start the local server with lucidity-mcp.

For a network connection, use the SSE transport and optionally set the bind host and port. The command-line interface also supports debug logging, log levels, verbose HTTP logging, and a log-file path. In stdio mode, logging is kept off stdout so it does not interfere with MCP communication; enabled logs can be directed to a file.

Tools and capabilities

analyze_changes accepts:

• workspace_root: the workspace or Git repository root
• path: an optional file to analyze

The hyperb1iss/lucidity-mcp MCP server is intended for pre-commit reviews and for asking an AI assistant questions such as whether a recent change introduced a security issue, removed important validation, created a performance problem, or left a feature without sufficient tests. Its framework is described as extensible, allowing additional issue types or revised analysis criteria as the project evolves.

Limitations and notes

The material documents one MCP analysis tool and does not describe automatic code modification, commits, or a standalone language parser. Results depend on the connected AI assistant's ability to understand the code under review. Git is required for change-based analysis, and the project is marked as being in active development.