Spring Architecture Analyzer MCP Server 🏛️🔍

A high-performance, local Model Context Protocol (MCP) server for deep static analysis, dependency mapping, and architectural governance of Java Spring Boot (Maven) repositories.

Analyzes Java code directly using Tree-sitter AST parsing, builds a directed dependency graph in SQLite, and generates high-resolution architectural diagrams in dark mode.

🤖 For AI Agents & LLMs: Operational Guide & Tool Contracts

Recommended Execution Sequence

When analyzing a Spring Boot codebase, follow this standard tool sequence:

graph TD
    A[index_repository] --> B[get_architecture_overview]
    B --> C[generate_dependency_graph]
    B --> D[validate_architecture_rules]
    B --> E[find_dependency_cycles]
    B --> F[rank_refactoring_targets]
    D --> G[get_change_impact]

1. Always call index_repository(repo_path) first: All other tools rely on the cached SQLite graph populated by this call. If not indexed, tools return an error payload: {"error": "No repository has been indexed yet..."}.

2. Call get_architecture_overview(): To quickly inspect packages, layer distribution, and high-level structure.

3. Call validate_architecture_rules(): To detect layer skipping (e.g. Controller -> Repository bypassing Service).

4. Call generate_dependency_graph(layout="layered"): To produce the visual PNG artifact saved locally at outputs/{repo_name}_dependency_graph.png.

5. Call get_change_impact(class_name): When asked about the blast radius or risk of modifying a specific class.

Available Tools Specification

Risk Scoring Formula

$$\text{Risk} = 2 \cdot \text{fan_in} + \text{fan_out} + 3 \cdot \text{transitive_impact} + (10 \text{ if in_cycle else } 0) + 8 \cdot \text{violations}$$

Related MCP server: mcp-codebase-oracle

👤 For Developers: Installation & Setup

Prerequisites

• Python 3.11+ installed.

• Git.

• A local Java Maven Spring Boot repository with src/main/java (e.g. spring-petclinic).

1. Clone & Setup Virtual Environment

# Clone the repository
git clone https://github.com/jcdiegolopez/spring-architecture-analyzer-mcp.git
cd spring-architecture-analyzer-mcp

# Create and activate virtual environment
# Windows (PowerShell):
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Linux / macOS:
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Verify Installation

Run the automated test suite to ensure Tree-sitter and FastMCP are operational:

pytest

⚙️ MCP Host Configuration

Add this server to your MCP host configuration file.

For Custom Hosts (e.g. mcp_servers.json)

{
  "mcpServers": {
    "architecture": {
      "command": "C:/Users/<USER>/.../spring-architecture-analyzer-mcp/.venv/Scripts/python.exe",
      "args": [
        "C:/Users/<USER>/.../spring-architecture-analyzer-mcp/server.py"
      ],
      "cwd": "C:/Users/<USER>/.../spring-architecture-analyzer-mcp"
    }
  }
}

For Claude Desktop (claude_desktop_config.json)

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "spring-architecture": {
      "command": "C:\\path\\to\\spring-architecture-analyzer-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\spring-architecture-analyzer-mcp\\server.py"
      ]
    }
  }
}

📊 Visual Graph Generator

When generate_dependency_graph is called:

• Saved directly to disk: Stored in outputs/{repo_name}_dependency_graph.png.

• Architectural Tiers: Organizes classes into colored visual bands:

  • 🟣 Presentation Tier: Controllers (@Controller, @RestController) & Configurations.

  • 🔵 Business Logic: Services (@Service) & Components (@Component, formatters, validators).

  • 🟠 Data Access: Repositories (@Repository, JpaRepository, CrudRepository).

  • 🟢 Domain Models: Entities (@Entity, MappedSuperclass, tables).

• Tech Card Badges: Clean rounded cards displaying component names and coupling metrics (in:X | out:Y).

• Curved Directed Edges: Color-coded arcs indicating dependency flow.

🔗 Related Repositories

• RD-PR01: Interactive Console MCP Client & Chatbot host (Google Gemini Interactions API).

• github-spring-profiler-mcp: Remote Cloudflare Worker MCP for fast remote repository pre-screening.

📄 License

MIT License. See LICENSE for details.