suggest_refactors

suggest_refactors

Get prioritized, actionable refactoring recommendations based on architecture analysis. This tool identifies specific opportunities to improve your codebase structure, such as breaking cycles, splitting hub modules, fixing layer violations, and reducing coupling.

Caution

Status: This tool is currently a placeholder in the MCP server. It runs the risk preset but only returns a summary message. Full refactoring suggestions require the complete arxo binary with the refactoring_recommendations metric.

Use the CLI instead: arxo analyze --preset full --format json and inspect the refactoring_recommendations metric.

Parameters

Parameter	Type	Required	Description
project_path	string	Yes	Absolute or relative path to the project root directory
edge_filter	string	No	Optional edge filter (reserved for future use)

Current Response (placeholder)

Request:

{
  "project_path": "."
}

Response:

Refactoring suggestions require full arxo. Analysis completed: 7 metrics in results.

The tool runs the risk preset and confirms analysis completed, but doesn’t return structured refactoring recommendations.

Expected Response (when fully implemented)

When implemented, this tool will return prioritized refactoring recommendations:

{
  "recommendations": [
    {
      "priority": "Critical|High|Medium|Low",
      "effort": "Low|Medium|High",
      "category": "string",
      "title": "string",
      "description": "string",
      "evidence": {
        "modules": ["string"],
        "metrics": {
          "key": "value"
        }
      },
      "steps": ["string"]
    }
  ],
  "recommendations_count": "number"
}

Recommendation Categories

Category	What it finds
Break circular dependencies	Identifies lowest-weight edges to cut (e.g., barrel imports, type-only imports)
Split hub modules	Suggests splitting modules with high fan-in + fan-out into smaller, cohesive units
Fix layer violations	Recommends dependency inversion or adapter patterns for upward-reaching imports
Move misplaced modules	Identifies modules with more connections to neighboring communities
Fix unstable dependencies	Suggests extracting interfaces when stable modules depend on unstable ones
Refactor high-churn hotspots	Highlights modules that change frequently and are tightly coupled

Priority Levels

Priority	When to act
Critical	Immediate action — blocking issue (e.g., cycles preventing modular compilation)
High	Address soon — significant technical debt or risk
Medium	Planned refactoring — improvement opportunity
Low	Optional — minor improvements or optimizations

Effort Estimates

Effort	Typical scope
Low	1-4 hours — single module refactoring
Medium	1-3 days — multiple modules, moderate complexity
High	1-2 weeks — architectural change, many modules affected

Expected Examples (when implemented)

Breaking a circular dependency

{
  "priority": "Critical",
  "effort": "Low",
  "category": "Break circular dependencies",
  "title": "Break cycle between auth.ts and session.ts",
  "description": "A 2-module cycle exists between auth and session. Breaking this cycle will enable modular compilation and reduce coupling.",
  "evidence": {
    "modules": ["src/core/auth.ts", "src/core/session.ts"],
    "metrics": {
      "scc.max_cycle_size": 2,
      "ricci_curvature": -0.3
    }
  },
  "steps": [
    "Extract shared types to src/core/auth-types.ts",
    "Make session.ts import from auth-types.ts instead of auth.ts",
    "Verify no cycle with `arxo analyze --preset quick`"
  ]
}

Splitting a hub module

{
  "priority": "High",
  "effort": "Medium",
  "category": "Split hub modules",
  "title": "Split utils.ts (fan-in: 42, fan-out: 18)",
  "description": "utils.ts is a hub module with excessive dependencies. Split it into focused utilities to reduce coupling.",
  "evidence": {
    "modules": ["src/utils/utils.ts"],
    "metrics": {
      "centrality.module.max_fan_in": 42,
      "centrality.module.max_fan_out": 18,
      "centrality.module.betweenness_max": 0.62
    }
  },
  "steps": [
    "Extract string utilities to src/utils/string.ts",
    "Extract array utilities to src/utils/array.ts",
    "Extract date utilities to src/utils/date.ts",
    "Update imports across codebase",
    "Verify betweenness reduced with `arxo analyze --preset quick`"
  ]
}

Fixing a layer violation

{
  "priority": "High",
  "effort": "Medium",
  "category": "Fix layer violations",
  "title": "Domain layer importing from presentation layer",
  "description": "Domain logic in src/domain/user.ts imports from src/presentation/formatters.ts, violating layer architecture.",
  "evidence": {
    "modules": ["src/domain/user.ts", "src/presentation/formatters.ts"],
    "metrics": {
      "layer_violations.violations_count": 1
    }
  },
  "steps": [
    "Move formatting logic to src/domain/user-formatters.ts",
    "Update presentation layer to use domain formatters",
    "Apply Dependency Inversion Principle",
    "Verify no violations with `arxo analyze --preset ci`"
  ]
}

Workaround: Use CLI

Until this tool is fully implemented in the MCP server, use the CLI:

# Get refactoring recommendations
arxo analyze --preset full --format json > results.json

# Extract refactoring recommendations
cat results.json | jq '.results[] | select(.id=="refactoring_recommendations")'

Sample CLI output

{
  "id": "refactoring_recommendations",
  "version": "1.0.0",
  "values": {},
  "findings": [
    {
      "title": "Break cycle between auth.ts and session.ts",
      "severity": "error",
      "evidence": [
        {
          "modules": ["src/core/auth.ts", "src/core/session.ts"],
          "priority": "Critical",
          "effort": "Low"
        }
      ]
    },
    {
      "title": "Split hub module utils.ts",
      "severity": "warning",
      "evidence": [
        {
          "module": "src/utils/utils.ts",
          "fan_in": 42,
          "fan_out": 18,
          "priority": "High",
          "effort": "Medium"
        }
      ]
    }
  ]
}

Workflow (when implemented)

Use this tool to plan refactoring efforts:

1. get_hotspots → identify problem areas
2. suggest_refactors → get prioritized recommendations
3. Sort by priority (Critical → High → Medium → Low)
4. For each recommendation:
   a. Assess effort vs impact
   b. Create refactoring task/ticket
   c. Implement steps
   d. Verify improvement with check_cycles or analyze_architecture
5. Re-run suggest_refactors to see remaining issues

See Workflows: Hotspot detection and refactoring for context.

Error Cases

Error	Cause	Solution
missing required parameter: project_path	project_path not provided	Include project_path in request
Refactoring suggestions require full arxo	MCP server limitation	Use CLI: arxo analyze --preset full

Performance

• Current: 10-30 seconds (runs risk preset)
• Expected (when implemented): 30-120 seconds (requires full preset with refactoring_recommendations)

Related Tools

• get_hotspots — Find hotspots before getting refactoring suggestions
• check_cycles — Verify cycle-breaking refactorings
• analyze_file_impact — Assess refactoring blast radius

Related Guides

• Breaking Cycles — Step-by-step cycle refactoring
• Refactoring Patterns — Common refactoring strategies
• Refactoring Recommendations — Detailed metric documentation

CLI Equivalent (current solution)

# This is the only way to get full refactoring suggestions
arxo analyze --preset full --format json | jq '.results[] | select(.id=="refactoring_recommendations")'

Future Implementation

To fully implement this tool in the MCP server:

1. Add refactoring_recommendations metric to arxo-loader
2. Expose structured recommendation data via the tool
3. Support filtering by priority, effort, or category
4. Cache recommendations by project state

The metric already exists in the Pro engine — it just needs to be wired into the MCP tool handler.