murugarajr/ohm-mcp

Purpose and Entry Point

OHM-MCP is a Python 3.8+ Model Context Protocol (MCP) server exposing AI-assistant tools for static analysis, refactoring planning, patch generation, and guarded application of Python code changes. MCP clients launch it through python -m ohm_mcp.server; the service boundary is src/ohm_mcp/server.py, with package initialization in src/ohm_mcp/__init__.py.

MCP Tool Orchestration

src/ohm_mcp/server.py is the integration layer between MCP requests and the refactoring domain. It presents analysis, transformation, reporting, and execution operations to compatible clients such as Copilot, Cursor, and Cline. Tool inputs are source text, files, or project paths; outputs are findings, plans, generated code, diffs, reports, or execution status.

Static Analysis Pipeline

The refactoring subsystem centers on AST-driven inspection of Python source:

• src/ohm_mcp/refactoring/analysis.py

• src/ohm_mcp/refactoring/architecture_analyzer.py

• src/ohm_mcp/refactoring/dead_code_detector.py

These stages identify structural and quality concerns such as architectural/SOLID issues, dead code, coupling, and code health signals. Analysis results feed planning, prioritization, and reporting rather than directly mutating code.

Refactoring Planning and AST Transformations

Planning converts findings or user requests into scoped refactoring proposals and patches:

• src/ohm_mcp/refactoring/planning.py

• src/ohm_mcp/refactoring/ast_refactorer.py

• src/ohm_mcp/refactoring/patching.py

The AST refactorer handles extract-method-style transformations; patching represents proposed changes as unified diffs. This is the main safety boundary: generation/review of a patch is distinct from writing changes to a target project.

Project-Wide Code Migration

Several specialized transformations operate across files and symbols:

• src/ohm_mcp/refactoring/symbol_renamer.py

• src/ohm_mcp/refactoring/import_refactorer.py

• src/ohm_mcp/refactoring/dependency_injection_refactorer.py

These handle project-wide rename/import migration and dependency-injection restructuring. They must resolve source-level references and conflicts before changes proceed, making filesystem/project scope an important boundary.

Quality, Risk, and Improvement Engines

Independent analyzers provide actionable signals for refactoring decisions:

• src/ohm_mcp/refactoring/type_hint_analyzer.py

• src/ohm_mcp/refactoring/performance_analyzer.py

• src/ohm_mcp/refactoring/duplication_detector.py

Additional architectural engines include pattern recommendations and coverage-aware prioritization in src/ohm_mcp/refactoring/pattern_suggester.py and src/ohm_mcp/refactoring/coverage_analyzer.py. Their outputs inform migration plans and recommended ordering, rather than requiring a single monolithic analysis pass.

Testing, Execution, and Reporting

Characterization-test generation supports behavior preservation before edits:

• src/ohm_mcp/refactoring/test_generator.py

• src/ohm_mcp/refactoring/automated_executor.py

• src/ohm_mcp/refactoring/metrics_reporter.py

The automated executor is the mutation boundary: it supports dry runs, backups, applying changes, test validation, rollback, and operation history. Metrics reporting aggregates analyzer outputs into quality reports. Runtime infrastructure is a local Python process communicating over MCP; no hosted database, web service, or external API dependency is indicated by the repository tree.