AI Explainer MCP Server

A production-ready Model Context Protocol (MCP) Server built with Java 21, Spring Boot, and the MCP Java SDK.

The server enables AI assistants such as Claude Code CLI, Claude Desktop, and Open WebUI to understand and explain software artifacts including BPMN processes, Java source code, Groovy scripts, JavaScript files, and documents (PDF, DOCX, TXT).

Features

The MCP server provides AI-powered explanations for both technical and non-technical audiences.

Supported inputs include:

Activiti BPMN XML
Java Source Code
Groovy Scripts
JavaScript Files
PDF Documents
Microsoft Word (DOCX)
Text Files

For every supported input, the MCP server can generate:

Technical Explanation
Non-Technical Explanation
Executive Summary
Context
Business Purpose
Recommendations

Supported MCP Clients

Claude Code CLI
Claude Desktop
Open WebUI
Any MCP Compatible Client

Technology Stack

Technology	Version
Java	21
Spring Boot	3.5+
Spring AI	Latest
MCP Java SDK	Latest
Streamable HTTP	MCP Standard
Jackson	Latest
Maven	Latest

Parsing Libraries

Activiti BPMN Parser
JavaParser
Groovy AST
Esprima (JavaScript Parser)
Apache PDFBox
Apache POI

Architecture

                    +----------------------+
                    | Claude Desktop       |
                    | Claude Code CLI      |
                    | Open WebUI           |
                    +----------+-----------+
                               |
                     Streamable HTTP
                               |
+---------------------------------------------------------------+
|                    Spring Boot MCP Server                     |
|---------------------------------------------------------------|
|                                                               |
| MCP Server                                                    |
|                                                               |
| • Tools                                                       |
| • Resources                                                   |
| • Prompts                                                     |
| • Elicitation                                                 |
|                                                               |
|---------------------------------------------------------------|
| Business Services                                             |
|                                                               |
| BPMN Analyzer                                                 |
| Java Analyzer                                                 |
| Groovy Analyzer                                               |
| JavaScript Analyzer                                           |
| Document Analyzer                                             |
| AI Prompt Builder                                             |
| Summary Generator                                             |
| Context Generator                                             |
|---------------------------------------------------------------|
| Parsing Layer                                                 |
|                                                               |
| Activiti BPMN                                                 |
| JavaParser                                                    |
| Groovy AST                                                    |
| Esprima                                                       |
| Apache PDFBox                                                 |
| Apache POI                                                    |
|---------------------------------------------------------------|
| AI Layer                                                      |
|                                                               |
| Claude                                                       |
| OpenAI                                                       |
| Gemini                                                       |
| Ollama                                                       |
| Azure OpenAI                                                 |
+---------------------------------------------------------------+

Project Structure

mcp-ai-explainer

├── src
│   ├── main
│   │   ├── java
│   │   │
│   │   ├── config
│   │   ├── controller
│   │   ├── ai
│   │   ├── parser
│   │   │     ├── bpmn
│   │   │     ├── java
│   │   │     ├── groovy
│   │   │     ├── javascript
│   │   │     ├── pdf
│   │   │     ├── docx
│   │   │     └── txt
│   │   │
│   │   ├── service
│   │   ├── model
│   │   ├── util
│   │   │
│   │   └── mcp
│   │         ├── tools
│   │         ├── resources
│   │         ├── prompts
│   │         └── elicitation
│   │
│   └── resources
│
├── docs
├── README.md
└── pom.xml

MCP Tools

1. explain-bpmn

Input

Activiti BPMN XML

Output

Technical Explanation
Non-Technical Explanation
Business Flow
Process Summary
Actors
Tasks
Gateways
Service Tasks
Business Rules
Recommendations

2. explain-java

Input

Java Class

Output

Technical Explanation
Non-Technical Explanation
Class Summary
Package Information
Dependencies
Methods
Design Patterns
Business Logic
Recommendations

3. explain-groovy

Input

Groovy Script

Output

Technical Explanation
Non-Technical Explanation
Flow Summary
DSL Explanation
Closures
Variables
Recommendations

4. explain-javascript

Input

JavaScript File

Output

Technical Explanation
Non-Technical Explanation
Functions
Modules
Async Flow
API Calls
Recommendations

5. summarize-document

Supported Files

PDF
DOCX
TXT

Output

Executive Summary
Technical Summary
Non-Technical Summary
Context
Key Topics
Important Sections
Recommendations

MCP Resources

resource://parser/bpmn

resource://parser/java

resource://parser/groovy

resource://parser/javascript

resource://parser/pdf

resource://parser/docx

resource://parser/text

resource://analysis/latest

resource://analysis/history

MCP Prompts

technical-explanation

non-technical-explanation

summary

context

business-process

developer-documentation

executive-summary

MCP Elicitation

The MCP server automatically asks clarifying questions when additional context is required.

Example:

You uploaded a BPMN file.

