# scope_ai_client

**Repository Path**: zhangxiaopengjy/scope_ai_client

## Basic Information

- **Project Name**: scope_ai_client
- **Description**: 基于 Spring Boot + Spring AI MCP Client 的 MCP 客户端示例项目，通过 SSE 协议连接 scope_ai MCP Server，演示远程工具调用。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# scope_ai_client

基于 Spring Boot + Spring AI MCP Client 的 MCP 客户端示例项目，通过 SSE 协议连接 `scope_ai` MCP Server，演示远程工具调用。

## 技术栈

| 组件 | 版本 |
|---|---|
| Java | 17 |
| Spring Boot | 3.3.5 |
| Spring AI | 1.0.0 |
| spring-ai-starter-mcp-client-webflux | 1.0.0（BOM 管理）|
| SpringDoc OpenAPI (Swagger UI) | 2.6.0 |

## 前置条件

- JDK 17+
- Maven 3.6+
- `scope_ai` MCP Server 已启动并可访问

## 配置

编辑 `src/main/resources/application.properties`，按实际环境修改以下参数：

```properties
server.port=8082

# scope_ai MCP Server 地址
spring.ai.mcp.client.sse.connections.scope-ai.url=http://10.20.200.205:8080
spring.ai.mcp.client.sse.connections.scope-ai.sse-endpoint=/scope-ai/sse
```

> **说明**：`url` 只保留 `scheme+host+port`，context path 前缀在 `sse-endpoint` 中指定，
> 避免 SDK 内部 `URI.resolve()` 丢弃路径的问题。

## 启动

```bash
# 指定 JDK 17（若系统 JAVA_HOME 已是 17 可省略前缀）
JAVA_HOME=/path/to/jdk-17 mvn spring-boot:run -DskipTests
```

启动后访问：
- Swagger UI：http://localhost:8082/swagger-ui.html
- OpenAPI JSON：http://localhost:8082/api-docs

## API 接口

所有接口前缀：`/mcp/demo`

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/tools` | 列出 MCP Server 注册的全部工具 |
| GET | `/current-time` | 获取服务器当前时间 |
| GET | `/search-user?keyword=` | 按关键词搜索用户 |
| GET | `/calculate-age?birthDate=` | 根据出生日期计算周岁（格式 `yyyy-MM-dd`）|
| GET | `/query-orders?status=&page=&size=` | 按状态分页查询订单（PENDING / PAID / CANCELLED）|

## 项目结构

```
src/main/java/com/scope/ai/client/
├── ScopeAiClientApplication.java   # 启动入口
├── config/
│   ├── McpClientConfig.java        # 手动构造 McpSyncClient Bean（SSE 连接）
│   └── SwaggerConfig.java          # SpringDoc 配置
├── controller/
│   └── McpDemoController.java      # REST 接口层
└── service/
    └── McpDemoService.java         # MCP 工具调用封装
```

## 注意事项

- Spring AI 自动配置 `McpClientAutoConfiguration` 和 `McpToolCallbackAutoConfiguration` 已被排除，
  由 `McpClientConfig` 手动管理连接生命周期（含 `@PreDestroy` 优雅关闭）。
- `spring-ai-starter-mcp-client-webflux` 版本须与 BOM 保持一致，不可单独升级，否则会引发
  `IllegalStateException: Error processing condition on McpToolCallbackAutoConfiguration`。