Spring Boot Bootstrap MCP Server

A Model Context Protocol (MCP) server for bootstrapping Spring Boot projects using Spring Initializr. This server provides AI assistants with tools to discover available Spring Boot configurations and generate customized project templates.

Features

Available Tools

1. getSpringBootInitDetails

   • Retrieves all available configuration options from Spring Initializr
   • Returns available Spring Boot versions, dependencies, Java versions, and more
   • Use this first to discover valid parameter values

2. downloadSpringBootProject

   • Downloads a fully configured Spring Boot project as a ZIP file OR extracts directly to a directory
   • Smart Path Detection: If path ends with .zip, saves as ZIP file; otherwise extracts all files to directory
   • Supports customization of build tool, language, dependencies, and more
   • Automatically creates parent directories if needed
   • Extracted projects are ready to open in your IDE immediately

Quick Start

1. Download the Server

Go to the Releases page and download the appropriate version for your platform:

Option A: Native Binary (Recommended - Ultra Fast Startup)

Fastest startup time (~87ms) with no Java installation required!

• Windows: Download app-bootstrap.exe
• macOS: Download app-bootstrap (macOS binary)
• Linux: Download app-bootstrap (Linux binary)

Save to: C:/mcp-servers/ (Windows) or ~/mcp-servers/ (Mac/Linux)

macOS/Linux: Make the binary executable:

chmod +x ~/mcp-servers/app-bootstrap

Option B: JAR File (Requires Java 21+)

Download app-bootstrap-0.0.1-SNAPSHOT.jar

Save to: C:/mcp-servers/app-bootstrap.jar (Windows) or ~/mcp-servers/app-bootstrap.jar (Mac/Linux)

2. Configure Your MCP Client

Choose your client below and add the configuration:

GitHub Copilot (VS Code)

Edit: %APPDATA%\Code\User\mcp.json (Windows) or ~/Library/Application Support/Code/User/mcp.json (Mac/Linux)

Native Binary (Recommended - Fastest):

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "C:/mcp-servers/app-bootstrap.exe",
      "args": []
    }
  }
}

JAR File:

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "java",
      "args": ["-jar", "C:/mcp-servers/app-bootstrap.jar"]
    }
  }
}

Claude Desktop

Edit: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)

Native Binary (Recommended - Fastest):

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "C:/mcp-servers/app-bootstrap.exe",
      "args": []
    }
  }
}

macOS/Linux Native Binary:

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "/Users/username/mcp-servers/app-bootstrap",
      "args": []
    }
  }
}

JAR File:

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "java",
      "args": ["-jar", "C:/mcp-servers/app-bootstrap.jar"]
    }
  }
}

Other MCP Clients (Cline, Zed, Cody, Continue.dev)

Native Binary (Recommended - Fastest):

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "/path/to/app-bootstrap",
      "args": []
    }
  }
}

JAR File:

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "java",
      "args": ["-jar", "/path/to/app-bootstrap.jar"]
    }
  }
}

Path examples:

• Windows native: C:/mcp-servers/app-bootstrap.exe
• Mac/Linux native: /Users/username/mcp-servers/app-bootstrap
• JAR: /Users/username/mcp-servers/app-bootstrap.jar

3. Restart Your Client

Restart VS Code, Claude Desktop, or your MCP client to load the server.

4. Start Using

Try prompts like:

# Download as ZIP file
Create a Spring Boot REST API with PostgreSQL and JPA, save to C:/projects/myapi.zip

# Extract directly to directory (ready to open in IDE)
Create a Spring Boot REST API with PostgreSQL and JPA, extract to C:/projects/myapi

---

Detailed Documentation

Alternative Installation Methods

Option 1: Download Pre-built Release (Recommended - Already covered in Quick Start above)

See the Quick Start section above for the easiest way to get started.

Available formats:

• Native Binary: Ultra-fast startup (~87ms), no Java installation required
• JAR File: Traditional Java archive, requires Java 21+

Option 2: Build from Source

If you want to build from source or contribute to the project:

Prerequisites for Building

• Java 21 or higher
• Gradle (included via wrapper)
• GraalVM (optional, for native image builds)

Build Steps

Standard JAR:

# Windows
.\gradlew.bat clean bootJar

# Linux/Mac
./gradlew clean bootJar

The built JAR file will be located at: build/libs/app-bootstrap-0.0.1-SNAPSHOT.jar

Native Image (GraalVM required):

# Windows
.\gradlew.bat nativeCompile

# Linux/Mac
./gradlew nativeCompile

The native binary will be located at:

• Windows: build/native/nativeCompile/app-bootstrap.exe
• Linux/Mac: build/native/nativeCompile/app-bootstrap

Benefits of Native Image:

