MCP - Spring Ai Practice

개요

Spring AI는 MCP Java SDK를 Spring Boot 통합으로 확장하여 Client와 Server Starter를 제공합니다.

본문

MCP Overview

MCP(Model Communication Protocol)은 AI 모델이 외부 도구와 리소스와 상호작용할 수 있도록 설계된 표준화된 프로토콜입니다.

MCP Java SDK는 MCP 프로토콜을 구현하여 Java 애플리케이션이 MCP 호환 AI 모델과 통신할 수 있도록 지원합니다.

 

MCP Java SDK는 3계층 아키텍처로 구성됩니다.

 

출처:  https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html#_mcp_java_sdk_architecture

• 클라이언트/서버 계층: McpClient는 클라이언트 측 작업을 처리하고 McpServer는 서버 측 작업을 처리합니다. 통신 관리를 위해 McpSession을 사용합니다.
• 세션 계층(McpSession): McpClientSession과 McpServerSession 구현을 통해 통신 패턴과 상태를 관리합니다.
• 전송 계층(McpTransport): 여러 전송 구현을 지원하여 JSON-RPC 메시지 직렬화 및 역직렬화를 처리합니다.

MCP Client

MCP Client는 MCP 아키텍처의 핵심 구성 요소로 MCP Server와의 연결 설정 및 관리를 담당합니다.

주요 기능:

• 서버와의 호환성을 보장하기 위한 프로토콜 버전 협상
• 사용 가능한 기능을 결정하기 위한 기능 협상
• 메시지 전송 및 JSON-RPC 통신
• 도구 발견 및 실행
• 리소스 접근 및 관리
• 프롬포트 시스템 상호작용
• 선택적 기능
  • 루트 관리
  • 샘플링 지원
• 동기 및 비동기 작업
• 전송 옵션:
  • 프로세스 기반 통신을 위한 Stdio 기반 전송
  • Java HttpClient 기반 SSE 클라이언트 전송
  • 반응형 HTTP 스트리밍을 위한 WebFlux SSE 클라이언트 전송

MCP Server

MCP Server는 MCP 아키텍처의 기초 구성 요소로 클라이언트에게 도구, 리소스 및 기능을 제공하는 역할을 합니다.

주요 기능:

• 서버 측 프로토콜 작업 구현
• 도구 노출 및 발견
• URI 기반 접근을 통한 리소스 관리
• 프롬프트 템플릿 제공 및 처리
• 클라이언트와의 기능 협상
• 구조화된 로깅 및 알림
• 동시 클라이언트 연결 관리
• 동기 및 비동기 API 지원
• 전송 옵션:
  • 프로세스 기반 통신을 위한 Stdio 기반 전송
  • 서블릿 기반 SSE 서버 전송
  • 반응형 HTTP 스트리밍을 위한 WebFlux SSE 서버 전송
  • 서블릿 기반 HTTP 스트리밍을 위한 WebMVC SSE 서버 전송

Spring Boot Integration

Spring AI는 다음 Spring Boot 스타터를 통해 MCP Java SDK와의 원활한 통합을 제공합니다.

클라이언트 스타터

• spring-ai-starter-mcp-client - STDIO 및 HTTP 기반 SSE 지원을 제공하는 핵심 스타터
• spring-ai-starter-mcp-client-webflux - WebFlux 기반 SSE 전송 구현

서버 스타터

• spring-ai-starter-mcp-server - STDIO 전송 지원을 포함한 핵심 서버
• spring-ai-starter-mcp-server-webmvc - Spring MVC 기반 SSE 전송 구현
• spring-ai-starter-mcp-server-webflux - WebFlux 기반 SSE 전송 구현

간단한 사용법 예제

MCP Client 예제:

• build.gradle.kts

implementation("org.springframework.ai:spring-ai-starter-mcp-client-webflux")
implementation("org.springframework.boot:spring-boot-starter-webflux") 
// or 
implementation("org.springframework.ai:spring-ai-starter-mcp-client")
implementation("org.springframework.boot:spring-boot-starter-web")

• application.yml

    spring:
      application:
        name: mcp-client-app
      ai:
        mcp:
          client:
            sse:
              connections:
                server1:
                  url: http://localhost:8081
                server2:
                  url: http://localhost:8082
    server:
      port: 8080

• Tool 가져오기

    @Service
    class ToolTestService(
        val clients: List<McpSyncClient>, // MCP Client 빈 가져오기
        val toolCallbackProvider: SyncMcpToolCallbackProvider, // MCP ToolCallbackProvider 빈 가져오기
    )

MCP Server 예제:

• build.gradle.kts

    implementation("org.springframework.ai:spring-ai-starter-mcp-server-webmvc")
    
    // or
    implementation("org.springframework.ai:spring-ai-starter-mcp-server-webflux")

• application.yml

    spring:
        application:
            name: mcpserver1
        ai:
            mcp:
                server:
                    name: mcp-server1
                    instructions: "This server provides datatime information tools and resources."
    server:
        port: 8081

• 도구 등록

    @Bean
    fun toolCallbackProvider(toolService: ToolService): ToolCallbackProvider {
        return MethodToolCallbackProvider.builder()
            .toolObjects(toolService)
            .build()
    }

마무리

Spring AI는 Spring Boot와의 원활한 통합을 통해 MCP Java SDK를 확장하여 MCP 클라이언트 및 서버 애플리케이션 개발을 간소화합니다. MCP의 기능을 확인하게에 시간이 많이 걸릴 수 있어서 여기서는 간단한 개요만 제공했습니다.

Reference Documentation

• Spring AI Reference Documentation
• Spring AI Practice