MCP Server

package com.example.docsassistant;

import java.util.List;

import org.springaicommunity.mcp.security.server.apikey.memory.ApiKeyEntityImpl;
import org.springaicommunity.mcp.security.server.apikey.memory.InMemoryApiKeyEntityRepository;
import org.springaicommunity.mcp.security.server.config.McpApiKeyConfigurer;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.annotation.Order;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

/** For machine clients such as a CI job: one API key per client, sent as X-API-key: <id>.<secret>. */
@Configuration(proxyBeanMethods = false)
@EnableWebSecurity
@Profile("apikey")
class McpApiKeySecurityConfig {

    @Bean
    @Order(1) // before the catch-all API chain of SecurityConfig
    SecurityFilterChain mcpApiKeySecurity(HttpSecurity http,
            @Value("${docsassistant.mcp.ci-key-secret}") String ciKeySecret) throws Exception {
        // The secret comes from the environment (DOCSASSISTANT_MCP_CI_KEY_SECRET); the repository stores it hashed.
        // InMemoryApiKeyEntityRepository is meant for samples: implement ApiKeyEntityRepository over your own store.
        var ciKey = ApiKeyEntityImpl.builder().id("ci01").name("CI pipeline").secret(ciKeySecret).build();
        return http
                .securityMatcher("/mcp/**") // only the MCP endpoint
                .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
                .with(McpApiKeyConfigurer.mcpServerApiKey(),
                        apiKey -> apiKey.apiKeyRepository(new InMemoryApiKeyEntityRepository<>(List.of(ciKey))))
                .build();
    }
}

package com.example.docsassistant;

import static org.assertj.core.api.Assertions.assertThat;

import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CopyOnWriteArrayList;

import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.JWSHeader;
import com.nimbusds.jose.crypto.RSASSASigner;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.gen.RSAKeyGenerator;
import com.nimbusds.jwt.JWTClaimsSet;
import com.nimbusds.jwt.SignedJWT;
import com.sun.net.httpserver.HttpServer;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.TextContent;
import io.modelcontextprotocol.spec.McpSchema.Tool;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.vectorstore.filter.Filter;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Import;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT, properties = {
        "spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:19100",
        "docsassistant.mcp.allowed-origins=http://localhost:6274",
        "docsassistant.mcp.allowed-hosts=localhost:*" })
@Import(DocsMcpServerTest.StubBeans.class)
class DocsMcpServerTest {

    static final String ISSUER = "http://localhost:19100";
    static final List<IssueDraft> DRAFTS = new CopyOnWriteArrayList<>();

    static HttpServer issuer;
    static RSAKey signingKey;

    @LocalServerPort
    int port;

    @TestConfiguration
    static class StubBeans {

        @Bean
        VectorStore vectorStore() {
            return new VectorStore() {
                @Override public void add(List<Document> documents) { }
                @Override public void delete(List<String> idList) { }
                @Override public void delete(Filter.Expression filterExpression) { }
                @Override public List<Document> similaritySearch(SearchRequest request) {
                    return List.of(Document.builder().text("Matrices support LU, QR and SVD.")
                            .metadata("source_path", "irurueta-algebra/matrices.adoc").score(0.9).build());
                }
                @Override public String getName() { return "stub"; }
            };
        }

        @Bean
        IssueApprovalQueue approvals() {
            return draft -> {
                DRAFTS.add(draft);
                return "D" + DRAFTS.size();
            };
        }
    }

    /** A minimal authorization server: discovery document and signing keys, all a resource server needs. */
    @BeforeAll
    static void startIssuer() throws Exception {
        signingKey = new RSAKeyGenerator(2048).keyID("test").generate();
        String jwks = new JWKSet(signingKey.toPublicJWK()).toString();
        String discovery = "{\"issuer\":\"" + ISSUER + "\",\"jwks_uri\":\"" + ISSUER + "/jwks\"}";
        issuer = HttpServer.create(new InetSocketAddress("localhost", 19100), 0);
        issuer.createContext("/jwks", exchange -> respond(exchange, jwks));
        issuer.createContext("/.well-known", exchange -> respond(exchange, discovery));
        issuer.start();
    }

    @AfterAll
    static void stopIssuer() {
        issuer.stop(0);
    }

    private static void respond(com.sun.net.httpserver.HttpExchange exchange, String json) throws java.io.IOException {
        byte[] body = json.getBytes(StandardCharsets.UTF_8);
        exchange.getResponseHeaders().add("Content-Type", "application/json");
        exchange.sendResponseHeaders(200, body.length);
        exchange.getResponseBody().write(body);
        exchange.close();
    }

