Spring AI MCP Server for Course Information

Overview

This repository contains a Spring Boot application that implements the Model Control Protocol (MCP) server for providing course information. The application creates a lightweight server that can expose course data through the Spring AI MCP framework, allowing AI models to interact with your custom data services using standardized tooling.

The server exposes two main tools:

• A tool to retrieve all available courses
• A tool to search for specific courses by title

This implementation serves as an excellent starting point for creating your own Model Control Protocol servers or for integrating external data sources with AI models through Spring AI.

Project Requirements

• Java 24
• Maven 3.8+
• Spring Boot 3.4.4
• Spring AI 1.0.0-M6

Dependencies

The project relies on the following key dependencies:

• Spring AI MCP Server: Provides the foundation for creating MCP-compatible servers

org.springframework.ai
      spring-ai-mcp-server-spring-boot-starter

• Spring Boot Test: For testing the application

org.springframework.boot
      spring-boot-starter-test
      test

Getting Started

Prerequisites

Before running the application, make sure you have:

• Java 24 installed on your system
• Maven installed for dependency management
• Basic understanding of Spring Boot applications

Setting Up the Project

1. Review the project structure to understand the components:

• Course.java: A simple record representing course data
• CourseService.java: Service with MCP tool annotations
• CoursesApplication.java: Main application class with tool registration
• application.properties: Configuration for the MCP server

2. The application is configured to run as a non-web application using STDIO transport for MCP communication:

spring.main.web-application-type=none
   spring.ai.mcp.server.name=dan-vega-mcp
   spring.ai.mcp.server.version=0.0.1
   
   # These settings are critical for STDIO transport
   spring.main.banner-mode=off
   logging.pattern.console=

How to Run the Application

Running the application is straightforward with Maven:

mvn spring-boot:run

The application will start as a Model Control Protocol server accessible via standard input/output. It doesn't open any network ports or provide a web interface, as indicated by the spring.main.web-application-type=none configuration.

When running, the server registers two tools with the MCP:

• dv_get_courses: Returns all available courses
• dv_get_course: Returns a specific course by title

Understanding the Code

Defining Data Models

The application uses a simple record to represent course data:

public record Course(String title, String url) {
}

This immutable data structure provides a clean way to represent course information with title and URL attributes.

Implementing Tool Functions

The CourseService class demonstrates how to create MCP tools using the @Tool annotation:

@Service
public class CourseService {
    private List courses = new ArrayList<>();

    @Tool(name = "dv_get_courses", description = "Get a list of courses from Dan Vega")
    public List getCourses() {
        return courses;
    }

    @Tool(name = "dv_get_course", description = "Get a single courses from Dan Vega by title")
    public Course getCourse(String title) {
        return courses.stream()
                .filter(course -> course.title().equals(title))
                .findFirst()
                .orElse(null);
    }

    @PostConstruct
    public void init() {
        courses.addAll(List.of(
                new Course("Building Web Applications with Spring Boot (FreeCodeCamp)", 
                          "https://youtu.be/31KTdfRH6nY"),
                new Course("Spring Boot Tutorial for Beginners - 2023 Crash Course using Spring Boot 3",
                          "https://youtu.be/UgX5lgv4uVM")
        ));
    }
}

The @Tool annotation transforms regular methods into MCP-compatible tools with:

• A unique name for identification
• A description that helps AI models understand the tool's purpose

Registering Tools with MCP

In the main application class, tools are registered with the MCP framework:

@SpringBootApplication
public class CoursesApplication {

    public static void main(String[] args) {
        SpringApplication.run(CoursesApplication.class, args);
    }

    @Bean
    public List danTools(CourseService courseService) {
        return List.of(ToolCallbacks.from(courseService));
    }
}

The ToolCallbacks.from() method scans the service class for @Tool annotations and registers them with the MCP framework.

Extending the Project

You can extend this project in several ways:

1. Add more courses: Modify the init() method in CourseService to include additional courses.

2. Create new tool functions: Add more methods with the @Tool annotation to expose additional functionality.

3. Implement database storage: Replace the in-memory list with a database connection to store course information persistently.

4. Add search capabilities: Implement more advanced search functions beyond exact title matching.

Example of adding a search function:

@Tool(name = "dv_search_courses", description = "Search courses containing a keyword")
public List searchCourses(String keyword) {
    return courses.stream()
            .filter(course -> course.title().toLowerCase().contains(keyword.toLowerCase()))
            .collect(Collectors.toList());
}

Using the MCP Server with AI Models

To utilize this MCP server with AI models:

1. Ensure your AI framework supports the Model Control Protocol

2. Connect the AI model to the MCP server using STDIO transport

3. The AI model can then invoke the exposed tools:

• Request a list of all courses
• Retrieve details about a specific course by title

This allows AI models to access real-time course information and provide it in responses to user queries.

Configuration for Claude Desktop Client

To use this MCP server with the Claude Desktop client, you need to add configuration to tell Claude where to find the server. Add the following configuration to your Claude Desktop setup:

{
  "dan-vega-mcp": {
    "command": "/Users/vega/.sdkman/candidates/java/current/bin/java",
    "args": [
      "-jar",
      "/Users/vega/Downloads/courses/target/courses-0.0.1-SNAPSHOT.jar"
    ]
  }
}

This configuration:

• Creates a tool named "dan-vega-mcp" in Claude Desktop
• Specifies the path to your Java executable
• Provides arguments to run the compiled JAR file

Make sure to adjust the paths to match your specific environment:

• Update the Java path to match your installation
• Update the JAR file path to where your compiled application is located

Conclusion

This Spring AI MCP Server provides a clean, extensible framework for exposing course data through the Model Control Protocol. By following the Spring AI conventions and leveraging the tool annotation system, you can create powerful integrations between AI models and your data services.

The project demonstrates how to structure your code for MCP compatibility while maintaining good software design practices. With this foundation, you can build more complex data providers that enhance AI capabilities with access to custom, domain-specific information.

For more information about Spring AI and the Model Control Protocol, refer to the official documentation.