MCP 유틸리티

MCP 유틸리티 (MCP Utilities)

MCP 유틸리티는 Model Context Protocol을 Spring AI 애플리케이션에 통합하기 위한 기반 지원을 제공해요. 이 유틸리티들은 Spring AI의 도구 시스템과 MCP 서버 사이의 원활한 통신을 가능하게 하고, 동기·비동기 작업을 모두 지원해요. 프로그램 방식으로 MCP 클라이언트와 서버를 구성하고 상호작용할 때 주로 사용되며, 더 간편한 구성은 boot starters를 고려해 보세요.

출처: 문서

본문

MCP 유틸리티 (MCP Utilities)

MCP 유틸리티는 Model Context Protocol을 Spring AI 애플리케이션과 통합하기 위한 기반 지원을 제공해요. 이 유틸리티들은 Spring AI의 도구 시스템과 MCP 서버 사이의 원활한 통신을 가능하게 하며 동기와 비동기 작업 모두를 지원해요. 보통 프로그램 방식의 MCP 클라이언트·서버 구성과 상호작용에 사용되며, 더 간편한 구성이 필요하다면 boot starters를 사용하는 걸 고려해 보세요.

ToolCallback 유틸리티 (ToolCallback Utility)

Tool Callback Adapter

MCP 도구를 Spring AI의 도구 인터페이스에 맞게 조정하며, 동기와 비동기 실행을 모두 지원해요.

  • Sync
  • Async
McpSyncClient mcpClient = // obtain MCP client
Tool mcpTool = // obtain MCP tool definition
ToolCallback callback = new SyncMcpToolCallback(mcpClient, mcpTool);

// Use the tool through Spring AI's interfaces
ToolDefinition definition = callback.getToolDefinition();
String result = callback.call("{\"param\": \"value\"}");

McpAsyncClient mcpClient = // obtain MCP client
Tool mcpTool = // obtain MCP tool definition
ToolCallback callback = new AsyncMcpToolCallback(mcpClient, mcpTool);

// Use the tool through Spring AI's interfaces
ToolDefinition definition = callback.getToolDefinition();
String result = callback.call("{\"param\": \"value\"}");

Tool Callback Providers

MCP 클라이언트에서 MCP 도구를 발견하고 제공해요.

  • Sync
  • Async
McpSyncClient mcpClient = // obtain MCP client
ToolCallbackProvider provider = new SyncMcpToolCallbackProvider(mcpClient);

// Get all available tools
ToolCallback[] tools = provider.getToolCallbacks();

여러 클라이언트를 사용할 때:

List<McpSyncClient> clients = // obtain list of clients
List<ToolCallback> callbacks = SyncMcpToolCallbackProvider.syncToolCallbacks(clients);

클라이언트의 일부만 동적으로 선택할 때:

@Autowired
private List<McpSyncClient> mcpSyncClients;

public ToolCallbackProvider buildProvider(Set<String> allowedServerNames) {
    // Filter by server.name().
    List<McpSyncClient> selected = mcpSyncClients.stream()
        .filter(c -> allowedServerNames.contains(c.getServerInfo().name()))
        .toList();

    return new SyncMcpToolCallbackProvider(selected);
}

McpAsyncClient mcpClient = // obtain MCP client
ToolCallbackProvider provider = new AsyncMcpToolCallbackProvider(mcpClient);

// Get all available tools
ToolCallback[] tools = provider.getToolCallbacks();

여러 클라이언트를 사용할 때:

List<McpAsyncClient> clients = // obtain list of clients
Flux<ToolCallback> callbacks = AsyncMcpToolCallbackProvider.asyncToolCallbacks(clients);

McpToolUtils

ToolCallbacks를 ToolSpecifications로 변환

Spring AI 도구 콜백을 MCP 도구 명세로 변환해요:

  • Sync
  • Async
List<ToolCallback> toolCallbacks = // obtain tool callbacks
List<SyncToolSpecifications> syncToolSpecs = McpToolUtils.toSyncToolSpecifications(toolCallbacks);

그런 다음 McpServer.SyncSpecification을 사용해 도구 명세를 등록할 수 있어요:

McpServer.SyncSpecification syncSpec = ...
syncSpec.tools(syncToolSpecs);

List<ToolCallback> toolCallbacks = // obtain tool callbacks
List<AsyncToolSpecification> asyncToolSpecifications = McpToolUtils.toAsyncToolSpecifications(toolCallbacks);

그런 다음 McpServer.AsyncSpecification을 사용해 도구 명세를 등록할 수 있어요:

McpServer.AsyncSpecification asyncSpec = ...
asyncSpec.tools(asyncToolSpecifications);

MCP 클라이언트를 ToolCallbacks로 변환

MCP 클라이언트에서 도구 콜백을 얻어요:

  • Sync
  • Async
List<McpSyncClient> syncClients = // obtain sync clients
List<ToolCallback> syncCallbacks = McpToolUtils.getToolCallbacksFromSyncClients(syncClients);

List<McpAsyncClient> asyncClients = // obtain async clients
List<ToolCallback> asyncCallbacks = McpToolUtils.getToolCallbacksFromAsyncClients(asyncClients);

네이티브 이미지 지원 (Native Image Support)

McpHints 클래스는 MCP 스키마 클래스에 대한 GraalVM 네이티브 이미지 힌트를 제공해요. 이 클래스는 네이티브 이미지를 빌드할 때 MCP 스키마 클래스에 필요한 모든 리플렉션 힌트를 자동으로 등록해 줘요.

더 알아보기 (Learn more)