Spring AI MCP PoC

Spring AI MCP PoC

展示 Spring AI 框架、GitHub MCP（Model Context Protocol）服务和大模型集成的概念验证项目。

概述

本项目展示如何构建一个 AI 驱动的应用，该应用能够：

• 使用 Spring AI 处理自然语言提示词
• 通过 MCP（Model Context Protocol）与 GitHub 集成
• 利用 OpenAI 的 GPT 模型生成智能响应
• 通过函数调用提供 GitHub 专属功能

架构

User Request → Spring Boot API → Spring AI → OpenAI LLM
                     ↓
              GitHub MCP Server → GitHub API

功能

• Spring AI 集成：利用 Spring AI 框架进行大模型交互
• GitHub MCP 支持：通过 Model Context Protocol 连接 GitHub
• 函数调用：AI 可以根据用户提示词调用 GitHub 操作
• RESTful API：用于处理提示词的简洁 REST 接口
• 可配置：轻松配置不同环境
• 错误处理：完善的错误处理和日志记录

前置条件

• Java 17 或更高版本
• Gradle 8.6+（或使用随附的包装器）
• OpenAI API 密钥
• 正在运行的 GitHub MCP 服务（基本功能可选）

设置

1. 克隆仓库

git clone https://github.com/shesadri/spring_ai_mcp_poc.git
cd spring_ai_mcp_poc

2. 配置环境变量

创建 .env 文件或设置环境变量：

export OPENAI_API_KEY="your-openai-api-key"
export GITHUB_MCP_SERVER_URL="http://localhost:3000"  # Optional
export GITHUB_TOKEN="your-github-token"  # Optional for enhanced features

3. 配置应用属性

编辑 src/main/resources/application.yml 或使用环境变量：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:your-openai-api-key-here}
      
app:
  github:
    mcp:
      server:
        url: ${GITHUB_MCP_SERVER_URL:http://localhost:3000}

4. 构建并运行

# Build the project
./gradlew build

# Run the application
./gradlew bootRun

# Or run with specific profile
./gradlew bootRun --args='--spring.profiles.active=dev'

# Alternative: Use custom tasks
./gradlew runDev    # Development profile
./gradlew runProd   # Production profile

应用将在 http://localhost:8080 上启动

使用方法

健康检查

curl http://localhost:8080/api/v1/health

处理提示词

curl -X POST http://localhost:8080/api/v1/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Tell me about Spring AI framework",
    "enableMcpTools": true
  }'

GitHub 专属提示词

curl -X POST http://localhost:8080/api/v1/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Show me information about my GitHub repositories",
    "enableMcpTools": true
  }'

获取可用的 MCP 工具

curl http://localhost:8080/api/v1/mcp/tools

API 端点

方法	端点	描述
GET	/api/v1/health	健康检查
POST	/api/v1/prompt	处理 AI 提示词
GET	/api/v1/mcp/tools	获取可用的 MCP 工具

请求/响应格式

提示词请求

{
  "prompt": "Your question or instruction",
  "context": "Optional context",
  "enableMcpTools": true,
  "githubToken": "optional-github-token"
}

提示词响应

{
  "response": "AI generated response",
  "mcpData": {
    "repositories": [...],
    "status": "success"
  },
  "usedMcpTools": true,
  "timestamp": "2024-01-01T12:00:00",
  "status": "success",
  "model": "gpt-4"
}

配置

环境变量

• OPENAI_API_KEY：你的 OpenAI API 密钥（必填）
• GITHUB_MCP_SERVER_URL：你的 GitHub MCP 服务 URL（可选）
• GITHUB_TOKEN：GitHub 个人访问令牌（可选）
• PORT：服务端口（默认值：8080）

应用属性

请参阅 application.yml，了解详细配置选项，包括：

• AI 模型设置
• 服务配置
• CORS 设置
• 日志级别
• 管理端点

GitHub MCP 服务

本应用需要运行 GitHub MCP 服务，以增强 GitHub 功能。MCP 服务应提供：

• 仓库信息端点
• Issue 管理功能
• Pull Request 操作
• 代码搜索功能

如果没有可用的 MCP 服务，应用仍可运行，但 GitHub 集成功能有限。

开发

运行测试

./gradlew test

开发配置文件

./gradlew runDev
# or
./gradlew bootRun --args='--spring.profiles.active=dev'

面向生产环境构建

./gradlew clean build
java -jar build/libs/spring-ai-mcp-poc-1.0.0-SNAPSHOT.jar

Gradle 命令

# Build project
./gradlew build

# Run application
./gradlew bootRun

# Run tests
./gradlew test

# Clean build
./gradlew clean

# Generate Gradle wrapper (if needed)
gradle wrapper --gradle-version 8.6

# Check dependencies
./gradlew dependencies

# Build info
./gradlew tasks

项目结构

src/
├── main/
│   ├── java/com/example/springaimcp/
│   │   ├── SpringAiMcpApplication.java     # Main application class
│   │   ├── config/
│   │   │   └── SpringAiConfig.java         # Spring AI configuration
│   │   ├── controller/
│   │   │   └── PromptController.java       # REST API endpoints
│   │   ├── service/
│   │   │   ├── AiMcpService.java          # Main service orchestrating AI and MCP
│   │   │   └── mcp/
│   │   │       └── GitHubMcpClient.java   # GitHub MCP client
│   │   └── model/
│   │       ├── PromptRequest.java         # Request model
│   │       └── PromptResponse.java        # Response model
│   └── resources/
│       ├── application.yml                # Main configuration
│       └── application.properties         # Alternative configuration
└── test/
    └── java/
        └── ... # Test classes

# Gradle files
build.gradle                     # Gradle build script
settings.gradle                  # Gradle settings
gradle/
└── wrapper/
    ├── gradle-wrapper.properties    # Gradle wrapper config
    └── gradle-wrapper.jar          # Gradle wrapper JAR
gradlew                         # Gradle wrapper script (Unix)
gradlew.bat                     # Gradle wrapper script (Windows)

使用的技术

• Spring Boot 3.2.5：应用框架
• Spring AI 1.0.0-M1：AI 集成框架
• OpenAI GPT-4：大语言模型
• WebFlux：用于 MCP 通信的响应式 Web 客户端
• Jackson：JSON 处理
• Gradle 8.6：构建工具

贡献

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交 Pull Request

许可证

本项目采用 MIT 许可证。

故障排除

常见问题

1. OpenAI API 密钥问题

   • 确认 API 密钥有效且额度充足
   • 检查环境变量是否已正确设置

2. MCP 服务连接问题

   • 确认 MCP 服务正在运行
   • 检查服务 URL 配置
   • 检查网络连接

3. GitHub 集成问题

   • 确认 GitHub 令牌拥有适当的权限
   • 检查 MCP 服务的 GitHub 配置

4. Gradle 问题

   • 使用 ./gradlew --version 检查 Gradle 版本
   • 运行 ./gradlew clean build 清理并重新构建
   • 使用 java -version 检查 Java 版本

日志

查看应用程序日志以获取详细的错误信息：

# View logs in development
tail -f logs/spring-ai-mcp-poc.log

# Increase log level for debugging
export LOGGING_LEVEL_COM_EXAMPLE_SPRINGAIMCP=DEBUG

Gradle Wrapper

如果遇到 Gradle wrapper 问题：

# Regenerate wrapper files
gradle wrapper --gradle-version 8.6

# Make gradlew executable on Unix systems
chmod +x gradlew

支持

如有问题或疑问：

• 在此代码库中创建 issue
• 查看 Spring AI 文档
• 查看 OpenAI API 文档
• 查阅 Gradle 文档