spring-ai

This MCP server is a Spring Boot starter designed to work with the SWAPI MCP ecosystem using Spring AI. It leverages Spring Boot 3.x and Spring AI to provide a modular, MVC-style server that can be extended with MCP tools and prompts. You can run the server inside a Docker container and interact with it through the MCP protocol as implemented by the Spring MCP Server layer (Stdio/Webflux). To use it, start the Docker image, then connect via the MCP client protocol to invoke available tools, prompts, and converters implemented in the project. The server is organized around Spring components and annotations to expose MCP endpoints and enable easy customization and extension.

Once running, you can utilize the provided tools and prompts to perform SWAPI data access, conversions, or other utilities implemented in the various branches (e.g., completion, resources, and OAuth2 security). If you’re integrating security, you can explore the oauth2-secured branch, otherwise use the no-security branch which contains the core completion and resource tooling. The Spring AI integration provides capabilities to generate and transform SWAPI data, while the MCP Server framework handles request routing and response formatting in a reactive (WebFlux) pipeline.

Prerequisites:

• Docker installed and running on your machine
• Basic familiarity with MCP client connections

Steps:

1. Pull and run the Docker image for the Spring AI MCP server:

   docker pull krdk01/spring-ai-mcp-server docker run -it --rm krdk01/spring-ai-mcp-server

   This starts the MCP server in interactive mode. If you need to expose ports or mount volumes for configuration, adjust the docker run command accordingly (e.g., -p 8080:8080 or -v ./config:/app/config).

2. Verify the server is running:

   Check container logs for startup messages indicating MCP server readiness and available endpoints.

3. Connect with an MCP client:

   Use your MCP client to establish a stdio or WebFlux-based connection to the server as per MCP protocol. Send requests to the server-name (spring-ai) to list tools, prompts, and converters, and to execute available actions.

4. Optional: provide configuration overrides via environment variables or mounted config files if supported by the Docker image. Consult the repository branches (e.g., 01-yaml-settings-for-mcp-server) for YAML-based settings and additional configuration options.

Notes and tips:

• This MCP server is built as a Spring Boot starter with a focus on SWAPI integration and Spring AI tooling. If you need security features, refer to the 08-oauth2-server branch where OAuth2 is integrated.
• The 01-yaml-settings-for-mcp-server branch includes YAML-based settings and a Dockerfile for easier local deployment. If you require a YAML-driven configuration, switch to that branch.
• When running via Docker, ensure the image name matches the one used in your environment. If you publish your own image, update the mcp_config accordingly.
• If you encounter connectivity issues, verify the MCP protocol version compatibility between your client and this server, and check for any branch-specific changes to endpoints or tool definitions.
• For development, you can build locally with Maven/Gradle (depending on project setup) and run the Spring Boot app directly, but the provided Docker path is the recommended deployment method for MCP compatibility.