Jakartamigrationmcp

🚀 Jakarta Migration MCP Server

A Model Context Protocol (MCP) server that equips AI coding assistants with dedicated tools. These tools are designed for analyzing and migrating Java applications from Java EE 8 (javax.*) to Jakarta EE 9+ (jakarta.*).

🚀 Quick Start

Run locally (STDIO)

Prerequisites: Java 21+ and Node.js 18+

# Install via npm (one-time)
npm install -g @jakarta-migration/mcp-server

# Or use with npx (no installation)
npx -y @jakarta-migration/mcp-server

Refer to Local Setup (STDIO) below for client configuration.

✨ Features

🖥️ IntelliJ IDEA Plugin

A native IntelliJ IDEA plugin is available for users who prefer an IDE - integrated experience:

Download

Get it from JetBrains Marketplace →

Plugin Features

• Migration Analysis: Analyze Java projects to determine their readiness for Jakarta EE migration.
• Dependency Graph Visualization: Visualize module dependencies with multiple layout options, including hierarchical, force - directed, circular, and tree layouts.
• MCP Server Integration: Automatically connect to the Jakarta Migration MCP server.
• AI Assistant Tools: Integrate with AI Assistant to provide intelligent migration suggestions.
• Tool Window: A dedicated Jakarta Migration tool window for easy access.
• Refactor Tab: Apply and manage OpenRewrite refactorings.
• Runtime Verification: Test migrated applications at runtime.

Installation

1. Install via IntelliJ IDEA:
   • Open Settings (Ctrl + Alt + S or Cmd + ,).
   • Navigate to Plugins.
   • Search for Jakarta Migration.
   • Click Install.
2. Restart IntelliJ IDEA.

Usage

1. Open a Java project.
2. Go to Tools → Jakarta Migration or use Ctrl + Shift + J.
3. The Jakarta Migration tool window will open.
4. Click Analyze Project to start the analysis.
5. View the results in the dependency graph and analysis panel.

AI Assistant Integration

If you have the IntelliJ AI Assistant installed:

1. The plugin automatically registers MCP tools with the AI Assistant.
2. Ask the AI Assistant: "Analyze my project for Jakarta migration".
3. The AI Assistant will use the MCP tools to analyze your project.

Requirements

• IntelliJ IDEA 2023.3.4 or later.
• Java 17 or later.
• Optional: AI Assistant plugin for AI features.

📋 What It Does

The Jakarta Migration MCP Server allows your AI coding assistant to:

• 🔍 Analyze Jakarta Readiness: Assess Java projects' migration readiness through detailed dependency analysis.
• 🚫 Detect Blockers: Identify dependencies and code patterns that impede Jakarta migration.
• 📦 Recommend Versions: Suggest Jakarta - compatible versions for existing dependencies.
• 📋 Create Migration Plans: Generate comprehensive, phased migration plans with risk assessment.
• 📊 Analyze Migration Impact: Conduct a comprehensive impact analysis by combining dependency analysis and source code scanning.
• ✅ Verify Runtime: Test migrated applications to ensure correct post - migration operation.

The Problem It Solves

Migrating from Java EE 8 (javax.*) to Jakarta EE 9+ (jakarta.*) is complex due to:

• Dependency Hell: Many libraries have not migrated, causing transitive conflicts.
• Binary Incompatibility: Compiled JARs may internally reference javax.*.
• Hidden Dependencies: Usage of javax.* in XML configs, annotations, and dynamic loading.
• Risk Assessment: The need to understand the migration impact before starting. This MCP server provides AI assistants with specialized knowledge and tools to effectively navigate these challenges.

🔒 Security & Privacy

Your code and project data are handled with the highest level of care. We understand that Java developers working with enterprise codebases require complete confidence in the security and privacy of their intellectual property.

Stateless Architecture

✅ No Data Persistence: The service is completely stateless. Your project files, source code, and analysis results are never stored, logged, or persisted on our servers. ✅ No Data Collection: We do not collect, track, or analyze your code. Each request is processed independently without memory of previous requests. ✅ Local Execution Option: For maximum privacy, you can run the entire service locally using the Local Setup option. Your code never leaves your machine.

Privacy Guarantees

• Zero Code Storage: Project files are only read during analysis and immediately discarded.
• No Telemetry: There is no usage tracking, analytics, or code scanning for any purpose other than migration analysis.
• Open Source: The core service is open source, allowing you to audit its operations.
• Enterprise Ready: It is safe for use with proprietary and sensitive codebases.

Local Service

When running locally via STDIO:

• 100% Local: Everything runs on your machine.
• No Network Calls: No external requests are made.
• Complete Control: You have full visibility and control over the process.

For maximum security and privacy, we recommend using the local STDIO setup for sensitive projects.

📦 Installation Guide

Local Setup (STDIO)