    /** The audience is the URL of the MCP endpoint that the token is meant for. */
    private String token(String scopes, String audience) throws Exception {
        JWTClaimsSet claims = new JWTClaimsSet.Builder().issuer(ISSUER).subject("alice").audience(audience)
                .claim("scope", scopes)
                .issueTime(new Date()).expirationTime(new Date(System.currentTimeMillis() + 300_000)).build();
        SignedJWT jwt = new SignedJWT(new JWSHeader.Builder(JWSAlgorithm.RS256).keyID("test").build(), claims);
        jwt.sign(new RSASSASigner(signingKey));
        return jwt.serialize();
    }

    private McpSyncClient client(String accessToken) {
        var transport = HttpClientStreamableHttpTransport.builder("http://localhost:" + this.port)
                .endpoint("/mcp")
                .httpRequestCustomizer((request, method, uri, body, context) ->
                        request.header("Authorization", "Bearer " + accessToken))
                .build();
        return McpClient.sync(transport).requestTimeout(Duration.ofSeconds(10)).build();
    }

    private HttpResponse<String> postInitialize(String accessToken) throws Exception {
        var request = HttpRequest.newBuilder(URI.create("http://localhost:" + this.port + "/mcp"))
                .header("Content-Type", "application/json")
                .header("Accept", "application/json, text/event-stream")
                .POST(HttpRequest.BodyPublishers.ofString("""
                        {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25",
                         "capabilities":{},"clientInfo":{"name":"test","version":"1"}}}"""));
        if (accessToken != null) {
            request.header("Authorization", "Bearer " + accessToken);
        }
        return HttpClient.newHttpClient().send(request.build(), HttpResponse.BodyHandlers.ofString());
    }

    @Test
    void requestWithoutTokenIsRejectedAndPointsToTheResourceMetadata() throws Exception {
        HttpResponse<String> response = postInitialize(null);

        assertThat(response.statusCode()).isEqualTo(401);
        assertThat(response.headers().firstValue("WWW-Authenticate").orElse(""))
                .contains("resource_metadata=http://localhost:" + this.port + "/.well-known/oauth-protected-resource/mcp");
    }

    @Test
    void tokenIssuedForAnotherResourceIsRejected() throws Exception {
        String foreign = token("docs:read issues:draft", "https://other.example/api");

        assertThat(postInitialize(foreign).statusCode()).isEqualTo(401);
    }

    @Test
    void readerSeesTheToolsButCannotDraftAnIssue() throws Exception {
        String reader = token("docs:read", "http://localhost:" + this.port + "/mcp");
        try (McpSyncClient client = client(reader)) {
            client.initialize();

            List<String> names = new ArrayList<>(client.listTools().tools().stream().map(Tool::name).toList());
            assertThat(names).contains("searchDocs", "open_issue", "count_hits");

            CallToolResult denied = client.callTool(CallToolRequest.builder("open_issue")
                    .arguments(Map.of("title", "Fix a typo", "body", "See the matrices page")).build());
            assertThat(denied.isError()).isTrue();
            assertThat(DRAFTS).isEmpty();
        }
    }

    @Test
    void drafterGetsADraftOwnedByTheTokenSubject() throws Exception {
        String drafter = token("docs:read issues:draft", "http://localhost:" + this.port + "/mcp");
        try (McpSyncClient client = client(drafter)) {
            client.initialize();

            CallToolResult result = client.callTool(CallToolRequest.builder("open_issue")
                    .arguments(Map.of("title", "Fix a typo", "body", "See the matrices page")).build());

            assertThat(result.isError()).isFalse();
            assertThat(((TextContent) result.content().get(0)).text()).contains("waiting for maintainer approval");
            assertThat(DRAFTS).extracting(IssueDraft::requester).containsExactly("alice");
        }
    }
}

export MCP_TEST_TOKEN=...   # an access token for this server, from your authorization server

npx @modelcontextprotocol/inspector --cli http://localhost:8080/mcp --transport http \
  --protocol-era legacy --header "Authorization: Bearer ${MCP_TEST_TOKEN}" --method tools/list

npx @modelcontextprotocol/inspector --cli http://localhost:8080/mcp --transport http \
  --protocol-era legacy --header "Authorization: Bearer ${MCP_TEST_TOKEN}" \
  --method tools/call --tool-name open_issue \
  --tool-arg title="Fix a typo" --tool-arg body="See the matrices page"

INIT='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

# the Mcp-Session-Id response header identifies the session (STREAMABLE mode): keep it for the next requests
SESSION=$(curl -si http://localhost:8080/mcp -H "Authorization: Bearer ${MCP_TEST_TOKEN}" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d "$INIT" \
  | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}' | tr -d '\r')

curl -s http://localhost:8080/mcp -H "Authorization: Bearer ${MCP_TEST_TOKEN}" -H "Mcp-Session-Id: ${SESSION}" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -s http://localhost:8080/mcp -H "Authorization: Bearer ${MCP_TEST_TOKEN}" -H "Mcp-Session-Id: ${SESSION}" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"searchDocs","arguments":{"query":"matrix inverse"}}}'