A comprehensive Spring Boot application that serves as a Model Context Protocol (MCP) Server, providing AI assistants with full-text searchable access to Spring ecosystem documentation via Server-Sent Events (SSE).
This MCP server enables AI assistants (like Claude) to search, browse, and retrieve Spring Framework documentation, code examples, and API references. It includes:
- MCP Server: SSE-based protocol implementation using Spring AI
- Documentation Sync: Automated synchronization from spring.io and GitHub spring-projects repositories
- Full-Text Search: PostgreSQL-powered search across all Spring documentation
- Web Management UI: Thymeleaf-based interface for managing projects, versions, and documentation
- Code Examples: Searchable repository of Spring code snippets
- Migration Recipes: OpenRewrite-based migration knowledge for Spring Boot version upgrades
- Language Evolution: Java (8+) and Kotlin (1.6+) feature tracking with deprecations and code patterns
- Flavors: Company-specific guidelines, architecture patterns, compliance rules, and AI agent configurations
- Flavor Groups: Team-based access control with API key membership for secure guideline sharing
- What is this?
- Changelog
- Quick Start
- API Key Authentication
- Features
- Using with Claude Code
- Configuration
- Troubleshooting
- Roadmap
- Contributing
- License
- Resources
Full changelog: See CHANGELOG.md for detailed version history.
| Version | Date | Highlights |
|---|---|---|
| 1.3.4 | 2025-12-05 | Spring AI 1.1.1, CVE-2025-48924 security fix |
| 1.3.3 | 2025-12-04 | Flavor Groups with team-based access control (3 MCP tools) |
| 1.3.2 | 2025-12-02 | YAML metadata headers for Flavors import/export, new example |
| 1.3.1 | 2025-12-01 | GitHub documentation scanner, enhanced code examples |
| 1.3.0 | 2025-11-30 | Flavors feature (8 MCP tools) |
| 1.2.0 | 2025-11-29 | Language Evolution tracking (6 MCP tools) |
| 1.1.0 | 2025-11-28 | OpenRewrite migration recipes (7 MCP tools) |
| 1.0.2 | 2025-11-27 | Spring Boot 3.5.8, example app |
| 1.0.1 | 2025-11-26 | Initial release (10 MCP tools) |
MCP Tools: 10 (docs) + 7 (migration) + 6 (language) + 8 (flavors) + 3 (flavor groups) = 34 total
IMPORTANT: This project requires Java 25 (LTS).
# Install Java 25 with SDKMAN (recommended)
curl -s "https://get.sdkman.io" | bash
sdk install java 25.0.1-tem
sdk use java 25.0.1-tem
# Verify
java -version # Should show: openjdk version "25"docker-compose up -d postgres./gradlew clean build
java -jar build/libs/spring-boot-documentation-mcp-server-1.3.4.jarOr using Gradle:
./gradlew bootRun- Web UI: http://localhost:8080
- Login: Username:
admin, Password:admin - MCP SSE Endpoint: http://localhost:8080/mcp/spring/sse
The MCP endpoints are protected by secure API key authentication.
API Key Management - Secure key generation with activation controls and confirmation modals |
- Log in to the Web UI at http://localhost:8080 (Username:
admin, Password:admin) - Navigate to Settings (
/settings) - Scroll to "API Key Management" section
- Click "Create New API Key" button
- Enter details: Name (minimum 3 characters) and optional description
- Copy the API key immediately - it will only be shown once!
API Key Format: smcp_<secure-random-string> (256-bit cryptographically secure, BCrypt hashed)
API keys can be provided in three ways:
-
X-API-Key Header (Recommended):
curl -H "X-API-Key: smcp_your_key_here" http://localhost:8080/mcp/spring/sse -
Authorization Bearer Header:
curl -H "Authorization: Bearer smcp_your_key_here" http://localhost:8080/mcp/spring/sse -
Query Parameter (Testing only):
curl "http://localhost:8080/mcp/spring/sse?api_key=smcp_your_key_here"
The dashboard provides an overview of all synchronized Spring projects, versions, and documentation with quick access to management functions.
Login - Secure authentication with Spring Security |
Dashboard - Overview statistics and quick actions |
Spring Boot - Spring Boot project management |
Projects - All Spring projects overview |
Web UI Features:
- Dashboard: Overview statistics, recent updates, and quick actions
- Projects: Manage Spring projects (Boot, Framework, Data, Security, Cloud, etc.)
- Versions: Version management with latest/default marking and EOL tracking
- Users: User management with role-based access (Admin, User, ReadOnly)
- Settings: Application configuration, scheduler settings, feature toggles
Comprehensive documentation synchronization from spring.io and GitHub repositories with full-text search capabilities.
Documentation - Full-text search and browse with filters |
Markdown Content - Expanded documentation with syntax highlighting |
Project Details - Spring Batch project with version list |
Versions - Version management with state tracking |
Features:
- Spring.io Sync: Crawls spring.io/projects to discover projects and documentation
- GitHub Source Docs: Direct AsciiDoc fetching from spring-projects repositories
- Version Detection: Automatic version tracking with tag resolution
- Full-Text Search: PostgreSQL tsvector with relevance ranking
- Scheduled Updates: Configurable cron-based synchronization
A searchable repository of Spring code snippets with syntax highlighting and organization by topic.
Code Examples - Searchable code snippets library with language and category filters |
Features:
- Rich Code Snippets: Complete examples with syntax highlighting (Atom One Dark theme)
- Topic Grouping: Organized by category (Configuration, REST API, Data Access, Security)
- Code View Modal: Click-to-view with copy-to-clipboard functionality
- Language Support: Java, Kotlin, Groovy, XML, YAML, and more
- Tag System: Multiple tags per example for enhanced discoverability
- Version Association: Link examples to specific Spring project versions
OpenRewrite-inspired migration knowledge for upgrading between Spring ecosystem versions. This is an optional feature that can be enabled or disabled.
Migration Recipes - Transformations with before/after code patterns |
Features:
- Dynamic Recipe Generation: Automatically generated based on Spring projects in database
- Version Upgrade Paths: Migrations between consecutive major.minor versions
- Transformation Types: Dependencies, imports, properties, annotations, and code changes
- 55+ Spring Projects: Supports all major Spring ecosystem projects
- Breaking Changes: Severity levels (CRITICAL, ERROR, WARNING, INFO)
Configuration:
mcp:
features:
openrewrite:
enabled: true # Set to false to disableComprehensive tracking of Java (8+) and Kotlin (1.6+) language changes with deprecations, removals, and code pattern examples.
JDK Deprecations - Claude Code querying Java deprecations since JDK 8 |
Language Evolution - Java Records code pattern example |
Features:
- Version Tracking: All Java versions from 8 onwards, Kotlin from 1.6 onwards
- Feature Status: NEW, DEPRECATED, REMOVED, PREVIEW, INCUBATING
- JEP/KEP Tracking: Links to Java Enhancement Proposals and Kotlin Evolution Proposals
- Code Patterns: Old vs new code examples showing how to modernize code
- Spring Boot Compatibility: Which Java/Kotlin versions are required for each Spring Boot version
- Version Comparison: Compare features between two versions
Configuration:
mcp:
features:
language-evolution:
enabled: true # Set to false to disableA flexible system for managing company-specific guidelines, architecture patterns, compliance rules, AI agent configurations, and project initialization templates.
Flavors - Company guidelines with category filtering |
Flavor Details - Hexagonal Architecture pattern with markdown content |
Categories:
- Architecture: Design patterns (hexagonal, microservices, event-driven)
- Compliance: Regulatory requirements (GDPR, SOC2, HIPAA, PCI-DSS)
- Agents: AI agent configurations and prompts for specific tasks
- Initialization: Project setup templates and bootstrapping guides
- General: Coding standards and best practices
Features:
- Markdown Content: Rich content with full-text search
- Import/Export with YAML Metadata: Share flavors via markdown files with YAML front matter
- Category Filtering: Quick access by category
- 8 MCP Tools: AI assistants can query flavor data for context-aware assistance
YAML Front Matter Format:
---
unique-name: my-flavor-identifier
display-name: My Flavor Display Name
category: ARCHITECTURE
pattern-name: Optional Pattern Name
description: Brief description
tags: tag1, tag2, tag3
---
# Actual Markdown Content Here
...Team-based organization and API key-based access control for secure sharing of guidelines with specific teams while keeping public standards available to everyone.
Flavor Groups - Team-based organization with public/private visibility |
Claude Code Integration - AI assistant accessing HR department guidelines |
Core Concepts:
-
Public Groups: Groups without members - visible to everyone
- Use for organization-wide standards (e.g., "Company Coding Standards")
- All API keys can access public groups
-
Private Groups: Groups with API key members - restricted visibility
- Only member API keys can see and access the group
- Use for team-specific guidelines (e.g., "HR Policies", "Security Guidelines")
-
Active/Inactive Status: Inactive groups are completely hidden
Security Model:
MCP Request → API Key Validation → Security Context → Group Membership Check → Access Granted/Denied
Setting Up Groups:
-
Create Groups (Web UI → Groups → New):
- Enter unique name (lowercase, hyphens only)
- Set display name and description
- Choose active status
-
Add API Key Members (Web UI → Groups → Edit):
- Check the API keys that should be members
- Private groups require at least one member
- Public groups should have no members
-
Assign Flavors (Web UI → Flavors → Edit):
- Check/uncheck groups to assign the flavor
- A flavor can belong to multiple groups
Best Practices:
- Use meaningful group names:
payment-team,security-guidelines,frontend-standards - Document group purposes with clear descriptions
- Create separate API keys for different teams/environments
- Monitor API key last-used timestamps in Settings
Configure Claude Code to use the Spring Documentation MCP Server for AI-assisted development.
Add to your Claude Code MCP configuration (.mcp.json):
{
"mcpServers": {
"spring": {
"type": "sse",
"url": "http://localhost:8080/mcp/spring/sse",
"headers": {
"X-API-Key": "YOUR_API_KEY_HERE"
}
}
}
}Replace YOUR_API_KEY_HERE with your actual API key from the Settings page, then restart Claude Code.
Use natural language to search Spring documentation:
> use spring to search for autoconfiguration in Spring Boot 3.5
> use spring to list all Spring projects and show me which ones support messaging
> use spring to get the latest Spring Boot 3.5 version with all documentation links
> use spring to find code examples for REST controllers in Java
Available Documentation Tools:
- Search across all Spring documentation with filters
- List available versions for any Spring project
- Browse all Spring projects by use case
- Get documentation for specific versions
- Search code examples with language/project filters
Get migration assistance when upgrading Spring versions:
> use spring to show me how to migrate from Spring Boot 3.3 to 3.5
> use spring to find all breaking changes in Spring Boot 4.0
> use spring to check if spring-security and flyway are compatible with Spring Boot 4.0
> use spring to search for MockBean replacement in Spring Boot 4.0 migrations
> use spring to find the replacement for deprecated Health.status() method
Available Migration Tools:
- Get comprehensive migration guides between versions
- List breaking changes with severity levels
- Search migration knowledge base
- Check dependency compatibility
- Find deprecation replacements
Query Java and Kotlin language evolution:
> use spring to show me all Java versions and their LTS status
> use spring to list new features in Java 21
> use spring to show what changed between Java 17 and Java 21
> use spring to find all deprecated features since Java 8
> use spring to get the Java version requirements for Spring Boot 3.5.8
> use spring to search for pattern matching features in Java
Available Language Tools:
- List all Java/Kotlin versions with feature counts
- Get features by version with status filtering
- Compare features between two versions
- Get old vs new code patterns for modernization
- Check Spring Boot language requirements
Access company-specific guidelines and patterns:
> use spring to search for hexagonal architecture guidelines
> use spring to list all architecture patterns for microservices
> use spring to get our GDPR compliance rules
> use spring to show the AI agent configuration for code reviews
> use spring to get the project initialization template for Spring Boot microservices
With Team-Based Access (Flavor Groups):
> use spring to list all flavor groups I have access to
> use spring to get all guidelines from the engineering-standards group
> use spring to show me the payment-team architecture patterns
(only accessible if your API key is a member of the payment-team group)
> use spring to get the HR department policies
(requires membership in the hr-policies private group)
Available Flavor Tools:
- Search guidelines with full-text search
- Get complete flavor content by name
- List flavors by category
- Get architecture patterns for specific technologies
- Get compliance rules by framework
- List accessible flavor groups
- Get all flavors in a specific group
Team Configuration Example:
Different teams can use different API keys to access their specific groups:
// Engineering Team - .mcp.json
{
"mcpServers": {
"spring": {
"type": "sse",
"url": "http://localhost:8080/mcp/spring/sse",
"headers": {
"X-API-Key": "smcp_engineering_team_key"
}
}
}
}
// Security Team - .mcp.json
{
"mcpServers": {
"spring": {
"type": "sse",
"url": "http://localhost:8080/mcp/spring/sse",
"headers": {
"X-API-Key": "smcp_security_team_key"
}
}
}
}# Database
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=spring_mcp
export DB_USER=postgres
export DB_PASSWORD=postgres
# Security
export ADMIN_USER=admin
export ADMIN_PASSWORD=changeme
# Server
export SERVER_PORT=8080
# Bootstrap
export BOOTSTRAP_DOCS=false # Set to true for sample dataKey configuration in src/main/resources/application.yml:
spring:
ai:
mcp:
server:
name: "spring-documentation-server"
sse-endpoint: /mcp/spring/sse
sse-message-endpoint: /mcp/spring/messages
mcp:
features:
openrewrite:
enabled: true # Migration recipes
language-evolution:
enabled: true # Java/Kotlin tracking
flavors:
enabled: true # Company guidelines & groups
documentation:
fetch:
enabled: true
schedule: "0 0 2 * * ?" # Daily at 2 AMjava -version # Verify Java 25
echo $JAVA_HOME # Ensure JAVA_HOME points to Java 25docker-compose ps
docker-compose logs postgres
psql -h localhost -U postgres -d spring_mcp # Password: postgres./gradlew clean build --refresh-dependencieslsof -ti :8080 | xargs kill -9-
Verify application is running:
curl http://localhost:8080/actuator/health
-
Check MCP endpoint with API key:
curl -H "X-API-Key: your_api_key" http://localhost:8080/mcp/spring/sse -
Test with MCP Inspector:
npx @modelcontextprotocol/inspector
Configure with URL:
http://localhost:8080/mcp/spring/sseand your API key header.
- Spring Boot 3.5.8 with Spring AI 1.1.1 MCP Server
- PostgreSQL database with full-text search
- 34 MCP tools (documentation, migration, language, flavors, groups)
- Web management UI with all features
- API Key authentication with BCrypt encryption
- Documentation sync from spring.io and GitHub
- Code examples repository
- OpenRewrite migration recipes
- Language Evolution tracking (Java/Kotlin)
- Flavors with YAML import/export
- Flavor Groups with team-based access control
- Semantic search using embeddings
- Version comparison and diff
- Export features (PDF, Markdown)
- Analytics and usage tracking
- Multi-language documentation support
- Air-Gapped Replication Mode
This is a demonstration/reference MCP server implementation. Contributions are welcome!
Areas for contribution:
- Additional Spring project coverage
- Enhanced search algorithms
- UI/UX improvements
- Performance optimizations
- Documentation and test coverage
This project is licensed under the MIT License - see the LICENSE file for details.
- Spring AI MCP Server Docs: https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html
- MCP Protocol Specification: https://spec.modelcontextprotocol.io/
- Spring Documentation: https://spring.io/projects
For detailed technical reference including:
- Testing the MCP Server with MCP Inspector
- Complete Technology Stack
- Database Schema and Full-Text Search
- Development Guide (tests, migrations, cleaning builds)
- API Endpoints Reference
- All 34 MCP Tool Parameters with JSON Examples