• Ultra-fast startup: ~87 milliseconds vs 2-5 seconds for JVM
• Lower memory: ~1/4 of JVM memory usage
• No Java required: Standalone executable
• Perfect for: Serverless, containers, CLI tools

Configuration

Server Configuration (Optional)

The server is pre-configured and ready to use. Default settings are in src/main/resources/application.properties:

spring.main.web-application-type=none
spring.main.banner-mode=off
spring.application.name=app-bootstrap

spring.ai.mcp.server.name=spring-bootstrap-mcp
spring.ai.mcp.server.version=0.0.1
spring.ai.mcp.server.stdio=true
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.annotation-scanner.enabled=true

logging.file.name=./mcp-springboot-bootstrap-stdio-server.log

Note: An alternative WebFlux configuration is available at src/main/resources/application.json for reactive applications (requires building from source).

---

Client-Specific Configuration Details

The Quick Start section above covers most use cases. This section provides additional details and troubleshooting.

GitHub Copilot (VS Code) - Extended

Configuration file locations:

• Windows: %APPDATA%\Code\User\mcp.json
• macOS: ~/Library/Application Support/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json

Complete configuration example:

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "java",
      "args": ["-jar", "C:/mcp-servers/app-bootstrap.jar"],
      "env": {}
    }
  }
}

Mac/Linux example:

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "java",
      "args": ["-jar", "/Users/username/mcp-servers/app-bootstrap.jar"]
    }
  }
}

#### Step 3: Restart VS Code

#### Step 4: Use with Copilot Chat

Open Copilot Chat and use prompts like:

Create a Spring Boot REST API with PostgreSQL and JPA, save to C:/projects/myapi.zip

### 2. Claude Desktop

#### Step 1: Get the JAR file

**Option A: Download pre-built release (Recommended)**
- Download from [Releases page](../../releases/latest)
- Save to a location like `C:/mcp-servers/app-bootstrap-0.0.1-SNAPSHOT.jar` (Windows)
- Or `~/mcp-servers/app-bootstrap-0.0.1-SNAPSHOT.jar` (macOS/Linux)

