星战科技xingzhan.cloud
返回市场
MCP服务器

MCP服务器

作者：davidchanit4 星标更新：2025-11-11
安装使用来源：spider==github.com

项目介绍

Spring AI MCP Server

一个使用Spring AI框架并自定义HTTP传输实现的Model Context Protocol (MCP)服务器。该服务器提供了数学计算和游戏工具，可通过HTTP上的JSON-RPC访问。

功能

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

快速开始

先决条件

  • Java 17或更高版本
  • Maven 3.6+
  • Cursor 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端点：

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

# 测试计算工具
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服务器名称
      version: 0.0.1   # 服务器版本

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

Cursor IDE配置

在你的Cursor MCP配置文件（~/.cursor/mcp.json）中添加以下内容：

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

可用工具

计算器工具（CalculatorService）

  • calculate：执行基本数学表达式
  • add：加两个数
  • subtract：减两个数
  • multiply：乘两个数
  • divide：除两个数

游戏工具（GameService）

  • rockPaperScissors：玩石头剪刀布游戏 - 随机返回三个选项之一
  • playRockPaperScissors：与计算机玩石头剪刀布游戏 - 选择你的动作
  • getRandomChoice：从石头剪刀布中获取随机选择

添加新工具

  1. 创建一个新的带有@Service注解的服务类
  2. 在方法上添加@Tool注解
  3. 在参数上添加@ToolParam注解

示例：

@Service
public class MyToolsService {

    @Tool(description = "工具描述")
    public String myTool(@ToolParam(description = "参数描述") String parameter) {
        // 工具实现
        return "结果: " + parameter;
    }
}

项目结构

src/main/java/com/example/mcpserver/
├── McpServerApplication.java          # 主应用类
├── controller/
│   └── McpController.java            # 自定义MCP HTTP控制器
├── service/
│   ├── CalculatorService.java        # 计算器工具服务
│   └── GameService.java              # 游戏工具服务
└── resources/
    └── application.yml               # 应用配置

传输方法

此项目支持多种传输方法：

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

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

2. SSE传输（框架提供）

  • 端点：由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>

故障排除

常见问题

  1. 端口已被占用：更改application.yml中的端口
  2. 工具未出现：确保服务类有@Service注解
  3. API无响应：检查服务器是否在正确端口运行
  4. Cursor连接问题：验证~/.cursor/mcp.json中的MCP配置

日志

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

开发

为开发构建

mvn clean compile

运行测试

mvn test

Docker支持

构建Docker镜像：

# 先构建JAR
mvn clean package -DskipTests

# 构建Docker镜像
docker build -t mcp-server .

使用Docker运行：

# 使用Docker运行
docker run -p 8090:8090 mcp-server

# 或使用docker-compose
docker-compose up -d

测试Docker容器：

# 测试POST端点（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": {}}'

# 测试GET端点（SSE/可流式HTTP）
curl -X GET http://localhost:8090/api/v1/mpc \
  -H "Accept: text/event-stream"

Web测试客户端

有一个基于Web的测试客户端可用：

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

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

对于生产环境： 客户端会自动检测服务器URL，因此它既可以在本地工作也可以在Heroku上工作：

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

CI/CD测试

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

# 将脚本设置为可执行
chmod +x ci-test.sh

# 运行测试
./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：

# 将脚本设置为可执行
chmod +x deploy-heroku.sh

# 部署到Heroku
./deploy-heroku.sh

或者手动：

# 构建应用程序
mvn clean package -DskipTests

# 创建Heroku应用（如果不存在）
heroku create

# 设置环境变量
heroku config:set SPRING_PROFILES_ACTIVE=prod

# 部署
git push heroku main

Docker

使用Docker构建和运行：

# 先构建JAR
mvn clean package -DskipTests

# 构建Docker镜像
docker build -t mcp-server .

# 使用Docker运行
docker run -p 8090:8090 mcp-server

# 或使用docker-compose
docker-compose up -d

许可证

本项目根据MIT许可证发布 - 查看LICENSE文件了解详情。 </中文翻译>