Java Hibernate MCP Server

A Model Context Protocol (MCP) server that scans Java codebases for Hibernate/JPA entities, extracts their structure and relationships, and provides this context to LLMs.

Features

• Entity Scanning: Automatically finds @Entity classes and extracts fields, types, and relationships (@OneToMany, @ManyToOne, etc.).
• Enhanced Metadata: Extracts validation constraints (@NotNull, @Size, etc.) and ID generation strategies.
• Dynamic Datasource Resolution: Maps entities to datasources based on configurable package patterns.
• Graph Visualization: Generates Mermaid.js class diagrams of the entity graph.
• Entity Resolution: Finds related entities up to a specified depth (BFS traversal).
• Caching: Caches scan results for performance.

Prerequisites

• Java 21 or higher
• Maven 3.6 or higher

Building the Server

Build the project using Maven:

mvn clean package

This will create an executable JAR file in the target directory (e.g., mcp-java-0.0.1-SNAPSHOT.jar).

Configuration

Path Configuration

You can configure the root path and datasource paths using command-line arguments or properties.

Example claude_desktop_config.json with arguments:

{
  "mcpServers": {
    "java-hibernate-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/mcp-java/target/mcp-java-0.0.1-SNAPSHOT.jar",
        "--mcp.root-path=/path/to/your/codebase",
        "--mcp.datasource-paths./path/to/your/codebase/core=CoreDatasource",
        "--mcp.datasource-paths./path/to/your/codebase/analytics=AnalyticsDatasource"
      ]
    }
  }
}

• --mcp.root-path: Sets the default root directory for scanning.
• --mcp.datasource-paths.<path>=<datasource>: Maps a specific file path prefix to a datasource. This takes precedence over package-based mapping.

Datasources

Configure your datasource mappings in src/main/resources/application.properties (or provide your own properties file at runtime):

# Map packages to datasource names
mcp.datasources.com.example.core=CoreDatasource
mcp.datasources.com.example.analytics=AnalyticsDatasource

Usage with Claude Desktop / Claude Code

To use this server with Claude Desktop or other MCP clients, add it to your configuration file (typically claude_desktop_config.json on macOS/Windows).

Configuration Entry

{
  "mcpServers": {
    "java-hibernate-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/mcp-java/target/mcp-java-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Note: Replace /absolute/path/to/... with the actual full path to the built JAR file.

Available Tools

scanEntities

Scans the codebase for Hibernate entities.

• path (optional): Root directory to scan. Defaults to the server's working directory.

findRelatedEntities

Finds a subgraph of entities related to a specific entity.

• entityName: The simple or fully qualified name of the starting entity.
• depth (optional): Search depth (default: 5).

generateEntityGraph

Generates a visual diagram of the entity relationships.

• Returns a Mermaid.js string that Claude can render.

refreshCache

Clears the internal cache to force a re-scan of the codebase.