Which explanation would you like?

1. Technical
2. Business
3. Both

Another example:

You uploaded Java source code.

Select explanation depth.

1. High Level
2. Detailed
3. Line by Line

Tool Chains

BPMN Analysis

Read BPMN
      │
Validate XML
      │
Parse BPMN
      │
Extract Workflow
      │
Generate Process Model
      │
LLM
      │
Technical Explanation
      │
Business Explanation

Java Analysis

Read Java File
      │
JavaParser
      │
Generate AST
      │
Dependency Analysis
      │
Method Analysis
      │
LLM
      │
Technical Explanation
      │
Business Explanation

Groovy Analysis

Read Script
      │
Groovy AST
      │
Extract DSL
      │
LLM
      │
Explanation

JavaScript Analysis

Read JavaScript
      │
Esprima
      │
AST
      │
Module Analysis
      │
LLM
      │
Explanation

Document Analysis

Read File
      │
PDFBox / Apache POI
      │
Extract Text
      │
Chunk Content
      │
Generate Summary
      │
Generate Context
      │
LLM
      │
Technical Explanation
      │
Business Explanation

Parsing Capabilities

BPMN

Extracts:

Start Events
End Events
User Tasks
Service Tasks
Script Tasks
Gateways
Events
Sequence Flows
Variables
Forms
Listeners
Business Rules

Java

Extracts:

Package
Imports
Classes
Interfaces
Enums
Fields
Constructors
Methods
Annotations
Generics
Dependencies
JavaDocs

Groovy

Extracts:

Methods
Closures
DSL
Variables
Classes
Flow

JavaScript

Extracts:

Functions
Classes
Arrow Functions
Modules
Promises
Async/Await
Imports
Exports

PDF

Extracts:

Paragraphs
Headings
Tables
Images
Metadata

DOCX

Extracts:

Paragraphs
Tables
Lists
Headers
Footers

Streamable HTTP Endpoints

POST   /mcp

GET    /mcp

DELETE /mcp

AI Prompt Examples

Technical Prompt

You are a senior software architect.

Explain the supplied artifact.

Include:

- Architecture
- Flow
- Business Logic
- Dependencies
- Design Patterns
- Recommendations

Business Prompt

You are a business analyst.

Explain the artifact in simple language.

Avoid technical jargon.

Use business terminology and real-world examples.

Provide step-by-step explanations.

Example Response

{
  "technical": {
    "summary": "...",
    "architecture": "...",
    "flow": "...",
    "dependencies": [],
    "businessLogic": "...",
    "recommendations": []
  },
  "nonTechnical": {
    "summary": "...",
    "businessPurpose": "...",
    "story": "...",
    "stepByStep": [],
    "recommendations": []
  }
}

Maven Dependencies

Spring Boot
Spring AI
Spring AI MCP Server
MCP Java SDK
JavaParser
Groovy
Apache PDFBox
Apache POI
Jackson
SLF4J
Spring Validation

Future Roadmap

Phase 1

Spring Boot MCP Server
Streamable HTTP
MCP Tools
MCP Resources
MCP Prompts
MCP Elicitation
BPMN Support
Java Support
Groovy Support
JavaScript Support
PDF Support
DOCX Support
TXT Support

Phase 2

Multi-LLM Support
Prompt Templates
AI Memory
Vector Database
RAG
Semantic Search
Caching

Phase 3

GitHub Integration
GitLab Integration
Jira Integration
Confluence Integration
Repository Analysis
Merge Request Analysis
Pull Request Analysis

Phase 4

Code Generation
BPMN to Java
BPMN to Spring Boot
Documentation Generator
Mermaid Diagram Generator
PlantUML Generator
Sequence Diagram Generator
Test Case Generator
Security Review
Performance Review
Kubernetes Deployment

Long-Term Vision

The goal of this project is to build a reusable, enterprise-grade AI-powered MCP server capable of understanding source code, business processes, scripts, and documents. By leveraging modern parsing libraries, large language models, and the Model Context Protocol, the server provides rich explanations tailored to both technical and non-technical audiences. Its modular architecture enables seamless integration with developer tools, AI assistants, enterprise knowledge platforms, and future automation workflows, making it a scalable foundation for intelligent software engineering and business process analysis.

Requirements for a Working MCP Server

To be compatible with MCP-enabled clients, your server must implement the following capabilities:

✅ Implement the Model Context Protocol (MCP)
✅ Support one or both transport mechanisms:
- STDIO Transport
- Streamable HTTP Transport
✅ Register Tools
✅ Register Resources
✅ Register Prompts
✅ Return MCP-compliant JSON-RPC responses
✅ Handle:
- Initialization
- Capability negotiation
- Tool invocation
- Resource requests
- Prompt requests
- Error handling
- Session lifecycle

Claude Desktop

Configure your MCP server in the Claude Desktop MCP configuration file.

The exact configuration file location depends on:

Operating System
Claude Desktop version

