Feature/mcp (#846)

* Added MCP support using SSE on http://localhost:8080/sse

* Reverted change that IntelliJ complains about

* Pre-rework

* Cleaned up the code a fair bit

* Renamed

* Renamed

* Running spotless

* Reuse FhirContext in result serialization to make MCP server work with R5

* Added support for transactions

* PoC tool for CDS Hooks

* some cleanup

* Upgrade of model protocol

* Added comments

* Removed field injection ... CDS to be changed to AutoConfig eventually

* Adjusted to new builder pattern

* Update src/main/java/ca/uhn/fhir/rest/server/MCPBridge.java

Co-authored-by: Copilot <[email protected]>

* A bit of restructuring

* More rework

* Removing (suspected unnecessary) formatting

* Add more example doc

* Added a smoke- / passthrough-test

* Applied spotless

* Update src/main/java/ca/uhn/fhir/jpa/starter/mcp/RequestBuilder.java

Co-authored-by: Copilot <[email protected]>

* Update src/main/java/ca/uhn/fhir/jpa/starter/mcp/RequestBuilder.java

Co-authored-by: Copilot <[email protected]>

* Update src/main/java/ca/uhn/fhir/jpa/starter/mcp/ToolFactory.java

Co-authored-by: Copilot <[email protected]>

* Update src/main/java/ca/uhn/fhir/rest/server/McpCdsBridge.java

Co-authored-by: Copilot <[email protected]>

* Update src/main/java/ca/uhn/fhir/rest/server/McpCdsBridge.java

Co-authored-by: Copilot <[email protected]>

* Formatting

* Added some documentation

* spotless cares about MD?

* Reverting back to default values

* minor refinements

* Fixed CDS hooks configuration

* Fixed some wirings

* Revert "Fixed some wirings"

This reverts commit c9d3bc0.

* Revert "Fixed CDS hooks configuration"

This reverts commit 67c4279.

---------

Co-authored-by: Ádám Z. Kövér <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

.dockerignore

@@ -5,7 +5,6 @@ target/maven-*
 target/ROOT
 target/test-classes/
 target/war
-target/duplicate-finder-result.xml
 target/jacoco.exec
 target/*.original
 .idea

README.md

@@ -588,3 +588,7 @@ docker run --rm -it -p 8080:8080 \
 ```
 
 You can configure the agent using environment variables or Java system properties, see <https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/> for details.
+
+## Enable MCP
+
+MCP capabilities can be enabled by setting the `spring.ai.mcp.server.enabled` to `true`. This will enable the MCP server and expose the MCP endpoints. The MCP endpoint is currently hardcoded to `/mcp/message` and can be tried out by running e.g. `npx @modelcontextprotocol/inspector` and connect to http://localhost:8080/mcp/message using Streamable HTTP. Spring AI MCP Server Auto Configuration is currently not supported.

pom.xml

@@ -383,6 +383,32 @@
             <version>5.0.1</version>
         </dependency>
 
+        <dependency>
+            <groupId>org.springframework.ai</groupId>
+            <artifactId>spring-ai-mcp</artifactId>
+            <version>1.0.2</version>
+        </dependency>
+        <!--
+        This will be included as well as using Spring Automatic Configuration
+        once spring-ai and io.modelcontextprotocol.sdk are on par
+        -->
+        <!--<dependency>
+            <groupId>org.springframework.ai</groupId>
+            <artifactId>spring-ai-starter-mcp-server</artifactId>
+            <version>1.0.2</version>
+        </dependency>-->
+
+        <dependency>
+            <groupId>io.modelcontextprotocol.sdk</groupId>
+            <artifactId>mcp</artifactId>
+            <version>0.12.1</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework</groupId>
+            <artifactId>spring-test</artifactId>
+
+        </dependency>
 
         <dependency>
             <groupId>org.junit.jupiter</groupId>

src/main/java/ca/uhn/fhir/jpa/starter/AppProperties.java

@@ -21,9 +21,9 @@
 
 import static org.apache.commons.lang3.ObjectUtils.defaultIfNull;
 
+@EnableConfigurationProperties
 @ConfigurationProperties(prefix = "hapi.fhir")
 @Configuration
-@EnableConfigurationProperties
 public class AppProperties {
 
 	private final Set<String> auto_version_reference_at_paths = new HashSet<>();

src/main/java/ca/uhn/fhir/jpa/starter/mcp/CallToolResultFactory.java

@@ -0,0 +1,40 @@
+package ca.uhn.fhir.jpa.starter.mcp;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.spec.McpSchema;
+import org.springframework.stereotype.Component;
+
+import java.util.Map;
+
+@Component
+public class CallToolResultFactory {
+
+	public static McpSchema.CallToolResult success(
+			String resourceType, Interaction interaction, String response, int status) {
+		Map<String, Object> payload = Map.of(
+				"resourceType", resourceType,
+				"interaction", interaction,
+				"response", response,
+				"status", status);
+
+		ObjectMapper objectMapper = new ObjectMapper();
+		String jacksonData;
+		try {
+			jacksonData = objectMapper.writeValueAsString(payload);
+		} catch (JsonProcessingException e) {
+			throw new RuntimeException(e);
+		}
+
+		return McpSchema.CallToolResult.builder()
+				.addContent(new McpSchema.TextContent(jacksonData))
+				.build();
+	}
+
+	public static McpSchema.CallToolResult failure(String message) {
+		return McpSchema.CallToolResult.builder()
+				.isError(true)
+				.addTextContent(message)
+				.build();
+	}
+}

src/main/java/ca/uhn/fhir/jpa/starter/mcp/Interaction.java

@@ -0,0 +1,34 @@
+package ca.uhn.fhir.jpa.starter.mcp;
+
+import ca.uhn.fhir.rest.api.RequestTypeEnum;
+
+public enum Interaction {
+	CALL_CDS_HOOK("call-cds-hook"),
+	SEARCH("search"),
+	READ("read"),
+	CREATE("create"),
+	UPDATE("update"),
+	DELETE("delete"),
+	PATCH("patch"),
+	TRANSACTION("transaction");
+
+	private final String name;
+
+	Interaction(String name) {
+		this.name = name;
+	}
+
+	public String getName() {
+		return name;
+	}
+
+	public RequestTypeEnum asRequestType() {
+		return switch (this) {
+			case SEARCH, READ -> RequestTypeEnum.GET;
+			case CREATE, TRANSACTION, CALL_CDS_HOOK -> RequestTypeEnum.POST;
+			case UPDATE -> RequestTypeEnum.PUT;
+			case DELETE -> RequestTypeEnum.DELETE;
+			case PATCH -> RequestTypeEnum.PATCH;
+		};
+	}
+}

src/main/java/ca/uhn/fhir/jpa/starter/mcp/McpServerConfig.java

@@ -0,0 +1,81 @@
+package ca.uhn.fhir.jpa.starter.mcp;
+
+import ca.uhn.fhir.context.FhirContext;
+import ca.uhn.fhir.rest.server.McpBridge;
+import ca.uhn.fhir.rest.server.McpCdsBridge;
+import ca.uhn.fhir.rest.server.McpFhirBridge;
+import ca.uhn.fhir.rest.server.RestfulServer;
+import ca.uhn.hapi.fhir.cdshooks.api.ICdsServiceRegistry;
+import ca.uhn.hapi.fhir.cdshooks.module.CdsHooksObjectMapperFactory;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpSyncServer;
+import io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider;
+import io.modelcontextprotocol.spec.McpStreamableServerTransportProvider;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.web.servlet.ServletRegistrationBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.util.List;
+
+// https://mcp-cn.ssshooter.com/sdk/java/mcp-server#sse-servlet
+// https://www.baeldung.com/spring-ai-model-context-protocol-mcp
+// https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/manual-webflux-server/src/main/java/org/springframework/ai/mcp/sample/server/McpServerConfig.java
+// https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-stdio-server/src/main/java/org/springframework/ai/mcp/sample/server
+// https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/sampling/mcp-weather-webmvc-server/src/main/java/org/springframework/ai/mcp/sample/server/WeatherService.java
+// https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html
+@Configuration
+@ConditionalOnProperty(
+		prefix = "spring.ai.mcp.server",
+		name = {"enabled"},
+		havingValue = "true")
+public class McpServerConfig {
+
+	private static final String SSE_ENDPOINT = "/sse";
+	private static final String SSE_MESSAGE_ENDPOINT = "/mcp/message";
+
+	@Bean
+	public McpSyncServer syncServer(
+			List<McpBridge> mcpBridges, McpStreamableServerTransportProvider transportProvider) {
+		return McpServer.sync(transportProvider)
+				.tools(mcpBridges.stream()
+						.flatMap(bridge -> bridge.generateTools().stream())
+						.toList())
+				.build();
+	}
+
+	@Bean
+	public McpFhirBridge mcpFhirBridge(RestfulServer restfulServer) {
+		return new McpFhirBridge(restfulServer);
+	}
+
+	@Bean
+	@ConditionalOnProperty(
+			prefix = "hapi.fhir.cr",
+			name = {"enabled"},
+			havingValue = "true")
+	public McpCdsBridge mcpCdsBridge(FhirContext fhirContext, ICdsServiceRegistry cdsServiceRegistry) {
+
+		return new McpCdsBridge(
+				fhirContext, cdsServiceRegistry, new CdsHooksObjectMapperFactory(fhirContext).newMapper());
+	}
+
+	@Bean
+	public HttpServletStreamableServerTransportProvider servletSseServerTransportProvider(
+			/*McpServerProperties properties*/ ) {
+
+		return HttpServletStreamableServerTransportProvider.builder()
+				.disallowDelete(false)
+				.mcpEndpoint(SSE_MESSAGE_ENDPOINT)
+				.objectMapper(new ObjectMapper())
+				// .contextExtractor((serverRequest, context) -> context)
+				.build();
+	}
+
+	@Bean
+	public ServletRegistrationBean customServletBean(
+			HttpServletStreamableServerTransportProvider transportProvider /*, McpServerProperties properties*/) {
+		return new ServletRegistrationBean<>(transportProvider, SSE_MESSAGE_ENDPOINT, SSE_ENDPOINT);
+	}
+}

