Spring Boot MCP Servers

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.1</version>
    <relativePath/>
</parent>

<properties>
    <java.version>21</java.version>
    <spring-ai.version>2.0.1</spring-ai.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    </dependency>
</dependencies>

spring.application.name=docs-assistant
spring.ai.mcp.server.name=docs-assistant
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.protocol=STREAMABLE
spring.ai.mcp.server.type=SYNC
spring.main.banner-mode=off

package dev.example.docsassistant;

import java.util.Arrays;
import java.util.Comparator;
import java.util.List;
import java.util.Set;
import org.springframework.stereotype.Component;

/** Stubbed in-memory documentation index shared by the docs-assistant examples. */
@Component
public class DocStore {

    public record Page(String component, String page, String title, String text) {}

    public record Hit(String component, String page, String title, int score, String snippet) {}

    public record SearchResult(String query, String component, List<Hit> hits) {}

    static final List<Page> PAGES = List.of(
            new Page("algebra", "matrices", "Matrices", "Matrix decompositions such as LU, QR and SVD solve linear systems."),
            new Page("algebra", "wrappers", "Wrappers", "Wrapper classes hide the decomposition details behind a simple solver."),
            new Page("units", "conversion", "Unit conversion", "Convert lengths, masses and times between unit systems."),
            new Page("statistics", "gaussian", "Gaussian distributions", "Normal distributions, means and covariance matrices."));

    public static final Set<String> COMPONENTS = Set.of("algebra", "units", "statistics");

    public SearchResult search(String query, String component, int topK) {
        var words = Arrays.stream(query.toLowerCase().split("\\s+")).filter(w -> !w.isBlank()).toList();
        var hits = PAGES.stream()
                .filter(p -> p.component().equals(component))
                .map(p -> {
                    var haystack = (p.title() + " " + p.text()).toLowerCase();
                    int score = (int) words.stream().filter(haystack::contains).count();
                    return new Hit(p.component(), p.page(), p.title(), score, p.text());
                })
                .filter(h -> h.score() > 0)
                .sorted(Comparator.comparingInt(Hit::score).reversed().thenComparing(Hit::page))
                .limit(topK)
                .toList();
        return new SearchResult(query, component, hits);
    }

    public String read(String component, String page) {
        return PAGES.stream()
                .filter(p -> p.component().equals(component) && p.page().equals(page))
                .findFirst()
                .map(p -> "= " + p.title() + "\n\n" + p.text() + "\n")
                .orElseThrow(() -> new IllegalArgumentException("unknown page " + component + "/" + page));
    }
}

package dev.example.docsassistant;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

package dev.example.docsassistant;

import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
import io.modelcontextprotocol.spec.McpSchema.PromptMessage;
import io.modelcontextprotocol.spec.McpSchema.ReadResourceResult;
import io.modelcontextprotocol.spec.McpSchema.Role;
import io.modelcontextprotocol.spec.McpSchema.TextContent;
import io.modelcontextprotocol.spec.McpSchema.TextResourceContents;
import java.util.List;
import org.springframework.ai.mcp.annotation.McpArg;
import org.springframework.ai.mcp.annotation.McpPrompt;
import org.springframework.ai.mcp.annotation.McpResource;
import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpToolParam;
import org.springframework.stereotype.Component;

@Component
public class DocsTools {

    private final DocStore store;

    public DocsTools(DocStore store) {
        this.store = store;
    }

    @McpTool(name = "search_docs",
            description = "Search the documentation of one component and return the best matching pages.",
            generateOutputSchema = true,
            annotations = @McpTool.McpAnnotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false))
    public DocStore.SearchResult searchDocs(
            @McpToolParam(description = "Free-text query", required = true) String query,
            @McpToolParam(description = "algebra, units or statistics", required = true) String component,
            @McpToolParam(description = "Maximum number of hits", required = false) Integer topK) {
        if (!DocStore.COMPONENTS.contains(component)) {
            throw new IllegalArgumentException("Unknown component '" + component + "'");
        }
        return store.search(query, component, topK == null ? 3 : topK);
    }

    @McpResource(uri = "docs://{component}/{page}", name = "docs-page",
            description = "The AsciiDoc source of one documentation page", mimeType = "text/asciidoc")
    public ReadResourceResult readPage(String component, String page) {
        return ReadResourceResult.builder(List.of(
                TextResourceContents.builder("docs://" + component + "/" + page, store.read(component, page))
                        .mimeType("text/asciidoc").build())).build();
    }

    @McpPrompt(name = "answer_with_citations",
            description = "Instruct the model to answer from the docs and cite page URIs.")
    public GetPromptResult answerWithCitations(
            @McpArg(name = "question", required = true) String question,
            @McpArg(name = "component", required = false) String component) {
        String c = component == null ? "algebra" : component;
        String text = "Answer the question using only search_docs results for component '" + c + "'. "
                + "Cite every claim as docs://" + c + "/<page>.\n\nQuestion: " + question;
        return GetPromptResult.builder(List.of(new PromptMessage(Role.USER, TextContent.builder(text).build())))
                .build();
    }
}

package dev.example.docsassistant;

import io.modelcontextprotocol.spec.McpSchema.CompleteRequest;
import java.util.List;
import java.util.Map;
import org.springframework.ai.mcp.annotation.McpComplete;
import org.springframework.stereotype.Component;

@Component
public class DocsCompletions {

    /** Completes both variables of the resource template, switching on the argument's name. */
    @McpComplete(uri = "docs://{component}/{page}")
    public List<String> completePageUri(CompleteRequest request) {
        String prefix = request.argument().value();
        return switch (request.argument().name()) {
            case "component" -> components(prefix);
            case "page" -> {
                // Narrow to the component the user already filled in, when the client sends it as context.
                Map<String, String> filled = request.context() == null ? Map.of() : request.context().arguments();
                String component = filled == null ? null : filled.get("component");
                yield DocStore.PAGES.stream()
                        .filter(p -> component == null || p.component().equals(component))
                        .map(DocStore.Page::page)
                        .filter(p -> p.startsWith(prefix))
                        .sorted()
                        .toList();
            }
            default -> List.of();
        };
    }

    /** Only the prompt's `component` argument has a closed set of values; `question` is free text. */
    @McpComplete(prompt = "answer_with_citations")
    public List<String> completePromptArgument(CompleteRequest request) {
        return "component".equals(request.argument().name()) ? components(request.argument().value()) : List.of();
    }

    private static List<String> components(String prefix) {
        return DocStore.COMPONENTS.stream().sorted().filter(c -> c.startsWith(prefix)).toList();
    }
}

{ "jsonrpc": "2.0", "id": 2, "result": { "completion": { "values": ["algebra"], "total": 1, "hasMore": false } } }

@McpTool(name = "search_docs_async", description = "Reactive variant of search_docs.")
public Mono<DocStore.SearchResult> searchDocsAsync(
        @McpToolParam(description = "Free-text query", required = true) String query,
        @McpToolParam(description = "algebra, units or statistics", required = true) String component) {
    return Mono.fromSupplier(() -> store.search(query, component, 3));
}