MCP客户端
- 该项目是使用模型上下文协议（MCP）的聊天机器人系统的MCP客户端演示。
为将聊天机器人应用到公司内部门户网站等提供基础结构。
- 基于Spring AI+Gemini实现。
用户-MCP client-MCP server集成方案
MCP标准方法由服务器提供，客户端调用它，使用什么工具（tool）由与客户端关联的AI模型（如Gemini）决定。
1. Mcp Client실행 → tools/list 요청
↓
2. MCP Server → 도구 목록 반환
사용자 요청
3. MCP Client → Gemini에 요청 전달
↓
4. Gemini → 사용자 메시지 분석 및 도구 선택
＂공지사항 알려줘“ → " get_notice_list" 선택 및 콜백
↓
5. MCP client → tools/call 요청
↓
6. MCP Server → 도구 실행(포털 API 호출) 및 결과 반환
↓
7. Mcp client 에게 (tools/call에 대한)응답
📁 项目结构
mcp-client-sample/
src/main/java/com/example/mcpclient/
├── McpclientApplication.java # Spring Boot 애플리케이션
├── config/ # Spring Bean 설정
│ ├── GeminiConfig.java # Gemini API 설정 및 RetryTemplate 구성
│ ├── McpServerConfig.java # MCP 서버 설정 (application.yml에서 로드)
│ └── WebConfig.java # HTTP 메시지 컨버터 설정
├── controller/ # HTTP Controller
│ ├── ChatController.java # 대화 도메인 API (유저 facing)
│ ├── ServerController.java # 서버/도구 관리 API
│ └── AdminController.java # 특수/디버깅/백도어 API
├── exception/ # 예외 처리
│ └── GlobalExceptionHandler.java # 전역 예외 핸들러
├── model/ # 데이터 모델
│ ├── ChatMessage.java # 채팅 메시지 모델
│ ├── McpRequest.java # MCP 요청 메시지
│ ├── McpResponse.java # MCP 응답 메시지
│ └── McpError.java # MCP 오류 정보
└── service/ # 비즈니스 로직
├── GeminiService.java # Gemini API 직접 호출 서비스
├── McpChatService.java # MCP 서버를 통한 채팅 서비스 (세션 관리 포함)
├── McpServerRegistry.java # MCP 서버 등록/관리 (도구 목록 캐싱, stdio/SSE 공통)
├── McpServerConnectionInterface.java # 통신 방식 추상화 인터페이스 (stdio/SSE 공통)
├── McpServerStdioConnection.java # stdio 방식 MCP 서버 통신 (stdio 전용)
├── McpServerSseConnection.java # SSE 방식 MCP 서버 통신 (SSE 전용)
└── McpSseClientManager.java # SSE 클라이언트 연결 관리 (SSE 전용)🔄 MCP Clinet行为流
- 注册工具：启动项目（Spring Boot）
- MCP客户端>McpServerRegistry初始化（）：从配置文件加载服务器信息 - MCP客户端>McpServerRegistry.fetchToolsFromServer（）：从服务器获取工具列表
- 用户请求：“请显示公告列表”（自然语言）-HTTP POST请求
/mcp/servers/{serverName}/chat发送到MCP客户端端点 - MCP客户端>McpController.chatWithServer（）:
/mcp/servers/{serverName}/chat通过端点接收HTTP请求并提取参数 - MCP客户端>McpChatService.chatWithServer（）：向Gemini发送请求
- MCP客户端>McpChatService.getOrCreateChatClient（）：创建/导入ChatClient - MCP客户端>McpChatService.createToolCallback（）：将MCP服务器上的工具转换为Spring AI ToolCallback - ChatClient已经将MCP服务器上的所有工具 defaultToolCallbacks()注册为
- 双子座：分析用户请求，使用适当的工具（
mcp_portal-mcp_get_notice_list）自动选择 - 双子座→ 工具回调：调用所选工具
- MCP客户端>McpToolCallback.call（）：调用ToolCallback的call方法
- MCP 客户端 > McpChatService.callMcpTool()：作为MCP服务器
tools/call发送请求 - MCP 服务器：运行工具后返回结果
- 双子座：获取工具运行结果并生成用户友好的响应
- MCP客户端>McpController.chatWithServer（）：将Gemini响应返回为HTTP响应
- 用户：接收最终响应
🚀 执行方法
mvn spring-boot:run 注意事项
验证MCP服务器连接
application.properties在中确认注册
mcp:
servers:
mcp-server-sample:
command: java
args:
- -jar
- C:\Users\User\Documents\projects\mcp-server-sample\target\mcp-server-sample-0.0.1-SNAPSHOT.jar
- --mcp-stdio
cwd: C:\Users\User\Documents\projects\mcp-server-sampleGET /mcp/servers确认注册为
gemini指南
- Gemini API：
application.properties在中验证API密钥 - https://ai.google.dev/gemini-api/docs/api-key?hl=ko
🛜 设置MCP Server通信方式
- 通信方式
application.yml在的服务器设置中type由字段决定。 - stdio模式:
application.yml从type: stdio设置（默认） - SSE模式:
application.yml从type: sse及url需要设置
mcp:
servers:
mcp-server-sample-sse:
type: sse
url: http://localhost:8080 # MCP 서버의 기본 URL📋 用户请求方法（无chat UI时测试）
方法1:curl命令
curl -X POST "http://localhost:8081/mcp/chat/mcp-server-sample" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Cookie: SESSIONID=796BAFB973B32658830B2CB822834C7B" \
-d '{"messages":[{"role":"user","content":"Please show me the notice list"}]}'方法2：curl命令+json（使用文件作为UTF-8编码问题）
# 1. request-notice-list.json 파일 수정
# 2. 파일을 사용하여 요청
curl -X POST "http://localhost:8081/mcp/chat/mcp-server-sample" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Cookie: SESSIONID=959891C59F9E2B75626FD34975C30E30" \
--max-time 40 \
--data-binary @request-notice-list.json方法3：使用Demo Class
打开McpClientDemo.java文件▶点击即可运行。 用自然语言请求。