**Option B: Build from source**
```bash
.\gradlew.bat clean bootJar  # Windows
./gradlew clean bootJar      # Linux/Mac

Step 2: Configure Claude Desktop

Edit the Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "java",
      "args": [
        "-jar",
        "C:/mcp-servers/app-bootstrap-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

macOS/Linux example:

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "java",
      "args": [
        "-jar",
        "/Users/username/mcp-servers/app-bootstrap-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

After restarting Claude Desktop, the tools will be available.

Other MCP Clients - Extended

Configuration for Cline, Zed Editor, Sourcegraph Cody, Continue.dev, and other MCP-compatible clients:

{
  "mcpServers": {
    "springboot-bootstrap": {
      "command": "java",
      "args": ["-jar", "/path/to/app-bootstrap.jar"]
    }
  }
}

Replace /path/to/app-bootstrap.jar with your actual file path.

---

Usage Examples

Example 1: Basic Web Application (Extracted)

Create a basic Spring Boot web application with Java 21 and extract it to C:/projects/demo

The AI will:

1. Call getSpringBootInitDetails() to get available options
2. Select appropriate defaults (Spring Web, latest Spring Boot version, etc.)
3. Call downloadSpringBootProject() with the configuration
4. Extract all files directly to C:/projects/demo (ready to open in IDE)

Example 2: Microservice with Database (ZIP Download)

I need a Spring Boot microservice with:
- Spring Boot 3.5.9
- Java 21, Gradle
- Dependencies: Web, Data JPA, PostgreSQL, Lombok, Actuator
- Group: com.mycompany
- Artifact: user-service
- Save to: C:/microservices/user-service.zip

Result: Downloads a ZIP file that can be distributed or archived.

Example 3: Reactive Application (Extracted)

Create a Spring Boot WebFlux application with MongoDB and extract to C:/projects/reactive-api

Result: All project files extracted and ready to import into your IDE.

Example 4: Quick Start Development

I need a REST API with Spring Boot, PostgreSQL, and Lombok. Extract it to C:/workspace/api-project so I can start coding immediately.

Result: Project extracted and ready - just open the directory in VS Code or IntelliJ!

Tool Parameters

getSpringBootInitDetails

No parameters required. Returns JSON with all available configuration options.

downloadSpringBootProject

Parameter	Required	Description	Example
type	Yes	Build tool type	gradle-project, maven-project
language	Yes	Programming language	java, kotlin, groovy
bootVersion	Yes	Spring Boot version (EXACT format from metadata)	3.5.9, 2.7.18.RELEASE
groupId	Yes	Maven group ID	com.example
artifactId	Yes	Project/artifact ID	demo
name	Yes	Project display name	Demo Application
description	No	Project description	Demo project for Spring Boot
packageName	Yes	Base package name	com.example.demo
packaging	Yes	Package type	jar, war
javaVersion	Yes	Java version	17, 21, 23
dependencies	Yes	Comma-separated dependency IDs	web,data-jpa,postgresql
configurationFileFormat	No	Config file format	properties, yaml
downloadPath	Yes	Path for output	See below ⬇️

Important: Spring Boot Version Format

⚠️ CRITICAL: Spring Boot uses different version formats:

• Spring Boot 3.x: Semantic versioning (e.g., 3.5.9, 3.4.2, 3.3.7)
• Spring Boot 2.x: Includes .RELEASE suffix (e.g., 2.7.18.RELEASE, 2.6.15.RELEASE)

Always call getSpringBootInitDetails() first to get the exact version format. Do not guess or assume the format! | downloadPath | Yes | Path for output | See below ⬇️ |

downloadPath Behavior

The downloadPath parameter determines how the project is delivered:

• Ends with .zip → Saves as ZIP file
  • Example: C:/projects/myapp.zip
  • Use case: Archive, share, or manually extract later

Sample API Call

For reference, here's what the actual Spring Initializr API call looks like:

https://start.spring.io/starter.zip?type=gradle-project&language=java&bootVersion=3.5.9&groupId=com.example&artifactId=demo&name=demo&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.demo&packaging=jar&javaVersion=17&configurationFileFormat=properties&dependencies=web,postgresql

This URL structure shows how all the parameters are passed to Spring Initializr. The MCP tool handles building this URL automatically based on your inputs.

• Does NOT end with .zip → Extracts all files to directory
  • Example: C:/projects/myapp
  • Use case: Ready to open in IDE immediately, start coding right away
  • All project files are extracted maintaining the proper structure

Common Dependencies

Some frequently used dependency IDs:

• web - Spring Web (REST APIs)
• webflux - Spring WebFlux (Reactive)
• data-jpa - Spring Data JPA
• data-mongodb - Spring Data MongoDB
• postgresql - PostgreSQL Driver
• mysql - MySQL Driver
• h2 - H2 Database
• lombok - Lombok
• actuator - Spring Boot Actuator
• security - Spring Security
• validation - Validation
• cloud-config-client - Spring Cloud Config Client
• cloud-eureka-client - Eureka Discovery Client

Use getSpringBootInitDetails() to get the complete list with descriptions.

Troubleshooting

JAR file not found

# Rebuild the project
.\gradlew.bat clean bootJar

Connection errors

• Ensure you have internet access to reach start.spring.io
• Check firewall settings

Tools not appearing in MCP client

• Verify the JAR path in your MCP configuration is correct
• Restart the MCP client completely
• Check logs at ./mcp-springboot-bootstrap-stdio-server.log

Permission errors when downloading

• Ensure the download directory exists and you have write permissions
• Use absolute paths (e.g., C:/projects/app.zip not ./app.zip)

Development

Automated Releases

Every push to the main branch or when a version tag is created automatically triggers a GitHub Actions workflow that:

1. Builds native executables for Windows, macOS, and Linux using GraalVM
2. Builds the traditional JAR file
3. Creates a GitHub release with all artifacts
4. Uploads native binaries and JAR to the release

For releases with version tags (e.g., v1.0.0):

git tag v1.0.0
git push origin v1.0.0

The workflow automatically creates a release with:

• app-bootstrap.exe (Windows native)
• app-bootstrap (Linux native)
• app-bootstrap (macOS native)
• app-bootstrap-0.0.1-SNAPSHOT.jar (traditional JAR)

No manual building needed for end users! Just download from the Releases page.

Project Structure

src/main/java/org/springboot/bootstrap/
├── AppBootstrapApplication.java          # Main application
├── config/
│   └── RestClientConfig.java            # RestClient configuration
└── tools/
    └── SpringInItTools.java             # MCP tools implementation

Adding New Tools

1. Add a new method in SpringInItTools.java
2. Annotate with @McpTool with name and description
3. Push to main branch (automatic build and release)
4. Tools are automatically discovered via annotation scanning

Testing

# Run tests
.\gradlew.bat test

# Run application locally (for testing)
.\gradlew.bat bootRun

Technology Stack

• Spring Boot: 3.5.9
• Spring AI MCP Server: 1.1.2
• Java: 21
• Build Tool: Gradle
• HTTP Client: Apache HttpClient 5
• Native Image: GraalVM Native Image support for ultra-fast startup
• CI/CD: GitHub Actions for multi-platform native builds

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is provided as-is for demonstration purposes.

Support

For issues or questions:

• Check the troubleshooting section above
• Review logs at ./mcp-springboot-bootstrap-stdio-server.log
• Ensure you're using Java 21 or higher

Related Links

• Spring Initializr
• Model Context Protocol Specification
• Spring AI Documentation
• Spring Boot Documentation

---

Built with ❤️ using Spring Boot and Spring AI MCP Server