For local development, use STDIO transport, which is compatible with Cursor, Claude Code, and Antigravity. This is the recommended approach for maximum privacy and performance.

Prerequisites

• Java 21+: Download from Adoptium.
  • Verify installation: java -version.
  • The output should show Java 21 or higher.
• Node.js 18+: Download from nodejs.org.
  • Verify installation: node --version.
  • The output should show v18.0.0 or higher.

Installation Methods

Option 1: Global Install (Recommended) Install the package globally for system - wide access:

npm install -g @jakarta-migration/mcp-server

After installation:

• The JAR file will be automatically downloaded from GitHub releases on first use.
• The JAR is cached in your home directory for faster subsequent runs.
• You can use the command directly: jakarta-migration-mcp.

Option 2: npx (No Installation) Use npx to run without installing:

npx -y @jakarta-migration/mcp-server

The -y flag automatically accepts the package download. The JAR will be downloaded and cached on first use.

Option 3: Local Development Build If you're building from source or want to use a local JAR:

# Build the JAR
./gradlew bootJar

# Set environment variable to use local JAR
export JAKARTA_MCP_JAR_PATH=/path/to/build/libs/jakarta-migration-mcp-1.0.0-SNAPSHOT.jar

# Run via npm wrapper
npx -y @jakarta-migration/mcp-server

Windows (PowerShell):

# Build the JAR
.\gradlew.bat bootJar

# Set environment variable
$env:JAKARTA_MCP_JAR_PATH = "E:\Source\JakartaMigrationMCP\build\libs\jakarta-migration-mcp-1.0.0-SNAPSHOT.jar"

# Run via npm wrapper
npx -y @jakarta-migration/mcp-server

How the npm Package Works

The npm package is a lightweight Node.js wrapper that:

1. Downloads the JAR from GitHub releases (if not already cached).
2. Caches the JAR in your home directory:
   • Windows: %USERPROFILE%\AppData\.cache\jakarta-migration-mcp\.
   • Linux/macOS: ~/.cache/jakarta-migration-mcp/.
3. Starts the Java process with correct MCP arguments.
4. Handles stdio communication for the MCP protocol.

Pre - download the JAR: You can pre - download the JAR without starting the server:

npx -y @jakarta-migration/mcp-server --download-only

This is useful for:

• Testing the download process.
• Pre - caching the JAR before first use.
• Verifying network connectivity.

Verify Installation: After installing, verify everything works:

# Test the wrapper can find Java and download JAR
npx -y @jakarta-migration/mcp-server --download-only

# Check if command is available (if installed globally)
jakarta-migration-mcp --download-only

You should see:

• Java version detection.
• JAR download or cache confirmation.
• No errors.

Optional configuration

To use a custom JAR path or override transport, see NPM Installation Configuration.

Cursor IDE

1. Open Cursor Settings (Ctrl + , or Cmd + ,).
2. Navigate to Features → MCP.
3. Add configuration:

Windows:

{
  "mcpServers": {
    "jakarta-migration": {
      "command": "npx",
      "args": ["-y", "@jakarta-migration/mcp-server"]
    }
  }
}

Mac/Linux:

{
  "mcpServers": {
    "jakarta-migration": {
      "command": "npx",
      "args": ["-y", "@jakarta-migration/mcp-server"]
    }
  }
}

4. Restart Cursor completely.

Claude Code (VS Code Extension)

1. Open VS Code Settings.
2. Navigate to Claude Code → MCP Settings.
3. Add the same configuration as Cursor.
4. Restart VS Code.

Antigravity

1. Open Antigravity Settings.
2. Navigate to MCP Configuration.
3. Add:

{
  "name": "jakarta-migration",
  "command": "npx",
  "args": ["-y", "@jakarta-migration/mcp-server"]
}

Alternative: Run from JAR Directly

If you've built the project locally and want to bypass the npm wrapper:

Windows:

{
  "mcpServers": {
    "jakarta-migration": {
      "command": "java",
      "args": [
        "-jar",
        "C:\\path\\to\\jakarta-migration-mcp-1.0.0-SNAPSHOT.jar",
        "--spring.profiles.active=mcp-stdio",
        "--spring.ai.mcp.server.transport=stdio",
        "--spring.main.web-application-type=none"
      ]
    }
  }
}

Mac/Linux:

{
  "mcpServers": {
    "jakarta-migration": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/jakarta-migration-mcp-1.0.0-SNAPSHOT.jar",
        "--spring.profiles.active=mcp-stdio",
        "--spring.ai.mcp.server.transport=stdio",
        "--spring.main.web-application-type=none"
      ]
    }
  }
}

⚠️ Important Note

Using the npm wrapper is recommended as it handles JAR downloads, caching, and argument configuration automatically.

Local HTTP Setup (Streamable HTTP or SSE)

For local HTTP - based testing or development:

1. Build the project:

./gradlew bootJar

2. Start server with Streamable HTTP: Windows (PowerShell):

java -jar build\libs\jakarta-migration-mcp-1.0.0-SNAPSHOT.jar --spring.profiles.active=mcp-streamable-http

Mac/Linux:

java -jar build/libs/jakarta-migration-mcp-1.0.0-SNAPSHOT.jar \
  --spring.profiles.active=mcp-streamable-http

Or with SSE (legacy): Windows (PowerShell):

java -jar build\libs\jakarta-migration-mcp-1.0.0-SNAPSHOT.jar --spring.profiles.active=mcp-sse

Mac/Linux:

java -jar build/libs/jakarta-migration-mcp-1.0.0-SNAPSHOT.jar \
  --spring.profiles.active=mcp-sse

3. Test the endpoint: Windows (PowerShell):

# Streamable HTTP (recommended)
curl.exe -X POST http://localhost:8080/mcp/streamable-http `
  -H "Content-Type: application/json" `
  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'

# Or SSE (legacy)
curl.exe -X POST http://localhost:8080/mcp/sse `
  -H "Content-Type: application/json" `
  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'

Mac/Linux:

# Streamable HTTP (recommended)
curl -X POST http://localhost:8080/mcp/streamable-http \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Or SSE (legacy)
curl -X POST http://localhost:8080/mcp/sse \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

4. Configure MCP client to use http://localhost:8080/mcp/streamable-http (or /mcp/sse for SSE).

💻 Usage Examples

Once configured, you can use the MCP tools in your AI assistant:

Basic Usage

Analyze Project Readiness

Analyze the Jakarta readiness of my project at /path/to/my-project

Detect Migration Blockers

Detect any blockers for Jakarta migration in my project

Get Version Recommendations

Recommend Jakarta-compatible versions for my dependencies

Create Migration Plan

Create a migration plan for migrating my project to Jakarta EE

Verify Runtime

Verify the runtime of my migrated application at /path/to/app.jar

🛠️ Available Tools

Refer to MCP Tools Documentation for detailed tool descriptions and parameters.

🐛 Troubleshooting

Tools Not Appearing

1. Restart your IDE completely: MCP servers load on startup.
2. Check MCP server status: Look for errors in IDE logs.
3. Verify configuration: Ensure JSON syntax is correct.
4. Check prerequisites: Java 21+ and Node.js 18+ must be installed.

Connection Issues

For Local (STDIO):

• Verify Java is installed: java -version (should show Java 21+).
• Verify Node.js is installed: node --version (should show v18+).
• Try running manually: npx -y @jakarta-migration/mcp-server.
• Check JAR download: npx -y @jakarta-migration/mcp-server --download-only.
• Verify JAR cache location:
  • Windows: %USERPROFILE%\AppData\.cache\jakarta-migration-mcp\.
  • Linux/macOS: ~/.cache/jakarta-migration-mcp/.
• If JAR download fails, check:
  • Internet connectivity.
  • GitHub releases are accessible.
  • Version matches package.json version.
• For local development, set the JAKARTA_MCP_JAR_PATH environment variable to point to your local JAR file.

Platform - Specific Issues

Windows:

• Use forward slashes in paths: C:/path/to/file.jar.
• Ensure Java is in your PATH.

Mac/Linux:

• Ensure execute permissions: chmod +x gradlew.
• Use absolute paths in configuration.

📚 Documentation

For Users

• Installation Guide: Build and installation instructions.
• MCP Tools Reference: Complete tool documentation.
• Transport Configuration: Explanation of STDIO vs SSE.

For Developers

• Development Setup: Build and development environment setup.
• Architecture: System design and module details.
• Testing Guide: Testing standards and practices.
• Contributing: How to contribute to the project.

🔗 Resources

• MCP Documentation: modelcontextprotocol.io
• Spring AI: docs.spring.io/spring-ai
• Jakarta EE: jakarta.ee

📄 License

This repository uses a dual - licensing model:

Root License (Proprietary)

The root LICENSE file contains the proprietary license for the overall project repository.

Community Modules (Apache 2.0)

The following modules are licensed under the Apache License 2.0:

• community-core-engine: Core migration logic and analysis.
• community-mcp-server: Model Context Protocol server.
• community-intellij-plugin: IntelliJ IDEA plugin.

See for details.

Premium Modules (Proprietary)

The following modules are proprietary and require a commercial license:

• premium-core-engine: Advanced migration features.
• premium-mcp-server: Premium MCP server features.
• premium-intellij-plugin: Premium IntelliJ plugin features.

See for details.

🙏 Acknowledgments

Built with ❤️ for the Java community. Special thanks to:

• The Spring AI team for the MCP framework.
• OpenRewrite for migration recipes.

💡 Usage Tip

Need help? Open an issue or check our documentation.