# Spring Architecture Analyzer MCP Server 🏛️🔍

[![MCP Version](https://img.shields.io/badge/MCP-1.29.1-blue.svg)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/Python-3.11+-brightgreen.svg)](https://python.org)
[![Tree--Sitter](https://img.shields.io/badge/AST-Tree--Sitter--Java-orange.svg)](https://github.com/tree-sitter/tree-sitter-java)
[![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](LICENSE)

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:

```mermaid
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

| Tool Name | Parameters | Returns | Description & Behavior |
|---|---|---|---|
| `index_repository` | `repo_path` *(string, required)* | `{ indexed_repo, classes_found, dependencies_found, layers, cache_db }` | Scans `src/main/java` via Tree-sitter AST. Parses same-package type usages and imports. Persists to SQLite. |
| `get_architecture_overview` | *None* | `{ total_classes, total_dependencies, packages, layers, cycle_count, cycles_preview }` | Returns high-level architectural metrics and layer distribution (`Controller`, `Service`, `Repository`, `Component`, `Entity`, `Configuration`). |
| `get_change_impact` | `class_name` *(string, required)* | `{ class, direct_dependents, transitive_dependents, total_impact }` | Calculates reverse-dependency blast radius (direct & transitive dependents) for a given class. |
| `find_dependency_cycles` | *None* | `{ cycle_count, cycles }` | Identifies circular dependencies (strongly connected components with size > 1). |
| `validate_architecture_rules` | *None* | `{ rule, violation_count, violations }` | Checks compliance with clean layering rules. Flags Controller -> Repository direct access. |
| `rank_refactoring_targets` | `top_n` *(integer, optional, default: 10)* | `{ top_n, scoring_formula, targets }` | Ranks classes by refactoring risk score using coupling, cycles, violations, and transitive impact. |
| `generate_dependency_graph` | `layout` *(string, default: "layered")*, `include_base64` *(bool, default: false)* | `{ status, saved_to, nodes, edges }` | Renders a high-resolution, dark-mode PNG architecture diagram to `outputs/` without terminal text flooding. |

#### 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}$$

---

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

```bash
# 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:

```bash
pytest
```

---

## ⚙️ MCP Host Configuration

Add this server to your MCP host configuration file.

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

```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`

```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](https://github.com/jcdiegolopez/RD-PR01): Interactive Console MCP Client & Chatbot host (Google Gemini Interactions API).
- [github-spring-profiler-mcp](https://github.com/jcdiegolopez/github-spring-profiler-mcp): Remote Cloudflare Worker MCP for fast remote repository pre-screening.

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.