GitHub - hpalma/springinitializr-mcp: MCP server for Spring Initializr (original) (raw)

Spring Initializr MCP Server

An MCP (Model Context Protocol) server that provides access to Spring Initializr functionality, allowing AI assistants to generate and download Spring Boot projects programmatically.

What is this?

This project implements an MCP server that wraps the Spring Initializr API, enabling AI assistants (like Claude) to create Spring Boot projects with custom configurations. Instead of manually visiting start.spring.io, you can now ask your AI assistant to generate projects with specific dependencies, Java versions, and project structures.

Features

Supported Parameters

When generating a project, you can specify:

Installation

Download Pre-built Binaries

Download the appropriate binary for your platform from the Releases page:

Build from Source

Requirements:

git clone https://github.com/hpalma/springinitializr-mcp.git cd springinitializr-mcp ./gradlew build ./gradlew nativeCompile

Usage with Claude Desktop

Add the MCP server to your Claude Desktop configuration:

macOS/Linux

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "springinitializr": { "command": "/path/to/springinitializr-mcp-binary" } } }

Windows

Edit %APPDATA%/Claude/claude_desktop_config.json:

{ "mcpServers": { "springinitializr": { "command": "C:\path\to\springinitializr-mcp-windows-x64.exe" } } }

Example Usage

Once configured, you can ask Claude to generate Spring Boot projects:

"Create a Spring Boot web application with Spring Data JPA, PostgreSQL, and Spring Security dependencies"

"Generate a Kotlin Spring Boot project using Gradle with WebFlux and MongoDB"

"Create a Maven-based Spring Boot project with Thymeleaf, Validation, and Actuator"

The tool will generate and download the project as a ZIP file to your specified location, with optional automatic extraction.

Available Dependencies

The server supports all Spring Initializr dependencies, including:

The dependency list is automatically updated by fetching the latest metadata from Spring Initializr.

Development

Running in Development

Run with dev profile for more logging

./gradlew bootRun --args='--spring.profiles.active=dev'

Generate updated constants from Spring Initializr

./gradlew generateToolDescriptions

Run tests

./gradlew test

Run native tests

./gradlew nativeTest

Code Generation

The project uses a Gradle task to fetch the latest Spring Initializr metadata and generate constants for supported dependencies and Java versions:

./gradlew generateToolDescriptions

This ensures the tool always supports the latest Spring Boot versions and dependencies by:

Testing

The project includes comprehensive tests:

Run all tests

./gradlew test nativeTest nativeIntegrationTest

Run only unit tests

./gradlew test

Run only native integration tests

./gradlew nativeIntegrationTest

Native Performance Testing

The integration tests include startup time validation to ensure native compilation provides expected performance benefits:

CI/CD

The project uses GitHub Actions for:

Release Process

  1. Create a new release on GitHub or trigger workflow manually
  2. Native binaries are automatically built for all platforms
  3. Binaries are attached to the release for download

Configuration

Application Configuration

The server uses Spring Boot configuration with the following key properties:

spring: application: name: springinitializr-mcp ai: mcp: server: name: springinitializr version: 1.0.0

Environment Profiles

API Reference

Tool: generate-spring-boot-project

Generates and downloads a Spring Boot project with the specified configuration.

Parameters:

Returns: Absolute path to the downloaded file or extracted directory

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass (./gradlew test nativeTest)
  6. Update generated constants if needed (./gradlew generateToolDescriptions)
  7. Commit your changes (git commit -m 'Add amazing feature')
  8. Push to the branch (git push origin feature/amazing-feature)
  9. Open a Pull Request

Troubleshooting

Common Issues

Native executable fails to start:

Project generation fails:

MCP connection issues:

Debug Mode

Run with the dev profile for enhanced logging:

./gradlew bootRun --args='--spring.profiles.active=dev'

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments