Bookservice MCP Server

Spring Boot MCP服务器示例

一个Spring Boot应用程序，演示了具有书籍和作者管理功能的模型上下文协议（MCP）服务器实现。此应用程序可以在两种模式下运行：

1. Web应用程序模式：传统REST API服务器
2. MCP服务器模式：用于AI工具集成的模型上下文协议服务器

先决条件

• Java 17 或更高
• Maven 3.6+ 为了建设这个项目
• MCP检查员 （可选，用于验证和测试）

项目结构

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

编译说明

1.清理和编译

mvn clean compile

2.打包应用程序

mvn clean package

这将在以下位置创建一个可执行JAR文件 target/book-service-1.0.0.jar.

3.跳过测试（如果需要）

mvn clean package -DskipTests

启动应用程序

Web应用程序模式（默认）

从具有REST端点的传统Spring Boot web应用程序开始：

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

web应用程序将在以下网址提供：

• 基本URL: http://localhost:8080
• API终点：http://localhost:8080/api/books ，http://localhost:8080/api/authors
• Swagger用户界面: http://localhost:8080/swagger-ui.html

MCP服务器模式

从用于AI工具集成的MCP服务器开始：

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

MCP服务器将：

• 在stdin上监听JSON-RPC 2.0请求
• 在stdout上使用JSON-RPC 2.0响应进行响应
• 将消息记录到stderr

MCP服务器验证

使用内置测试脚本

运行提供的测试脚本以验证基本MCP功能：

chmod +x test_mcp.sh
./test_mcp.sh

此脚本测试：

• 服务器初始化
• 工具列表
• 工具执行（get_all_books）

使用JSON-RPC请求进行手动测试

1.初始化MCP服务器

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

2.列出可用工具

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

3.调用工具（获取所有书籍）

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.调用工具（按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

使用MCP检查器

如果您安装了MCP检查器，则可以使用它来验证MCP服务器并与之交互：

1.安装MCP检查器（如果尚未安装）

npm install -g @modelcontextprotocol/inspector

2.创建MCP配置

创建配置文件 mcp-config.json:

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

3.启动MCP检查器

mcp-inspector --config mcp-config.json

4.访问检查器UI

打开浏览器并导航到检查员提供的URL（通常http://localhost:5173).

可用的MCP工具

MCP服务器提供以下工具：

图书管理工具

• 获取所有书籍：检索所有书籍
• get_book_by_id：按ID获取特定书籍
• 创建_书籍：创建新书
• update_book：更新现有书籍
• 删除_书籍：按ID删除书籍

作者管理工具

• 获取所有作者：检索所有作者
• 获取作者id：按ID获取特定作者
• 创建者_作者：创建新作者
• update_author：更新现有作者
• 删除作者：按ID删除作者

示例用法

样本簿数据

该应用程序预装了示例书：

• F.斯科特·菲茨杰拉德的《了不起的盖茨比》
• 《杀死一只知更鸟》哈珀·李
• 乔治·奥威尔1984

通过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

故障排除

常见问题

1. 端口已在使用中：如果在web模式下运行，请确保端口8080可用
2. Java版本：确保您使用的是Java 17或更高版本
3. Maven构建失败：运行 mvn clean 建造前
4. MCP服务器没有响应：检查stderr输出是否有错误消息

调试

通过设置日志记录级别启用调试日志记录：

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

发展

以开发模式运行

mvn spring-boot:run

在开发模式下运行MCP服务器

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

许可证

本项目作为教育目的的示例提供。