MCP with Spring Boot

개요

MCP : Model Context Protocol은 LLM 애플리케이션과 외부 테이터 소스 및 도구 간의 원활한 통합을 가능하게 하는 개방형 프로토콜로 최근 AI 툴에서 많은 지원을 해주면서 사람들의 관심이 많아졌다. 

Spring AI에서도 MCP 관련 기능을 꾸준하게 추가하고 있고, 다양한 애플리케이션에서도 MCP를 지원하고 있어서 Spring을 사용하여 MCP를 사용하는 방법에 대해서 알아보도록 하자

 

MCP관련 내용은 아래 링크를 참조한다.

MCP : https://github.com/modelcontextprotocol)

Spring AI / Model Context Protocol : https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html

 

Getting Started

이번 예제에서는 로컬 파일 시스템이 있는 파일 중 파일 이름이 중국어 인사말로 된 파일을 찾는 기능에 대하여 구현한다. 예제는 두 가지 버전으로 첫 번째 예제는 OpenAI를 사용하여 파일을 찾고, 두 번째는 MCP의 Client, Server 구조의 두 개의 애플리케이션을 실행하여 작성하는 방법으로 예제를 구현한다.

 

OpenAI를 사용하여 작성하기

프로젝트 생성

OpenAI, MCP Client가 필요하기 때문에 의존성을 추가해 준다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
    implementation 'org.springframework.ai:spring-ai-mcp-client-spring-boot-starter'
    ......
}

 

Properties 설정

OpenAI 사용을 위해서 api-key를 추가한다.

spring.application.name=spring-mcp-first
spring.main.banner-mode=off
spring.ai.openai.api-key={ API KEY }

 

NamedMCPClientRunner 생성

Spring 애플리케이션이 시작되면 ChatClient(AI)를 사용해서 사용자가 지정된 디렉터리의 파일 중 파일명이 중국어 인사말로 된 파일을 검색하는 기능을 하는 클래스를 작성한다.

class NamedMcpClientRunner implements ApplicationRunner, BeanNameAware {
    private final AtomicReference<String> beanName = new AtomicReference<>();

    private final ChatClient.Builder builder;

    NamedMcpClientRunner(ChatClient.Builder builder) {
        this.builder = builder;
    }

    @Override
    public void setBeanName(String name) {
        this.beanName.set(name);
    }

    @Override
    public void run(ApplicationArguments args) throws Exception {
        var prompt = """
                what files are in the user-context folder, and of those files,
                which hava a name that corresponds to a chinese greeting?
                """;

        var response = this.builder
                .build()
                .prompt(prompt)
                .call()
                .entity(ChineseFile.class);

        System.out.println(this.beanName.get() + " response: " + response);
    }
}

record ChineseFile(String fileName, String word) {
}

 

Configuration

위에서 작성한 NamedMcpClientRunner를 Bean으로 등록해 준다.

ChatClient에 defaultTools에 사용자가 테스트로 사용할 디렉터리에 파일 목록을 제공하고, description을 사용하여 AI에게 기능을 제공한다.

@Configuration
class LocalToolsAutoConfiguration {

    @Bean
    NamedMcpClientRunner namedMcpClientRunner(ChatClient.Builder builder, Tools tools) {
        return new NamedMcpClientRunner(builder.defaultTools(tools));
    }

    @Component
    static class Tools {
        @Tool(description = "returns all the files in a folder called " + SpringMcpFirstApplication.FOLER + ".")
        String[] listFiles() {
            System.out.println("returning the files from " + SpringMcpFirstApplication.FOLER);
            return new File(SpringMcpFirstApplication.FOLER).list();
        }
    }
}

@SpringBootApplication
public class SpringMcpFirstApplication {

    static final String FOLER = "D:\\user-context";
    ......

 

Demo

애플리케이션을 실행하기 전에 지정한 디렉터리에 아래와 같이 파일을 미리 생성해 둔다.

hello, hi, hola, ni_hao, salut

 

애플리케이션을 실행하면 아래와 같이 중국어 인사말로 작성된 파일 정보를 확인할 수 있다.

returning the files from D:\user-context
namedMcpClientRunner response: ChinessFile[fileName=ni_hao, word=你好]

 

예제 소스 : https://github.com/igooo/tutorials/tree/main/spring-boot-3.4/spring-mcp/spring-mcp-first

 

 

MCP Client, Server 구조로 작성하기

Server 프로젝트 

MCP Server 의존성을 추가한다.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.ai:spring-ai-mcp-server-webmvc-spring-boot-starter'
    ......

 

Properties 설정

Client 애플리케이션과 동시에 실행하기 위해 서버 Port를 8081로 변경해 준다.

spring.application.name=spring-mcp-server
spring.main.banner-mode=off
server.port=8081

 

ToolCallbackProvier 생성

첫 번째 구현애서 Tool 객체를 생성했던 로직을 MCP Server에 추가하고 MethodToolCallbackProvider를 Bean으로 등록한다.

@SpringBootApplication
public class SpringMcpServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringMcpServerApplication.class, args);
    }

    @Bean
    ToolCallbackProvider fileSystemToolProvider(FileTools fileTools) {
        return MethodToolCallbackProvider.builder().toolObjects(fileTools).build();
    }
}

@Component
class FileTools {

    @Tool(description = "returns all the files in a folder. D:\\user-context")
    String[] listFiles() {
        System.out.println("calling listFiles");
        return new File("D:\\user-context").list();
    }

}

 

Client 프로젝트 

Client 프로젝트는 앞에서 작성한 첫 번째 프로젝트를 그대로 사용한다. (LocalToolsAutoConfiguration은 삭제한다.)

Sever 프로젝트에 McpSyncClient를 사용하여 연결할 수 있도록 설정 정보를 추가한다.

@Configuration
class LocalFileSystemMcpConfiguration {
    @Bean
    McpSyncClient mcpSyncClient() {
        var mcp = McpClient
                .sync(new HttpClientSseClientTransport("http://localhost:8081"))
                .build();
        mcp.initialize();
        return mcp;
    }

    @Bean
    NamedMcpClientRunner localFileSystemMcpClientRunner(ChatClient.Builder builder, McpSyncClient client) {
        var provider = new SyncMcpToolCallbackProvider(client);
        return new NamedMcpClientRunner(builder.defaultTools(provider));
    }
}

 

Demo

서버 프로젝트를 먼저 실행 후 클라이언트 프로젝트를 실행하면 각각 아래와 같은 로그를 확인할 수 있다.

# Server
calling listFiles

# Client
localFileSystemMcpClientRunner response: ChinessFile[fileName=ni_hao, word=你好]

 

예제 소스 : https://github.com/igooo/tutorials/tree/main/spring-boot-3.4/spring-mcp/spring-mcp-second

 

마무리

MCP를 사용한 많은 활용 방법이 공유되고 있고, 실제 업무에 사용할 수 있는 기능도 개발이 가능해 보인다.

다음 포스팅에는 업무에 활용 가능한 예제를 개발해 볼 예정이다.