hasanmk52/mcp-demo

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 21
• Maven 3.8+
• Spring Boot 3.4.4
• Spring AI 1.0.0-RC1

Dependencies

The project relies on the following key dependencies:

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

  <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-mcp-server</artifactId>
  </dependency>
  

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
   • McpDemoApplication.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=hasan-spring-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
• dv_search_courses: Searches for courses containing a keyword

MCP Tool Annotations

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

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:

{
  "hasan-spring-mcp": {
    "command": "/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/bin/java",
    "args": [
      "-jar",
      "/Users/hasankagalwala/learn/mcp-demo/target/mcp-demo-0.0.1-SNAPSHOT.jar"
    ]
  }
}

This configuration:

• Creates a tool named "hasan-spring-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.