Lucidity MCP

Instructions

Implementation Reference

• lucidity/tools/code_analysis.py:287-424 (handler)

  The main tool handler function decorated with @mcp.tool("analyze_changes"). It fetches git diffs, parses changes per file, detects language, generates analysis prompts using analyze_changes_prompt, and returns structured data including prompts and instructions for AI analysis via MCP.
  @mcp.tool("analyze_changes") def analyze_changes(workspace_root: str = "", path: str = "") -> dict[str, Any]: """Prepare git changes for analysis through MCP. This tool examines the current git diff, extracts changed code, and prepares structured data with context for the AI to analyze. The tool doesn't perform analysis itself - it formats the git diff data and provides analysis instructions which get passed back to the AI model through the Model Context Protocol. Args: workspace_root: The root directory of the workspace/git repository path: Optional specific file path to analyze Returns: Structured git diff data with analysis instructions for the AI """ logger.info("Starting git change analysis%s in workspace %s", f" for {path}" if path else "", workspace_root) if not workspace_root: return {"status": "error", "message": "workspace_root parameter is required"} # Get git diff logger.debug("Fetching git diff...") diff_content, staged_content = get_git_diff(workspace_root, path) # Get list of all changed files changed_files = get_changed_files(workspace_root) # Combine diff and staged content for complete changes combined_diff = diff_content if staged_content: combined_diff = combined_diff + "\n" + staged_content if combined_diff else staged_content logger.debug("Combined diff size: %d bytes", len(combined_diff)) if not combined_diff: logger.warning("No changes detected in git diff") return {"status": "no_changes", "message": "No changes detected in the git diff", "file_list": []} # Parse the diff logger.debug("Parsing git diff...") parsed_diff = parse_git_diff(combined_diff) if not parsed_diff: logger.warning("No parseable changes in git diff") return { "status": "no_changes", "message": "No parseable changes detected in the git diff", "file_list": changed_files, } logger.info("Found %d files with changes to analyze", len(parsed_diff)) # Process each changed file analysis_results = {} file_list = [] for filename, diff_info in parsed_diff.items(): logger.debug("Processing file: %s (status: %s)", filename, diff_info["status"]) file_list.append(filename) # Skip certain files if filename.endswith((".lock", ".sum", ".mod", "package-lock.json", "yarn.lock", ".DS_Store")): logger.debug("Skipping excluded file: %s", filename) continue try: # Extract original and modified code logger.debug("Extracting code changes for %s", filename) original_code, modified_code = extract_code_from_diff(diff_info) # Skip if no significant code changes if len(modified_code.strip()) < 10: logger.debug("Skipping %s - insufficient code changes (< 10 chars)", filename) continue # Detect language language = detect_language(filename) logger.debug("Detected language for %s: %s", filename, language) # Create a prompt for analysis logger.debug("Generating analysis prompt for %s", filename) from ..prompts import analyze_changes_prompt analysis_prompt = analyze_changes_prompt( code=modified_code, language=language, original_code=original_code if original_code else None ) logger.debug("Generated analysis prompt of size: %d chars", len(analysis_prompt)) # Store the analysis prompt to be returned analysis_results[filename] = { "status": diff_info["status"], "language": language, "analysis_prompt": analysis_prompt, "raw_diff": diff_info["raw_diff"], "original_code": original_code, "modified_code": modified_code, } logger.info("Successfully analyzed %s", filename) except Exception as e: logger.error("Error analyzing %s: %s", filename, e) analysis_results[filename] = {"status": "error", "message": f"Error analyzing file: {e!s}"} logger.info("Code analysis complete - processed %d files", len(analysis_results)) # Return results with instructions for AI analysis return { "status": "success", "file_count": len(analysis_results), "file_list": file_list, "all_changed_files": changed_files, "results": analysis_results, "instructions": """ This data contains git changes that you should analyze for code quality issues. As an AI model receiving this through MCP, your task is to: 1. Review each changed file: - Examine the raw diff showing the exact changes - Compare the original and modified code - Consider the language and file status (added, modified, deleted) 2. For each file, perform the analysis following the provided analysis prompt: - Analyze relevant quality dimensions - Assign severity levels to issues you identify - Provide line-specific explanations - Suggest concrete improvements 3. After analyzing all files, provide: - An overall assessment of the code changes - A prioritized list of improvements - Any patterns or systemic issues you've identified Your analysis should be thorough yet focused on actionable improvements. """, }
• lucidity/tools/__init__.py:7-9 (registration)

  Package-level registration: imports analyze_changes from code_analysis.py and adds it to __all__, making it available when importing from lucidity.tools.
  from .code_analysis import analyze_changes __all__ = ["analyze_changes"]
• lucidity/prompts.py:204-220 (helper)

  Helper function decorated with @mcp.prompt("analyze_changes"). Generates a structured prompt for code change analysis, used inside the handler to prepare prompts for each changed file.
  @mcp.prompt("analyze_changes") def analyze_changes_prompt(code: str, language: str, original_code: str | None = None) -> str: """Generate a prompt for analyzing git code changes via MCP. This function creates a structured prompt that will be passed back to the AI model through the Model Context Protocol, guiding it to analyze git changes effectively. Args: code: The changed code to analyze language: The programming language of the code original_code: The original code before changes (optional) Returns: A formatted prompt for the AI to analyze git changes """ return generate_analysis_prompt(code, language, original_code)