# murugarajr/ohm-mcp architecture

> Architecture diagram of the GitHub repository murugarajr/ohm-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/murugarajr/ohm-mcp
- Repository: https://github.com/murugarajr/ohm-mcp

## Overview

#### 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.

Main entry points: [`src/ohm_mcp/refactoring/planning.py`](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/planning.py) (Refactoring planning), [`src/ohm_mcp/server.py`](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/server.py) (MCP server), [`src/ohm_mcp/refactoring/analysis.py`](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/analysis.py) (AST inspection), [`src/ohm_mcp/refactoring/automated_executor.py`](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/automated_executor.py) (Automated executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Service"]
  node_client(("MCP client"))
  node_server{{"MCP server<br/>Python entry point<br/>[server.py]"}}
end

subgraph group_analysis["Analysis Signals"]
  node_core_analysis["AST inspection<br/>analysis pipeline<br/>[analysis.py]"]
  node_architecture["Architecture analysis<br/>SOLID analyzer"]
  node_dead_code["Dead-code detection<br/>analyzer"]
  node_quality["Quality analyzers<br/>risk signals"]
  node_prioritization["Recommendations &amp; coverage<br/>prioritization signals"]
end

subgraph group_planning["Planning &amp; Patches"]
  node_planning["Refactoring planning<br/>proposal builder<br/>[planning.py]"]
  node_ast_refactorer["AST refactorer<br/>code transformer<br/>[ast_refactorer.py]"]
  node_patches["Unified patches<br/>change artifact<br/>[patching.py]"]
end

subgraph group_migration["Project Migrations"]
  node_migrations["Cross-file migrations<br/>project transformer<br/>[symbol_renamer.py]"]
end

subgraph group_execution["Guarded Execution"]
  node_test_generation["Characterization tests<br/>test generator<br/>[test_generator.py]"]
  node_executor{{"Automated executor<br/>mutation boundary"}}
  node_metrics["Metrics reports<br/>reporting"]
end

node_project[("Target Python project<br/>filesystem scope")]

node_client -->|"MCP tool request"| node_server
node_server -->|"reads source or paths"| node_project
node_server -->|"runs analysis"| node_core_analysis
node_core_analysis -->|"structural checks"| node_architecture
node_core_analysis -->|"unused-code checks"| node_dead_code
node_project -->|"source inspection"| node_quality
node_project -->|"project signals"| node_prioritization
node_architecture -->|"findings"| node_planning
node_dead_code -->|"findings"| node_planning
node_quality -->|"risk signals"| node_planning
node_prioritization -->|"recommended order"| node_planning
node_planning -->|"scoped transformation"| node_ast_refactorer
node_ast_refactorer -->|"proposed diff"| node_patches
node_planning -->|"project-wide proposal"| node_migrations
node_project -->|"references and conflicts"| node_migrations
node_migrations -->|"migration diff"| node_patches
node_planning -->|"preservation scope"| node_test_generation
node_patches -->|"reviewed change set"| node_executor
node_test_generation -->|"validation tests"| node_executor
node_executor -->|"apply or rollback"| node_project
node_core_analysis -->|"analysis outputs"| node_metrics
node_quality -->|"quality signals"| node_metrics
node_server -->|"report request"| node_metrics
node_executor -->|"execution status"| node_server
node_metrics -->|"quality report"| node_server

click node_server "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/server.py"
click node_core_analysis "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/analysis.py"
click node_architecture "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/architecture_analyzer.py"
click node_dead_code "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/dead_code_detector.py"
click node_quality "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/type_hint_analyzer.py"
click node_prioritization "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/pattern_suggester.py"
click node_planning "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/planning.py"
click node_ast_refactorer "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/ast_refactorer.py"
click node_patches "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/patching.py"
click node_migrations "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/symbol_renamer.py"
click node_test_generation "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/test_generator.py"
click node_executor "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/automated_executor.py"
click node_metrics "https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/metrics_reporter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_server toneBlue
class node_core_analysis,node_architecture,node_dead_code,node_quality,node_prioritization toneAmber
class node_planning,node_ast_refactorer,node_patches toneMint
class node_migrations toneRose
class node_test_generation,node_executor,node_metrics toneIndigo
class node_project toneNeutral
```

## Components

### MCP Service

- **MCP client**: client · Copilot, Cursor, or Cline sends tool requests.
- [MCP server](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/server.py): Python entry point · Exposes analysis, transformation, reporting, and execution tools. · `src/ohm_mcp/server.py`

### Analysis Signals

- [AST inspection](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/analysis.py): analysis pipeline · Finds structural, architectural, dead-code, and coupling concerns. · `src/ohm_mcp/refactoring/analysis.py`
- [Architecture analysis](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/architecture_analyzer.py): SOLID analyzer · `src/ohm_mcp/refactoring/architecture_analyzer.py`
- [Dead-code detection](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/dead_code_detector.py): analyzer · `src/ohm_mcp/refactoring/dead_code_detector.py`
- [Quality analyzers](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/type_hint_analyzer.py): risk signals · Type hints, performance, and duplication findings. · `src/ohm_mcp/refactoring/type_hint_analyzer.py`
- [Recommendations & coverage](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/pattern_suggester.py): prioritization signals · Pattern recommendations and coverage-aware ordering. · `src/ohm_mcp/refactoring/pattern_suggester.py`

### Planning & Patches

- [Refactoring planning](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/planning.py): proposal builder · Scopes findings or requests into refactoring proposals. · `src/ohm_mcp/refactoring/planning.py`
- [AST refactorer](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/ast_refactorer.py): code transformer · Performs extract-method-style transformations. · `src/ohm_mcp/refactoring/ast_refactorer.py`
- [Unified patches](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/patching.py): change artifact · Generated changes remain reviewable before writing. · `src/ohm_mcp/refactoring/patching.py`

### Project Migrations

- [Cross-file migrations](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/symbol_renamer.py): project transformer · Coordinates rename, import, and dependency-injection changes. · `src/ohm_mcp/refactoring/symbol_renamer.py`

### Guarded Execution

- [Characterization tests](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/test_generator.py): test generator · Creates behavior-preserving tests before edits. · `src/ohm_mcp/refactoring/test_generator.py`
- [Automated executor](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/automated_executor.py): mutation boundary · Dry-runs, backs up, applies, validates, rolls back, and records operations. · `src/ohm_mcp/refactoring/automated_executor.py`
- [Metrics reports](https://github.com/murugarajr/ohm-mcp/blob/main/src/ohm_mcp/refactoring/metrics_reporter.py): reporting · Aggregates analyzer outputs into quality reports. · `src/ohm_mcp/refactoring/metrics_reporter.py`

### Other components

- **Target Python project**: filesystem scope · Source files and project-wide references supplied to tools.

## Connections

- MCP client → MCP server: MCP tool request
- MCP server → Target Python project: reads source or paths
- MCP server → AST inspection: runs analysis
- AST inspection → Architecture analysis: structural checks
- AST inspection → Dead-code detection: unused-code checks
- Target Python project → Quality analyzers: source inspection
- Target Python project → Recommendations & coverage: project signals
- Architecture analysis → Refactoring planning: findings
- Dead-code detection → Refactoring planning: findings
- Quality analyzers → Refactoring planning: risk signals
- Recommendations & coverage → Refactoring planning: recommended order
- Refactoring planning → AST refactorer: scoped transformation
- AST refactorer → Unified patches: proposed diff
- Refactoring planning → Cross-file migrations: project-wide proposal
- Target Python project → Cross-file migrations: references and conflicts
- Cross-file migrations → Unified patches: migration diff
- Refactoring planning → Characterization tests: preservation scope
- Unified patches → Automated executor: reviewed change set · Writing is separate from patch generation.
- Characterization tests → Automated executor: validation tests
- Automated executor → Target Python project: apply or rollback
- AST inspection → Metrics reports: analysis outputs
- Quality analyzers → Metrics reports: quality signals
- MCP server → Metrics reports: report request
- Automated executor → MCP server: execution status
- Metrics reports → MCP server: quality report