Spring Boot MCP Server Example

A Spring Boot application that demonstrates Model Context Protocol (MCP) server implementation with book and author management functionality. This application can run in two modes:

1. Web Application Mode: Traditional REST API server
2. MCP Server Mode: Model Context Protocol server for AI tool integration

Prerequisites

• Java 17 or higher
• Maven 3.6+ for building the project
• MCP Inspector (optional, for validation and testing)

Project Structure

book-service/
├── src/main/java/com/example/bookservice/
│   ├── BookServiceApplication.java          # Main application class
│   ├── controller/
│   │   ├── BookController.java              # REST endpoints for books
│   │   └── AuthorController.java            # REST endpoints for authors
│   ├── mcp/
│   │   ├── McpServer.java                   # MCP server implementation
│   │   └── McpTool.java                     # MCP tool definitions
│   └── model/
│       ├── Book.java                        # Book entity
│       └── Author.java                      # Author entity
├── pom.xml                                  # Maven configuration
├── test_mcp.sh                             # MCP server test script
└── test_mcp_simple.json                    # Sample MCP request

Compilation Instructions

1. Clean and Compile

mvn clean compile

2. Package the Application

mvn clean package

This will create an executable JAR file at target/book-service-1.0.0.jar.

3. Skip Tests (if needed)

mvn clean package -DskipTests

Starting the Application

Web Application Mode (Default)

Start as a traditional Spring Boot web application with REST endpoints:

java -jar target/book-service-1.0.0.jar

The web application will be available at:

• Base URL: http://localhost:8080
• API Endpoints: http://localhost:8080/api/books, http://localhost:8080/api/authors
• Swagger UI: http://localhost:8080/swagger-ui.html

MCP Server Mode

Start as an MCP server for AI tool integration:

java -jar target/book-service-1.0.0.jar --mcp

The MCP server will:

• Listen for JSON-RPC 2.0 requests on stdin
• Respond with JSON-RPC 2.0 responses on stdout
• Log messages to stderr

MCP Server Validation

Using the Built-in Test Script

Run the provided test script to validate basic MCP functionality:

chmod +x test_mcp.sh
./test_mcp.sh

This script tests:

• Server initialization
• Tools listing
• Tool execution (get_all_books)

Manual Testing with JSON-RPC Requests

1. Initialize the MCP Server

echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}' | java -jar target/book-service-1.0.0.jar --mcp

2. List Available Tools

echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | java -jar target/book-service-1.0.0.jar --mcp

3. Call a Tool (Get All Books)

echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_all_books", "arguments": {}}}' | java -jar target/book-service-1.0.0.jar --mcp

4. Call a Tool (Get Book by ID)

echo '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "get_book_by_id", "arguments": {"id": "1"}}}' | java -jar target/book-service-1.0.0.jar --mcp

Using MCP Inspector

If you have the MCP Inspector installed, you can use it to validate and interact with the MCP server:

1. Install MCP Inspector (if not already installed)

npm install -g @modelcontextprotocol/inspector

2. Create MCP Configuration

Create a configuration file mcp-config.json:

{
  "mcpServers": {
    "book-service": {
      "command": "java",
      "args": ["-jar", "target/book-service-1.0.0.jar", "--mcp"],
      "env": {}
    }
  }
}

3. Start MCP Inspector

mcp-inspector --config mcp-config.json

4. Access Inspector UI

Open your browser and navigate

... View full README on GitHub