# Spring AI MCP Test Agent **Repository Path**: onlyonebody/spring-ai-mcp-test-agent ## Basic Information - **Project Name**: Spring AI MCP Test Agent - **Description**: Spring AI MCP Agent 是一个基于Spring AI的智能代理系统,采用MCP(Model Context Protocol)协议,专为集成测试现有系统的RESTful、WebService和Dubbo接口而设计。该项目旨在简化接口测试流程,提高测试效率,并通过AI能力实现智能化的接口组合调用。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-09-18 - **Last Updated**: 2025-09-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: Spring, SpringAI, MCP ## README # Spring AI MCP Agent 基于Spring AI的MCP(Model Context Protocol)智能代理系统,用于集成测试现有系统的RESTful、WebService和Dubbo接口。 ## 项目概述 本项目实现了一个集成测试Agent,主要功能包括: 1. **MCP Server**:将现有的RESTful、WebService、Dubbo接口通过MCP协议开放 2. **MCP Client**:作为集成测试Agent,通过SSE方式调用MCP接口 3. **AI集成**:集成OpenAI,通过提示词实现智能的接口组合调用逻辑 4. **RESTful API**:对外提供RESTful接口供外部系统调用 ## 技术栈 - **Java**: JDK 17 - **框架**: Spring Boot 3.2.1 - **AI框架**: Spring AI 1.0.0 - **构建工具**: Maven 3.6+ - **AI模型**: OpenAI GPT-3.5-turbo - **通信协议**: MCP (Model Context Protocol) via SSE - **日志**: Logback - **数据格式**: JSON ## 项目结构 ``` spring-ai-mcp-agent/ ├── mcp-server/ # MCP服务端模块 │ ├── src/main/java/ │ │ └── com/example/mcpserver/ │ └── src/main/resources/ │ └── application.yml ├── mcp-client/ # MCP客户端模块 │ ├── src/main/java/ │ │ └── com/example/mcpclient/ │ └── src/main/resources/ │ └── application.yml ├── docs/ # 项目文档 │ └── spring-ai-mcp-agent/ ├── .env.example # 环境变量示例 ├── pom.xml # 父项目配置 └── README.md # 项目说明 ``` ## 快速开始 ### 1. 环境准备 确保您的开发环境满足以下要求: - JDK 17 或更高版本 - Maven 3.6 或更高版本 - 网络连接(用于访问OpenAI API) ### 2. 配置环境变量 复制环境变量示例文件并配置: ```bash cp .env.example .env ``` 编辑 `.env` 文件,至少需要配置以下必要参数: ```properties # OpenAI API密钥(必填) OPENAI_API_KEY=sk-your-openai-api-key-here # 其他配置使用默认值即可 ``` ### 3. 编译项目 ```bash # 在项目根目录执行 mvn clean compile ``` ### 4. 启动服务 #### 启动MCP Server(端口9999) ```bash cd mcp-server mvn spring-boot:run ``` #### 启动MCP Client(端口8080) ```bash # 新开一个终端窗口 cd mcp-client mvn spring-boot:run ``` ### 5. 验证服务 #### 检查服务健康状态 ```bash # 检查MCP Server curl http://localhost:9999/actuator/health # 检查MCP Client curl http://localhost:8080/actuator/health ``` #### 测试集成API ```bash # 调用集成测试API curl -X POST http://localhost:8080/api/integration-test \ -H "Content-Type: application/json" \ -d '{ "prompt": "获取用户信息并查询相关订单", "context": { "userId": "12345" } }' ``` ### 6. 功能测试 #### MCP配置 ```bash { "mcpServers": { "Spring AI MCP": { "url": "http://127.0.0.1:9999/sse" } } } ``` #### 访问界面 http://localhost:8080/chat.html ![输入图片说明](docs/Spring%20AI%20MCP.jpg) ## 核心功能 ### MCP Server功能 - **接口适配器**:支持RESTful、WebService、Dubbo三种协议 - **工具注册**:使用`@Tool`注解将接口注册为MCP工具 - **Demo接口**:提供每种协议的示例实现 - **错误处理**:完善的异常处理和重试机制 ### MCP Client功能 - **RESTful API**:对外提供HTTP接口 - **AI集成**:集成OpenAI进行智能决策 - **MCP通信**:通过SSE方式与MCP Server通信 - **提示词处理**:根据用户输入生成合适的提示词 ### 支持的接口类型 1. **RESTful接口**:HTTP/HTTPS协议的REST API 2. **WebService接口**:基于SOAP协议的Web服务 3. **Dubbo接口**:Apache Dubbo RPC服务 ## API文档 ### 集成测试API **端点**: `POST /api/test/combo/stream` **请求体**: ```json { "testDescription": "用户的自然语言描述", "userId": "12345" } ``` ### 工具查询API **端点**: `GET /api/test/tools` **响应体**: ```json { "success": true, "tools": [ { "name": "工具名称", "description": "工具描述", "parameters": {}, "protocol": "协议类型" } ] } ``` ## 配置说明 ### MCP Server配置 主要配置文件:`mcp-server/src/main/resources/application.yml` - **端口配置**:默认9999端口 - **MCP配置**:服务名称、版本、类型等 - **适配器配置**:各种协议的超时、重试等参数 - **Demo配置**:测试接口的地址和参数 ### MCP Client配置 主要配置文件:`mcp-client/src/main/resources/application.yml` - **端口配置**:默认8080端口 - **OpenAI配置**:API密钥、模型、参数等 - **MCP客户端配置**:连接地址、超时、重试等 - **Agent配置**:AI决策、提示词、工具调用等 ## 开发指南 ### 添加新的接口适配器 1. 在`mcp-server`模块中创建新的适配器类 2. 使用`@Tool`注解标记适配器方法 3. 在配置文件中添加相应的配置项 4. 创建对应的Demo实现 ### 自定义提示词 1. 在`mcp-client/src/main/resources/prompts/`目录下创建提示词文件 2. 在`PromptService`中添加新的提示词处理逻辑 3. 在配置文件中指定提示词模板路径 ### 扩展AI功能 1. 修改`AiDecisionService`添加新的决策逻辑 2. 调整OpenAI模型参数以优化效果 3. 添加新的工具调用策略 ## 故障排除 ### 常见问题 1. **OpenAI连接失败** - 检查API密钥是否正确 - 确认网络连接正常 - 验证API配额是否充足 2. **MCP连接失败** - 确认MCP Server已启动 - 检查端口是否被占用 - 验证防火墙设置 3. **编译失败** - 确认JDK版本为17或更高 - 检查Maven配置 - 清理并重新编译:`mvn clean compile` ### 日志查看 - **MCP Server日志**:`mcp-server/logs/mcp-server.log` - **MCP Client日志**:`mcp-client/logs/mcp-client.log` - **控制台日志**:启动时的实时日志输出 ## 贡献指南 1. Fork本项目 2. 创建特性分支:`git checkout -b feature/new-feature` 3. 提交更改:`git commit -am 'Add new feature'` 4. 推送分支:`git push origin feature/new-feature` 5. 创建Pull Request ## 许可证 本项目采用MIT许可证,详见LICENSE文件。 ## 联系方式 如有问题或建议,请通过以下方式联系: - 项目Issues:[Gitee Issues](https://gitee.com/onlyonebody/spring-ai-mcp-test-agent/issues) - 邮箱:loveonlyonebody@vip.qq.com ## 更新日志 ### v1.0.0 (2025-09-01) - 初始版本发布 - 实现MCP Server和Client基础功能 - 支持RESTful、WebService、Dubbo接口适配 - 集成OpenAI AI决策功能 - 提供完整的Demo和文档