# spring-ai-apps

**Repository Path**: yangshangwei/spring-ai-apps

## Basic Information

- **Project Name**: spring-ai-apps
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-19
- **Last Updated**: 2025-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI 应用项目 [![Twitter](https://img.shields.io/twitter/follow/piotr_minkowski.svg?style=social&logo=twitter&label=Follow%20Me)](https://twitter.com/piotr_minkowski)

[![CircleCI](https://circleci.com/gh/piomin/spring-ai-showcase.svg?style=svg)](https://circleci.com/gh/piomin/spring-ai-showcase)

[![SonarCloud](https://sonarcloud.io/images/project_badges/sonarcloud-black.svg)](https://sonarcloud.io/dashboard?id=piomin_spring-ai-showcase)
[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=piomin_spring-ai-showcase&metric=bugs)](https://sonarcloud.io/dashboard?id=piomin_spring-ai-showcase)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=piomin_spring-ai-showcase&metric=coverage)](https://sonarcloud.io/dashboard?id=piomin_spring-ai-showcase)
[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=piomin_spring-ai-showcase&metric=ncloc)](https://sonarcloud.io/dashboard?id=piomin_spring-ai-showcase)

本项目演示了在 Spring Boot 应用中集成 AI 能力，使用 [Spring AI](https://github.com/spring-projects/spring-ai) 框架。它展示了使用多个微服务暴露 AI 工具和提示的模型上下文协议（MCP）实现。

## 目录

- [架构](#架构)
- [模块](#模块)
  - [人员 MCP 服务](#人员-mcp-服务)
  - [账户 MCP 服务](#账户-mcp-服务)
  - [示例客户端](#示例客户端)
- [运行应用](#运行应用)
- [示例](#示例)
- [文章](#文章)

## 架构

### MCP 客户端/服务端

示例位于 `spring-ai-mcp` 目录中。下图展示了架构。

<img src="https://i0.wp.com/piotrminkowski.com/wp-content/uploads/2025/03/Screenshot-2025-03-16-at-12.24.46.png?w=1392&ssl=1" title="Architecture"><br/>

该架构由三个主要组件组成：
1. **人员 MCP 服务** - 暴露处理人员数据的工具
2. **账户 MCP 服务** - 暴露处理账户数据的工具
3. **示例客户端** - 使用服务并演示 AI 集成

## 模块

### 人员 MCP 服务

该服务暴露处理人员数据的工具，提供以下功能：
- 根据 ID 查找人员
- 根据国籍查找人员
- 使用提示按国籍统计人员数量

该服务实现了 MCP 服务端规范，并将这些功能作为 AI 工具暴露，供其他服务使用。

### 账户 MCP 服务

该服务暴露处理账户数据的工具，提供以下功能：
- 根据人员 ID 查找账户

与人员服务类似，它实现了 MCP 服务端规范，并将这些功能作为 AI 工具暴露。

### 示例客户端

该服务演示如何使用 MCP 服务，包括：
- 与 Spring AI 的聊天客户端集成
- 调用工具的示例
- 使用来自 MCP 服务的提示示例
- 用于测试集成的 REST 端点

## 运行应用

您可以始终使用 Spring Maven 插件支持在本地运行所有应用：
```shell
mvn spring-boot:run
```

有时，您需要将应用连接到 AI 模型。可以是 OpenAI 或您喜欢的其他模型。运行应用前，您应该导出 API 令牌，如下所示：
```shell
export SPRING_AI_OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
```

要运行完整系统，您需要启动所有三个服务：
1. 启动人员 MCP 服务
2. 启动账户 MCP 服务
3. 启动示例客户端

## 示例

启动服务后，您可以使用示例客户端中的以下端点测试集成：

- `GET /persons/nationality/{nationality}` - 按国籍查找人员
- `GET /persons/count-by-nationality/{nationality}` - 使用直接提示按国籍统计人员
- `GET /persons/count-by-nationality-from-client/{nationality}` - 使用 MCP 提示按国籍统计人员

## 文章

1. 开始使用 Spring AI **MCP** 概念。实现客户端和服务端应用，向其他服务暴露 `@Tools` 和 `Prompts`。示例在 [master](https://github.com/piomin/spring-ai-showcase/tree/master) 分支中。详细指南请参见以下文章：[在 Spring AI 中使用模型上下文协议（MCP）](https://piotrminkowski.com/2025/03/17/using-model-context-protocol-mcp-with-spring-ai/)