Ji Spring AI MCP Playground

春季AI MCP游乐场

一个生产就绪的Spring Boot应用程序，将Spring AI与模型上下文协议（MCP）服务器集成在一起，具有现代网络聊天界面、多提供商AI支持（Ollama/OpenAI）、安全凭据管理和自定义MCP工具的可扩展架构。

特性

• 🤖 多提供商AI支持：选择OpenAI和Ollama进行自然语言处理
• 🔌 MCP服务器集成：连接到内部和外部MCP服务器
• 🛠️ 自定义工具管理：创建和管理自定义MCP工具
• 💬 基于Web的聊天界面：用于与AI交互的现代、响应式UI
• 🔍 RAG支持：检索增强生成与文档索引
• 🔐 安全凭据管理：API密钥的加密存储
• 📊 工具发现：MCP工具的自动发现和注册

先决条件

• Java 17或更高版本
• Maven 3.6+
• PostgreSQL（用于向量存储-可选）
• Ollama（可选，如果使用Ollama供应商）

快速开始

1.克隆和构建

cd spring-ai-mcp-playground
mvn clean install

2.配置环境变量

创建一个 application-local.yml 或设置环境变量：

# OpenAI (optional)
export OPENAI_API_KEY=your-openai-api-key

# Ollama (optional, defaults to http://localhost:11434)
export OLLAMA_BASE_URL=http://localhost:11434
export OLLAMA_MODEL=llama3

# PostgreSQL for RAG (optional)
export PGVECTOR_HOST=localhost
export PGVECTOR_PORT=5432
export PGVECTOR_DB=vectordb
export PGVECTOR_USER=postgres
export PGVECTOR_PASSWORD=your-password

3.运行应用程序

mvn spring-boot:run

或者使用特定的配置文件：

mvn spring-boot:run -Dspring-boot.run.profiles=dev

4.访问Web界面

打开浏览器并导航到：

http://localhost:8080

项目结构

spring-ai-mcp-playground/
├── src/
│   ├── main/
│   │   ├── java/com/portfolio/springaimcp/
│   │   │   ├── client/          # MCP client wrapper and tool registry
│   │   │   ├── config/          # Configuration classes
│   │   │   ├── controller/      # REST controllers
│   │   │   ├── exception/       # Exception handling
│   │   │   ├── model/           # Data models
│   │   │   ├── mcp/server/      # MCP server implementations
│   │   │   └── service/         # Business logic services
│   │   └── resources/
│   │       ├── static/           # Frontend files (HTML, CSS, JS)
│   │       └── application.yml  # Application configuration
│   └── test/                    # Test files
├── rag-documents/               # Documents for RAG (create this directory)
├── pom.xml                      # Maven dependencies
└── README.md                    # This file

配置

MCP服务器

在中配置MCP服务器 application.yml:

mcp:
  servers:
    math:
      enabled: true
      type: INTERNAL
    rag:
      enabled: true
      type: INTERNAL
      documents-path: ./rag-documents
    browser-token:
      enabled: true
      type: INTERNAL

AI提供商

开放人工智能

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4-turbo-preview
          temperature: 0.7

奥拉玛

spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: llama3.2
          temperature: 0.7

API终点

聊天API

• POST /api/chat -发送聊天消息
• GET /api/chat/history/{conversationId} -获取对话历史记录
• DELETE /api/chat/history/{conversationId} -清除对话历史记录

MCP API

• GET /api/mcp/servers -列出所有已注册的MCP服务器
• GET /api/mcp/tools -列出所有可用工具
• GET /api/mcp/tools/{serverName} -获取特定服务器的工具
• POST /api/mcp/servers -添加自定义MCP服务器
• DELETE /api/mcp/servers/{serverName} -删除MCP服务器

添加自定义MCP服务器

内部服务器

1. 创建一个实现MCP服务器接口的新服务器类：

@Component
public class MyCustomServer {
    public List getAvailableTools() {
        // Return your tools
    }
    
    public Object executeTool(String toolName, Map parameters) {
        // Implement tool execution
    }
}

1. 在中注册 McpServerManager:

if (isServerEnabled("my-custom")) {
    registerServer("my-custom", myCustomServer);
}

外部服务器

可以通过web UI或API添加外部服务器。它们要求：

• 服务器名称
• 服务器类型（外部）
• 启动服务器的命令
• 环境变量（可选）

RAG（检索增强生成）

1. 创建一个 rag-documents 项目根目录中的目录
2. 将PDF文件添加到目录
3. 应用程序将在启动时自动为它们建立索引
4. 使用RAG MCP服务器工具搜索文档

发展

运行测试

mvn test

生产大楼

mvn clean package -Pprod

Docker支持（可选）

创建一个 Dockerfile:

FROM openjdk:17-jdk-slim
COPY target/spring-ai-mcp-playground-1.0.0.jar app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

故障排除

Ollama连接问题

• 确保Olama正在运行： ollama serve
• 检查配置中的基本URL
• 验证模型名称是否存在： ollama list

OpenAI API错误

• 验证API密钥设置是否正确
• 检查您的API配额和账单

矢量存储问题

• 确保PostgreSQL正在运行
• 创建数据库： CREATE DATABASE vectordb;
• 安装pgvector扩展： CREATE EXTENSION vector;

贡献

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

许可证

该项目根据MIT许可证获得许可。

参考文献

• Spring AI文档
• 模型上下文协议

支持

有关问题和疑问，请在GitHub存储库上打开问题。