victorysatish05/bookservice-mcp-server

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 to the URL provided by the inspector (typically http://localhost:5173).

Available MCP Tools

The MCP server provides the following tools:

Book Management Tools

• get_all_books: Retrieve all books
• get_book_by_id: Get a specific book by ID
• create_book: Create a new book
• update_book: Update an existing book
• delete_book: Delete a book by ID

Author Management Tools

• get_all_authors: Retrieve all authors
• get_author_by_id: Get a specific author by ID
• create_author: Create a new author
• update_author: Update an existing author
• delete_author: Delete an author by ID

Example Usage

Sample Book Data

The application comes pre-loaded with sample books:

• The Great Gatsby by F. Scott Fitzgerald
• To Kill a Mockingbird by Harper Lee
• 1984 by George Orwell

Creating a New Book via MCP

echo '{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "create_book", "arguments": {"title": "Brave New World", "author": "Aldous Huxley", "isbn": "978-0-06-085052-4", "publishedYear": 1932}}}' | java -jar target/book-service-1.0.0.jar --mcp

Troubleshooting

Common Issues

1. Port Already in Use: If running in web mode, ensure port 8080 is available
2. Java Version: Ensure you're using Java 17 or higher
3. Maven Build Fails: Run mvn clean before building
4. MCP Server Not Responding: Check stderr output for error messages

Debugging

Enable debug logging by setting the logging level:

java -jar target/book-service-1.0.0.jar --mcp --logging.level.com.example.bookservice=DEBUG

Development

Running in Development Mode

mvn spring-boot:run

Running MCP Server in Development Mode

mvn spring-boot:run -Dspring-boot.run.arguments="--mcp"

License

This project is provided as an example for educational purposes.