使用说明

Spring AI MCP服务器

使用Spring AI框架和自定义HTTP传输的模型上下文协议（MCP）服务器实现。该服务器提供数学计算和游戏工具，可通过HTTP上的JSON-RPC访问。

特性

✅ 自定义HTTP MCP服务器：使用JSON-RPC通过HTTP实现MCP协议
✅ Spring AI框架集成：基于Spring AI MCP框架构建
✅ 工具自动发现：通过自动工具注册 @Tool 注释
✅ 多种运输支持：HTTP（自定义）+SSE（提供框架）
✅ 实时通信：支持HTTP和SSE传输方法
✅ 游标IDE集成：与Cursor的MCP客户端兼容

快速开始

先决条件

Java 17或更高版本
Maven 3.6+
游标IDE（用于测试MCP集成）

1.建设项目

mvn clean package -DskipTests

2.运行服务器

java -jar target/mcp-server-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod

服务器将在端口8090上启动。

3.测试API

测试MCP端点：

# Test ping
curl -X POST http://localhost:8090/api/v1/mpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping", "params": {}}'

# Test calculate tool
curl -X POST http://localhost:8090/api/v1/mpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "calculate", "arguments": {"expression": "22+2"}}}'

配置

服务器配置（application.yml）

server:
  port: 8090

spring:
  application:
    name: mcp-server

ai:
  mcp:
    server:
      name: mcp-server # MCP server name
      version: 0.0.1   # Server version

logging:
  level:
    org.springframework.ai: DEBUG
    com.example.mcpserver: DEBUG

光标IDE配置

将其添加到您的Cursor MCP配置文件中(~/.cursor/mcp.json):

{
  "mcpServers": {
    "spring-ai-mcp-server": {
      "command": "http",
      "args": {
        "url": "http://localhost:8090/api/v1/mpc"
      }
    }
  }
}

可用工具

计算器工具（计算器服务）

计算：执行基本数学表达式
添加：添加两个数字
减去：减去两个数字
乘：将两个数字相乘
分割：除以两个数字

游戏工具（GameService）

岩石剪刀：玩石头、布、剪刀-随机返回三个选项之一
playRockPaperScissors：在电脑前玩石头、纸、剪刀——你选择你的动作
getRandomChoice：从岩石、纸张、剪刀中随机选择

添加新工具

使用创建新的服务类 @Service 注释
添加 @Tool 方法注释
添加 @ToolParam 参数注释

例子：

@Service
public class MyToolsService {

    @Tool(description = "Tool description")
    public String myTool(@ToolParam(description = "Parameter description") String parameter) {
        // Tool implementation
        return "Result: " + parameter;
    }
}

项目结构

src/main/java/com/example/mcpserver/
├── McpServerApplication.java          # Main application class
├── controller/
│   └── McpController.java            # Custom MCP HTTP controller
├── service/
│   ├── CalculatorService.java        # Calculator tools service
│   └── GameService.java              # Game tools service
└── resources/
    └── application.yml               # Application configuration

运输方式

本项目支持多种运输方式：

1.HTTP传输（自定义实现）

端点: POST http://localhost:8090/api/v1/mpc
协议：基于HTTP的JSON-RPC
用法：直接HTTP请求，Cursor IDE集成
响应：即时JSON响应

2.上交所运输（提供框架）

端点：Spring AI框架自动提供
协议：服务器发送流媒体事件
用法：实时、持久的连接
响应：流媒体事件

依赖项

核心依赖关系（pom.xml）

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

存储库配置

<repositories>
    <repository>
        <id>spring-snapshots</id>
        <name>Spring Snapshots</name>
        <url>https://repo.spring.io/snapshot</url>
        <releases>
            <enabled>false</enabled>
        </releases>
    </repository>
    <repository>
        <name>Central Portal Snapshots</name>
        <id>central-portal-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

故障排除

常见问题

端口已在使用中：在中更改端口 application.yml
工具未出现：确保服务类具有 @Service 注释
API未响应：检查服务器是否在正确的端口上运行
游标连接问题：验证MCP配置 ~/.cursor/mcp.json

日志

该应用程序使用SLF4J日志记录。检查控制台输出以获取详细的日志信息。

发展

建设促进发展

mvn clean compile

运行测试

mvn test

Docker支持

构建Docker镜像：

# Build the JAR first
mvn clean package -DskipTests

# Build Docker image
docker build -t mcp-server .

使用Docker运行：

# Run with Docker
docker run -p 8090:8090 mcp-server

# Or run with docker-compose
docker-compose up -d

测试Docker容器：

# Test POST endpoint (JSON-RPC)
curl -X POST http://localhost:8090/api/v1/mpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping", "params": {}}'

# Test GET endpoint (SSE/Streamable HTTP)
curl -X GET http://localhost:8090/api/v1/mpc \
  -H "Accept: text/event-stream"

Web测试客户端

基于网络的测试客户端可在以下网址获得：

http://localhost:8090/mcp-client.html

该客户端提供了一个用户友好的界面来测试所有MCP端点和工具。

生产： 客户端会自动检测服务器URL，因此它既可以在本地运行，也可以在Heroku上运行：

https://your-app-name.herokuapp.com/mcp-client.html

CI/CD测试

对于CI/CD管道，请使用提供的测试脚本：

# Make script executable
chmod +x ci-test.sh

# Run the test
./ci-test.sh

或手动：

docker run -d --name mcp-test -p 8090:8090 mcp-server:latest
sleep 10
curl -f -X POST http://localhost:8090/api/v1/mpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping", "params": {}}' || exit 1
docker stop mcp-test
docker rm mcp-test

部署

Heroku

使用提供的脚本部署到Heroku：

# Make script executable
chmod +x deploy-heroku.sh

# Deploy to Heroku
./deploy-heroku.sh