# java项目集成MCP **Repository Path**: hLDrange/java-project-integration-mcp ## Basic Information - **Project Name**: java项目集成MCP - **Description**: springboot项目集成MCP的demo，环境jdk17，maven3.9.9，windows - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-12-09 - **Last Updated**: 2026-01-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MCP (Model Common Platform) 接入说明文档 ## 项目概述 本项目是一个Java实现的MCP（Model Common Platform）框架，提供了统一的AI模型调用接口，允许开发者通过标准化的方式接入不同的AI模型提供商（如DeepSeek、OpenAI等）。 ## 项目结构 ``` com.bigtimes.mcpdemo.mcp/ ├── adapter/ # 模型适配器层 │ ├── AbstractModelAdapter.java # 适配器抽象基类 │ ├── DeepSeekAdapter.java # DeepSeek模型适配器 │ ├── MockModelAdapter.java # 模拟模型适配器 │ ├── ModelAdapter.java # 适配器接口 │ ├── ModelAdapterFactory.java # 适配器工厂 │ └── OpenAIAdapter.java # OpenAI模型适配器 ├── config/ # 配置层 │ ├── McpConfig.java # MCP配置类 │ └── SwaggerConfig.java # Swagger配置类 ├── controller/ # 控制器层 │ └── McpController.java # REST API控制器 ├── core/ # 核心业务层 │ └── ModelRouter.java # 模型路由 ├── dto/ # 数据传输对象 │ ├── McpRequest.java # MCP统一请求格式 │ ├── McpResponse.java # MCP统一响应格式 │ ├── Message.java # 消息格式 │ └── ModelParameters.java # 模型参数 └── service/ # 服务层 ├── McpService.java # MCP服务主类 └── ModelRouter.java # 模型路由(注:与core目录下的实现相同) ``` ## MCP实现原理 ### 1. 适配器模式设计 MCP框架采用了**适配器模式**，将不同AI模型提供商的API接口转换为统一的MCP接口。 #### 适配器接口 (`ModelAdapter`) 定义了所有模型适配器必须实现的方法，包括调用模型、检查模型可用性等。 #### 抽象适配器基类 (`AbstractModelAdapter`) 实现了通用的模型调用逻辑，包括： - HTTP请求发送 - 错误处理 - 响应构建 子类只需要实现特定模型的请求转换和响应转换逻辑。 #### 具体适配器实现 如`DeepSeekAdapter`、`OpenAIAdapter`等，负责将MCP统一格式转换为特定模型的API格式。 ### 2. 核心组件 #### 模型适配器工厂 (`ModelAdapterFactory`) - 管理所有可用的模型适配器 - 根据模型名称选择合适的适配器 - 提供模型可用性检查 #### 模型路由 (`ModelRouter`) - 根据请求的路由策略选择合适的模型 - 支持多种路由策略（默认、随机等） - 处理模型调用逻辑 #### MCP服务 (`McpService`) - 作为MCP功能的主入口点 - 处理请求验证和错误处理 ### 3. Swagger API文档 MCP框架集成了Swagger/OpenAPI 3.0，提供了交互式API文档： - 自动生成API文档 - 支持在线测试API - 提供API接口的详细说明 Swagger配置在`SwaggerConfig.java`中定义，包括文档标题、版本、联系方式等信息。 http://localhost:8080/swagger-ui/index.html ## MCP请求格式 ### 请求数据结构 MCP采用统一的JSON请求格式，定义在`McpRequest.java`中： ```java public class McpRequest { private String requestId; // 请求ID private String model; // 目标模型名称 private List messages; // 消息列表 private ModelParameters parameters; // 模型参数 private String routingStrategy; // 路由策略 } ``` #### 消息结构 (`Message`) ```java public class Message { private String role; // 消息角色：system, user, assistant private String content; // 消息内容 private String type; // 消息类型：text, image, audio, video等 } ``` #### 模型参数 (`ModelParameters`) ```java public class ModelParameters { private Double temperature; // 温度参数 private Integer maxTokens; // 最大生成token数 private String samplingMethod; // 采样方法 private Double topP; // top_p参数 private Integer topK; // top_k参数 private Boolean stream; // 是否启用流式输出 private String responseFormat; // 响应格式 private Integer n; // 生成结果数量 } ``` ### 请求示例 ```json { "requestId": "uuid-1234567890", "model": "deepseek-chat", "messages": [ { "role": "system", "content": "你是一个AI助手", "type": "text" }, { "role": "user", "content": "请解释什么是MCP？", "type": "text" } ], "parameters": { "temperature": 0.7, "maxTokens": 1000, "topP": 0.95, "stream": false }, "routingStrategy": "default" } ``` ## MCP响应格式 ### 响应数据结构 MCP采用统一的JSON响应格式，定义在`McpResponse.java`中： ```java public class McpResponse { private String responseId; // 响应ID private String requestId; // 请求ID private String status; // 响应状态：success, error, pending private List choices; // 响应内容 private ModelInfo modelInfo; // 模型信息 private Long timestamp; // 响应时间戳 private ErrorInfo error; // 错误信息（如果有） // 内部类 public static class ModelInfo { private String name; // 模型名称 private String version; // 模型版本 private String provider; // 模型提供商 } public static class ErrorInfo { private String code; // 错误代码 private String message; // 错误消息 private String details; // 错误详情 } } ``` ### 响应示例 #### 成功响应 ```json { "responseId": "uuid-0987654321", "requestId": "uuid-1234567890", "status": "success", "choices": [ { "role": "assistant", "content": "MCP (Model Common Platform) 是一个统一的AI模型调用平台...", "type": "text" } ], "modelInfo": { "name": "deepseek-chat", "version": "v1.0", "provider": "DeepSeek" }, "timestamp": 1765276800000, "error": null } ``` #### 错误响应 ```json { "responseId": "uuid-0987654321", "requestId": "uuid-1234567890", "status": "error", "choices": null, "modelInfo": null, "timestamp": 1765276800000, "error": { "code": "MODEL_CALL_ERROR", "message": "模型调用失败", "details": "API密钥无效" } } ``` ## 如何接入MCP ### 1. 配置模型提供商信息 在`application.properties`或`application.yml`中配置模型提供商的API密钥和URL： ```properties # DeepSeek配置 mcp.model.deepseek.api-key=your-deepseek-api-key mcp.model.deepseek.api-url=https://api.deepseek.com/chat/completions # OpenAI配置 mcp.model.openai.api-key=your-openai-api-key mcp.model.openai.api-url=https://api.openai.com/v1/chat/completions ``` ### 2. 使用MCP API MCP提供了以下REST API接口： #### 调用AI模型 ``` POST /api/mcp/chat Content-Type: application/json ``` 请求体：MCP统一请求格式（见上文） 响应：MCP统一响应格式（见上文） #### 获取可用模型列表 ``` GET /api/mcp/models ``` 响应： ```json ["deepseek-chat", "deepseek-coder", "gpt-3.5-turbo", "gpt-4"] ``` #### 检查模型可用性 ``` GET /api/mcp/models/{modelName}/availability ``` 响应： ```json true ``` ### 3. 代码中使用MCP 在Java代码中，可以直接注入`McpService`并使用： ```java @Autowired private McpService mcpService; // 构建请求 McpRequest request = McpRequest.builder() .requestId(UUID.randomUUID().toString()) .model("deepseek-chat") .messages(Arrays.asList( Message.builder() .role("user") .content("请解释什么是MCP？") .type("text") .build() )) .parameters(ModelParameters.builder() .temperature(0.7) .maxTokens(1000) .build()) .build(); // 调用模型 McpResponse response = mcpService.processRequest(request); ``` ### 4. 使用Swagger API文档 启动应用后，可以通过以下地址访问Swagger API文档： ``` http://localhost:8080/swagger-ui.html ``` Swagger文档提供了： - API接口列表和详细说明 - 请求参数和响应格式 - 在线测试功能 - 接口版本信息 ## 适配器开发指南 如果需要接入新的AI模型提供商，可以按照以下步骤开发适配器： ### 1. 创建适配器类 继承`AbstractModelAdapter`类，实现特定模型的请求转换和响应转换逻辑： ```java @Component("newModelAdapter") public class NewModelAdapter extends AbstractModelAdapter { @Value("${mcp.model.newmodel.api-key}") private String newModelApiKey; @Value("${mcp.model.newmodel.api-url}") private String newModelApiUrl; private static final String[] SUPPORTED_MODELS = { "new-model-1", "new-model-2" }; public NewModelAdapter() { this.providerName = "NewModelProvider"; } @Override public void afterPropertiesSet() { this.apiKey = newModelApiKey; this.apiUrl = newModelApiUrl; } @Override public String[] getSupportedModels() { return SUPPORTED_MODELS; } @Override protected String convertToModelSpecificRequest(McpRequest request) throws Exception { // 实现MCP请求到特定模型请求的转换 } @Override protected McpResponse convertToMcpResponse(String modelResponse, McpRequest request, String responseId) throws Exception { // 实现特定模型响应到MCP响应的转换 } @Override protected String getModelVersion(String modelName) { // 返回模型版本信息 } } ``` ### 2. 注册适配器 适配器会通过Spring的@Component注解自动注册到`ModelAdapterFactory`中。 ## 路由策略 MCP支持多种路由策略，可以在请求中指定： - `default`: 默认路由策略，根据模型名称选择合适的适配器 - `random`: 随机路由策略，随机选择一个可用的模型适配器 - `loadbalance`: 负载均衡策略（待实现） - `failover`: 故障转移策略（待实现） ## 常见问题 ### 1. 如何添加新的模型参数？ 在`ModelParameters`类中添加新的字段，并在对应的适配器中实现参数转换逻辑。 ### 2. 如何处理流式响应？ 在`ModelParameters`中设置`stream=true`，并在适配器中实现流式响应处理逻辑。 ### 3. 如何进行错误处理？ MCP框架会自动捕获和处理错误，返回标准化的错误响应格式。开发者可以通过检查响应的`status`字段和`error`字段来处理错误。 ## 总结 MCP框架提供了统一的AI模型调用接口，通过适配器模式实现了不同AI模型提供商的标准化接入。开发者只需要学习一套API，就可以调用多种AI模型，大大提高了开发效率和代码可维护性。 --- **版本**: V1.0.1 **更新日期**: 2025-12-08 **更新内容**: - 集成Swagger/OpenAPI 3.0，提供交互式API文档 - 修正项目结构，明确McpService和ModelRouter的位置 - 更新路由策略说明，添加随机路由策略 - 完善文档内容 **维护团队**: BigTimes