# scope_ai

**Repository Path**: zhangxiaopengjy/scope_ai

## Basic Information

- **Project Name**: scope_ai
- **Description**: 基于 Spring Boot 3 + Spring AI 1.0 构建的 AI 服务脚手架，内置 MCP Server / MCP Client 双端支持，可快速对接大模型并将业务能力以 MCP 工具形式暴露给 AI Agent。
- **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

基于 Spring Boot 3 + Spring AI 1.0 构建的 AI 服务脚手架，内置 MCP Server / MCP Client 双端支持，可快速对接大模型并将业务能力以 MCP 工具形式暴露给 AI Agent。

## 技术栈

| 组件 | 版本 |
|------|------|
| Java | 17 |
| Spring Boot | 3.3.6 |
| Spring AI | 1.0.0 |
| MyBatis-Plus | 3.5.5 |
| MySQL | 8.x |
| Redis | 6.x+ |
| Knife4j (OpenAPI 3) | 4.4.0 |

## 项目结构

```
src/main/java/com/scope/ai
├── common/        # 统一响应 R<T>、BizException、PageQuery/PageVO
├── config/        # GlobalExceptionHandler、MybatisPlusConfig、Knife4jConfig
├── controller/    # REST 控制器（@Tag / @Operation 注解文档）
├── mcp/
│   ├── McpServerConfig.java   # MCP 工具注册配置
│   └── tool/
│       └── DemoTools.java     # @Tool 工具示例（时间、用户、订单）
├── service/       # 业务逻辑（待扩展）
├── mapper/        # MyBatis-Plus Mapper 接口（待扩展）
└── entity/        # 数据库实体（待扩展）
```

## 快速开始

### 1. 环境准备

- JDK 17+
- Maven 3.8+
- MySQL 8.x（创建数据库 `scope_ai`）
- Redis 6.x+

### 2. 修改开发配置

编辑 `src/main/resources/application-dev.properties`，按实际环境修改数据源和 Redis 地址：

```properties
spring.datasource.url=jdbc:mysql://localhost:3306/scope_ai?...
spring.datasource.username=root
spring.datasource.password=123456

spring.data.redis.host=localhost
spring.data.redis.port=6379
```

### 3. 构建与启动

```bash
# 构建（跳过测试）
mvn clean package -DskipTests

# 以 dev 环境启动
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

### 4. 验证服务

| 地址 | 说明 |
|------|------|
| `http://localhost:8080/scope-ai/health` | 健康检查 |
| `http://localhost:8080/scope-ai/doc.html` | Knife4j API 文档 |
| `http://localhost:8080/scope-ai/sse` | MCP Server SSE 订阅端点 |

## MCP Server 使用

本服务已启用 MCP Server（WebMVC SSE 模式），AI Client（如 Claude Desktop、自定义 MCP Client）可通过以下地址连接：

```
SSE 端点:     http://localhost:8080/scope-ai/sse
消息端点:     http://localhost:8080/scope-ai/mcp/messages
Server 名称:  scope-ai-mcp-server
```

### 已注册工具

| 工具名 | 描述 |
|--------|------|
| `getCurrentTime` | 获取服务器当前日期和时间 |
| `searchUser` | 根据关键词搜索用户列表 |
| `calculateAge` | 根据出生日期计算周岁年龄 |
| `queryOrders` | 按状态和分页查询订单列表 |

### 新增工具

1. 在 `mcp/tool/` 下新建工具类，添加 `@Component` 和 `@Tool` 注解：

```java
@Component
public class MyTools {

    @Tool(name = "myTool", description = "工具功能描述，LLM 依据此决定何时调用")
    public String myTool(@ToolParam(description = "参数说明") String param) {
        return "结果";
    }
}
```

2. 在 `McpServerConfig` 中注册：

```java
@Bean
public ToolCallbackProvider myToolCallbackProvider(MyTools myTools) {
    return MethodToolCallbackProvider.builder().toolObjects(myTools).build();
}
```

## MCP Client 配置（可选）

如需连接外部 MCP Server，在 `application-dev.properties` 中取消注释并填写地址：

```properties
spring.ai.mcp.client.sse.connections.external-server.url=http://other-server/sse
```

## 开发规范

- **统一响应**：所有接口返回 `R<T>`，成功用 `R.ok(data)`，业务异常抛 `BizException`。
- **分页**：入参用 `PageQuery`，出参用 `PageVO<T>`。
- **多环境**：公共配置放 `application.properties`，环境差异配置放 `application-dev.properties` / `application-prod.properties`，通过 `spring.profiles.active` 切换。

## 测试

```bash
# 运行全部测试
mvn test

# 运行单个测试类
mvn test -Dtest=ScopeAiApplicationTests
```

## 参与贡献

1. Fork 本仓库
2. 新建 `feature/xxx` 分支
3. 提交代码
4. 新建 Pull Request