src/main/java/ca/uhn/fhir/jpa/starter/mcp/RequestBuilder.java

@@ -0,0 +1,120 @@
+package ca.uhn.fhir.jpa.starter.mcp;
+
+import ca.uhn.fhir.context.FhirContext;
+import com.google.gson.Gson;
+import org.hl7.fhir.instance.model.api.IBaseResource;
+import org.springframework.mock.web.MockHttpServletRequest;
+
+import java.nio.charset.StandardCharsets;
+import java.util.Map;
+
+public class RequestBuilder {
+
+	private final FhirContext fhirContext;
+	private final String resourceType;
+	private final Interaction interaction;
+	private final Map<String, Object> config;
+	/**
+	 * Constructs a RequestBuilder for a specific FHIR interaction.
+	 *
+	 * @param fhirContext the FHIR context
+	 * @param contextMap  a map containing configuration parameters, including 'resourceType'
+	 * @param interaction the type of interaction (e.g., SEARCH, READ, CREATE, etc.)
+	 */
+	public RequestBuilder(FhirContext fhirContext, Map<String, Object> contextMap, Interaction interaction) {
+		this.config = contextMap;
+		if (interaction == Interaction.TRANSACTION) this.resourceType = "";
+		else if (contextMap.get("resourceType") instanceof String rt && !rt.isBlank()) this.resourceType = rt;
+		else throw new IllegalArgumentException("Missing or invalid 'resourceType' in contextMap");
+
+		this.interaction = interaction;
+		this.fhirContext = fhirContext;
+	}
+
+	public MockHttpServletRequest buildRequest() {
+		String basePath = "/" + resourceType;
+		String method;
+		MockHttpServletRequest req;
+
+		switch (interaction) {
+			case SEARCH -> {
+				method = "GET";
+				req = new MockHttpServletRequest(method, basePath);
+				Map<?, ?> sp = null;
+				if (config.get("query") instanceof Map<?, ?> q) {
+					sp = q;
+				} else if (config.get("searchParams") instanceof Map<?, ?> s) {
+					sp = s;
+				}
+				if (sp != null) {
+					sp.forEach((k, v) -> req.addParameter(k.toString(), v.toString()));
+				}
+			}
+			case READ -> {
+				method = "GET";
+				String id = requireString();
+				req = new MockHttpServletRequest(method, basePath + "/" + id);
+			}
+			case CREATE, TRANSACTION -> {
+				method = "POST";
+				req = new MockHttpServletRequest(method, basePath);
+				applyResourceBody(req);
+			}
+			case UPDATE -> {
+				method = "PUT";
+				String id = requireString();
+				req = new MockHttpServletRequest(method, basePath + "/" + id);
+				applyResourceBody(req);
+			}
+			case DELETE -> {
+				method = "DELETE";
+				String id = requireString();
+				req = new MockHttpServletRequest(method, basePath + "/" + id);
+			}
+			case PATCH -> {
+				method = "PATCH";
+				String id = requireString();
+				req = new MockHttpServletRequest(method, basePath + "/" + id);
+				applyPatchBody(req);
+			}
+			default -> throw new IllegalArgumentException("Unsupported interaction: " + interaction);
+		}
+
+		req.setContentType("application/fhir+json");
+		req.addHeader("Accept", "application/fhir+json");
+		return req;
+	}
+
+	private void applyResourceBody(MockHttpServletRequest req) {
+		Object resourceObj = config.get("resource");
+		String json;
+		if (resourceObj instanceof Map<?, ?>) json = new Gson().toJson(resourceObj, Map.class);
+		else if (resourceObj instanceof String) json = resourceObj.toString();
+		else throw new IllegalArgumentException("Unsupported resource body type: " + resourceObj.getClass());
+		req.setContent(json.getBytes(StandardCharsets.UTF_8));
+	}
+
+	private void applyPatchBody(MockHttpServletRequest req) {
+		Object patchBody = config.get("resource");
+		if (patchBody == null) {
+			throw new IllegalArgumentException("Missing 'resource' for patch interaction");
+		}
+		String content;
+		if (patchBody instanceof String s) {
+			content = s;
+		} else if (patchBody instanceof IBaseResource r) {
+			content = fhirContext.newJsonParser().encodeResourceToString(r);
+		} else {
+			throw new IllegalArgumentException("Unsupported patch body type: " + patchBody.getClass());
+		}
+		req.setContent(content.getBytes(StandardCharsets.UTF_8));
+	}
+
+	private String requireString() {
+		Object val = config.get("id");
+		if (!(val instanceof String s) || s.isBlank()) {
+			throw new IllegalArgumentException("Missing or invalid '" + "id" + "'");
+		}
+		return s;
+	}
+}