STDIO Configuration

{
  "mcpServers": {
    "java-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/mcp-server.jar"
      ]
    }
  }
}

Streamable HTTP Configuration

{
  "mcpServers": {
    "java-mcp": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Claude Code CLI

Claude Code CLI can connect to the same MCP server.

Depending on the supported transport, configure it to use either:

Local executable (STDIO)
Streamable HTTP endpoint

Typical workflow:

Claude Code CLI
        │
        ▼
MCP Server
        │
        ▼
Registered Tools

Visual Studio Code

VS Code MCP extensions generally support the following connection methods:

Local MCP Process

VS Code
    │
    ▼
STDIO
    │
    ▼
Java MCP Server

Streamable HTTP

VS Code
    │
    ▼
HTTP
    │
    ▼
http://localhost:8080/mcp

Support depends on the installed extension.

Windsurf

Windsurf can integrate with MCP servers using either:

Local MCP process (STDIO)
Streamable HTTP endpoint

Configuration depends on the Windsurf version being used.

Open WebUI

Open WebUI can communicate with external MCP servers.

Typical configuration includes:

MCP Server URL
Authentication (optional)
Available Tools
Available Resources
Available Prompts

Example:

Setting	Value
MCP Server URL	`http://localhost:8080/mcp`
Authentication	Optional
Transport	Streamable HTTP
Protocol	MCP

Architecture

                Claude Desktop
                      │
              Claude Code CLI
                      │
                  VS Code
                      │
                  Windsurf
                      │
                 Open WebUI
                      │
                      ▼
        ┌───────────────────────────────┐
        │      Java MCP Server          │
        │-------------------------------│
        │ • MCP Protocol                │
        │ • Streamable HTTP             │
        │ • STDIO                       │
        │ • Tool Registry               │
        │ • Resource Registry           │
        │ • Prompt Registry             │
        │ • Elicitation                 │
        └───────────────────────────────┘
                      │
                      ▼
             Parser Services
        ├── BPMN Parser
        ├── Java Parser
        ├── Groovy Parser
        ├── JavaScript Parser
        └── Document Parser
                      │
                      ▼
               AI Provider Layer
        ├── OpenAI
        ├── Claude
        ├── Gemini
        ├── Ollama
        └── Azure OpenAI

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
ai-service/src/main/java/com/github/mcp/ai		ai-service/src/main/java/com/github/mcp/ai
docker		docker
kubernetes		kubernetes
mcp-common		mcp-common
mcp-elicitation/src/main/java/com/github/mcp/elicitation		mcp-elicitation/src/main/java/com/github/mcp/elicitation
mcp-prompts/src/main/java/com/github/mcp/prompts		mcp-prompts/src/main/java/com/github/mcp/prompts
mcp-resources/src/main/java/com/github/mcp/resources		mcp-resources/src/main/java/com/github/mcp/resources
mcp-server		mcp-server
mcp-springboot-starter		mcp-springboot-starter
mcp-tools/src/main/java/com/github/mcp/tools		mcp-tools/src/main/java/com/github/mcp/tools
parser-bpmn/src/main/java/com/github/mcp/parser/bpmn		parser-bpmn/src/main/java/com/github/mcp/parser/bpmn
parser-document/src/main/java/com/github/mcp/parser/document		parser-document/src/main/java/com/github/mcp/parser/document
parser-groovy/src/main/java/com/github/mcp/parser/groovy		parser-groovy/src/main/java/com/github/mcp/parser/groovy
parser-java/src/main/java/com/github/mcp/parser/java		parser-java/src/main/java/com/github/mcp/parser/java
parser-javascript/src/main/java/com/github/mcp/parser/javascript		parser-javascript/src/main/java/com/github/mcp/parser/javascript
.DS_Store		.DS_Store
README.md		README.md
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

AI Explainer MCP Server

Features

Supported MCP Clients

Technology Stack

Parsing Libraries

Architecture

Project Structure

MCP Tools

1. explain-bpmn

Input

Output

2. explain-java

Input

Output

3. explain-groovy

Input

Output

4. explain-javascript

Input

Output

5. summarize-document

Supported Files

Output

MCP Resources

MCP Prompts

MCP Elicitation

Tool Chains

BPMN Analysis

Java Analysis

Groovy Analysis

JavaScript Analysis

Document Analysis

Parsing Capabilities

BPMN

Java

Groovy

JavaScript

PDF

DOCX

Streamable HTTP Endpoints

AI Prompt Examples

Technical Prompt

Business Prompt

Example Response

Maven Dependencies

Future Roadmap

Phase 1

Phase 2

Phase 3

Phase 4

Long-Term Vision

Requirements for a Working MCP Server

Claude Desktop

STDIO Configuration

Streamable HTTP Configuration

Claude Code CLI

Visual Studio Code

Local MCP Process

Streamable HTTP

Windsurf

Open WebUI

Architecture

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages