Start of some examples of using this library

mcp-examples/mcp-stateless-server/README.md

@@ -0,0 +1,39 @@
+# Example Stateless MCP HTTP Server
+
+This an example of sync stateless MCP HTTP server. It shows how to set up
+some simple tools, prompts, and resources as well as accessing the HTTP request
+from handlers.
+
+The actual server implementation is Jetty but any servlet container could be used.
+
+- See [Tools](src/main/java/io/modelcontextprotocol/examples/stateless/server/Tools.java) for the test tools. 
+The tool `requestHeader` shows how to access the HTTP request headers.
+- See [Prompts](src/main/java/io/modelcontextprotocol/examples/stateless/server/Prompts.java) for the test prompt.
+- See [Resources](src/main/java/io/modelcontextprotocol/examples/stateless/server/Resources.java) for the test resource.
+
+## How to run
+
+1. Build the project:
+
+```shell
+./mvnw clean install
+```
+
+2. Run this server example:
+
+```shell
+./mvnw -pl :mcp-stateless-server exec:java -Dexec.mainClass="io.modelcontextprotocol.examples.stateless.server.Main"
+```
+
+3. In a separate terminal, run the MCP inspector:
+
+```shell
+npx @modelcontextprotocol/inspector
+```
+
+A browser should open with the MCP Inspector tool:
+- Set the "Transport Type" to "Streamable HTTP"
+- Change the URL to `http://localhost:8080/mcp`
+- Click "Connect"
+
+Try out the tools, prompts, and resources in the MCP Inspector.

mcp-examples/mcp-stateless-server/pom.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.modelcontextprotocol.sdk</groupId>
+        <artifactId>mcp-examples</artifactId>
+        <version>0.12.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>mcp-stateless-server</artifactId>
+    <packaging>jar</packaging>
+    <name>Examples for the Java MCP SDK</name>
+    <description>Provides some examples for the MCP Java SDK</description>
+    <url>https://github.com/modelcontextprotocol/java-sdk</url>
+
+    <scm>
+        <url>https://github.com/modelcontextprotocol/java-sdk</url>
+        <connection>git://github.com/modelcontextprotocol/java-sdk.git</connection>
+        <developerConnection>git@github.com/modelcontextprotocol/java-sdk.git</developerConnection>
+    </scm>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <version>${jackson.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>jakarta.servlet</groupId>
+            <artifactId>jakarta.servlet-api</artifactId>
+            <version>${jakarta.servlet.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.eclipse.jetty</groupId>
+            <artifactId>jetty-server</artifactId>
+            <version>11.0.20</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.eclipse.jetty</groupId>
+            <artifactId>jetty-servlet</artifactId>
+            <version>11.0.20</version>
+        </dependency>
+    </dependencies>
+</project>

mcp-examples/mcp-stateless-server/src/main/java/io/modelcontextprotocol/examples/stateless/server/JettyServer.java

@@ -0,0 +1,34 @@
+package io.modelcontextprotocol.examples.stateless.server;
+
+import jakarta.servlet.http.HttpServlet;
+import org.eclipse.jetty.server.Server;
+import org.eclipse.jetty.servlet.ServletContextHandler;
+import org.eclipse.jetty.servlet.ServletHolder;
+
+public class JettyServer implements AutoCloseable {
+
+	private final Server server;
+
+	public JettyServer(HttpServlet servlet, int port) {
+		server = new Server(port);
+
+		ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
+		context.setContextPath("/");
+		server.setHandler(context);
+
+		context.addServlet(new ServletHolder(servlet), "/mcp");
+
+		try {
+			server.start();
+		}
+		catch (Exception e) {
+			throw new RuntimeException(e);
+		}
+	}
+
+	@Override
+	public void close() throws Exception {
+		server.stop();
+	}
+
+}

mcp-examples/mcp-stateless-server/src/main/java/io/modelcontextprotocol/examples/stateless/server/Main.java

@@ -0,0 +1,40 @@
+package io.modelcontextprotocol.examples.stateless.server;
+
+import io.modelcontextprotocol.server.McpStatelessSyncServer;
+import io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities.PromptCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities.ResourceCapabilities;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities.ToolCapabilities;
+
+public class Main {
+
+	@SuppressWarnings("CallToPrintStackTrace")
+	public static void main(String[] args) {
+		HttpServletStatelessServerTransport transport = McpServerBuilder.buildTransport();
+
+		PromptCapabilities promptCapabilities = new PromptCapabilities(false);
+		ResourceCapabilities resourceCapabilities = new ResourceCapabilities(false, false);
+		ToolCapabilities toolCapabilities = new ToolCapabilities(false);
+
+		McpStatelessSyncServer mcpServer = McpServerBuilder.buildServer(transport,
+				new ServerCapabilities(null, null, null, promptCapabilities, resourceCapabilities, toolCapabilities),
+				"test", "1.0", "For testing");
+
+		mcpServer.addTool(Tools.addTwoNumbers);
+		mcpServer.addTool(Tools.requestHeader);
+		mcpServer.addPrompt(Prompts.greetingPrompt);
+		mcpServer.addResource(Resources.testResources);
+
+		try (var ignore = new JettyServer(transport, 8080)) {
+			Thread.currentThread().join();
+		}
+		catch (InterruptedException e) {
+			throw new RuntimeException(e);
+		}
+		catch (Exception e) {
+			e.printStackTrace();
+		}
+	}
+
+}

mcp-examples/mcp-stateless-server/src/main/java/io/modelcontextprotocol/examples/stateless/server/McpServerBuilder.java

@@ -0,0 +1,38 @@
+package io.modelcontextprotocol.examples.stateless.server;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.modelcontextprotocol.server.McpServer;
+import io.modelcontextprotocol.server.McpStatelessSyncServer;
+import io.modelcontextprotocol.server.transport.HttpServletStatelessServerTransport;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpStatelessServerTransport;
+
+public interface McpServerBuilder {
+
+	String CONTEXT_REQUEST_KEY = McpServerBuilder.class.getName() + ".request";
+
+	ObjectMapper MAPPER = new ObjectMapper();
+
+	static HttpServletStatelessServerTransport buildTransport() {
+		return HttpServletStatelessServerTransport.builder()
+			.messageEndpoint("/mcp")
+			.objectMapper(MAPPER)
+			.contextExtractor((request, transportContext) -> {
+				transportContext.put(CONTEXT_REQUEST_KEY, request);
+				return transportContext;
+			})
+			.build();
+	}
+
+	static McpStatelessSyncServer buildServer(McpStatelessServerTransport transport,
+			McpSchema.ServerCapabilities serverCapabilities, String serverName, String serverVersion,
+			String instructions) {
+		return McpServer.sync(transport)
+			.objectMapper(MAPPER)
+			.capabilities(serverCapabilities)
+			.serverInfo(serverName, serverVersion)
+			.instructions(instructions)
+			.build();
+	}
+
+}

mcp-examples/mcp-stateless-server/src/main/java/io/modelcontextprotocol/examples/stateless/server/Prompts.java

@@ -0,0 +1,25 @@
+package io.modelcontextprotocol.examples.stateless.server;
+
+import io.modelcontextprotocol.server.McpStatelessServerFeatures.SyncPromptSpecification;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
+import io.modelcontextprotocol.spec.McpSchema.Prompt;
+import io.modelcontextprotocol.spec.McpSchema.PromptMessage;
+import io.modelcontextprotocol.spec.McpSchema.TextContent;
+
+import java.util.List;
+
+import static io.modelcontextprotocol.spec.McpSchema.Role.USER;
+
+public interface Prompts {
+
+	SyncPromptSpecification greetingPrompt = new SyncPromptSpecification(
+			new Prompt("greeting", "Greeting Prompt",
+					List.of(new McpSchema.PromptArgument("name", "Name of the person to greet", true))),
+			(transportContext, getPromptRequest) -> {
+				String name = String.valueOf(getPromptRequest.arguments().get("name"));
+				return new GetPromptResult("greeting",
+						List.of(new PromptMessage(USER, new TextContent("Hello " + name + "!"))));
+			});
+
+}

mcp-examples/mcp-stateless-server/src/main/java/io/modelcontextprotocol/examples/stateless/server/Resources.java

@@ -0,0 +1,24 @@
+package io.modelcontextprotocol.examples.stateless.server;
+
+import io.modelcontextprotocol.server.McpStatelessServerFeatures.SyncResourceSpecification;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.ReadResourceResult;
+import io.modelcontextprotocol.spec.McpSchema.Resource;
+
+import java.util.List;
+
+public interface Resources {
+
+	SyncResourceSpecification testResources = new SyncResourceSpecification(
+			Resource.builder()
+				.name("test")
+				.uri("https://modelcontextprotocol.io")
+				.description("A test resource")
+				.mimeType("text/plain")
+				.size(10L)
+				.build(),
+			(transportContext, readResourceRequest) -> new ReadResourceResult(
+					List.of(new McpSchema.TextResourceContents("https://modelcontextprotocol.io", "text/plain",
+							"0123456789"))));
+
+}

mcp-examples/mcp-stateless-server/src/main/java/io/modelcontextprotocol/examples/stateless/server/Tools.java

@@ -0,0 +1,67 @@
+package io.modelcontextprotocol.examples.stateless.server;
+
+import io.modelcontextprotocol.server.McpStatelessServerFeatures.SyncToolSpecification;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
+import io.modelcontextprotocol.spec.McpSchema.JSONRPCResponse.JSONRPCError;
+import jakarta.servlet.http.HttpServletRequest;
+
+import static io.modelcontextprotocol.examples.stateless.server.McpServerBuilder.CONTEXT_REQUEST_KEY;
+import static io.modelcontextprotocol.spec.McpSchema.ErrorCodes.INVALID_REQUEST;
+
+public interface Tools {
+
+	String addTwoNumbersSchemaJson = """
+			{
+				"type": "object",
+				"properties": {
+					"a": {
+						"type": "integer"
+					},
+					"b": {
+						"type": "integer"
+					}
+				},
+				"required": ["a", "b"]
+			}
+			""";
+
+	String requestHeaderSchemaJson = """
+			{
+				"type": "object",
+				"properties": {
+					"headerName": {
+						"type": "string"
+					}
+				},
+				"required": ["headerName"]
+			}
+			""";
+
+	SyncToolSpecification addTwoNumbers = SyncToolSpecification.builder()
+		.tool(McpSchema.Tool.builder().name("add").inputSchema(addTwoNumbersSchemaJson).build())
+		.callHandler((transportContext, callToolRequest) -> {
+			int a = Integer.parseInt(String.valueOf(callToolRequest.arguments().get("a")));
+			int b = Integer.parseInt(String.valueOf(callToolRequest.arguments().get("b")));
+
+			return new CallToolResult(String.valueOf(a + b), null);
+		})
+		.build();
+
+	SyncToolSpecification requestHeader = SyncToolSpecification.builder()
+		.tool(McpSchema.Tool.builder().name("requestHeader").inputSchema(requestHeaderSchemaJson).build())
+		.callHandler((transportContext, callToolRequest) -> {
+			HttpServletRequest request = (HttpServletRequest) transportContext.get(CONTEXT_REQUEST_KEY);
+			String headerName = String.valueOf(callToolRequest.arguments().get("headerName"));
+
+			String value = request.getHeader(headerName);
+			if (value == null) {
+				throw new McpError(new JSONRPCError(INVALID_REQUEST, "Header '" + headerName + "' not found", null));
+			}
+
+			return new CallToolResult(value, null);
+		})
+		.build();
+
+}

mcp-examples/pom.xml

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.modelcontextprotocol.sdk</groupId>
+        <artifactId>mcp-parent</artifactId>
+        <version>0.12.0-SNAPSHOT</version>
+    </parent>
+    <artifactId>mcp-examples</artifactId>
+    <packaging>pom</packaging>
+    <name>Examples for the Java MCP SDK</name>
+    <description>Provides some examples for the MCP Java SDK</description>
+    <url>https://github.com/modelcontextprotocol/java-sdk</url>
+    <modules>
+        <module>mcp-stateless-server</module>
+    </modules>
+
+    <scm>
+        <url>https://github.com/modelcontextprotocol/java-sdk</url>
+        <connection>git://github.com/modelcontextprotocol/java-sdk.git</connection>
+        <developerConnection>git@github.com/modelcontextprotocol/java-sdk.git</developerConnection>
+    </scm>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.modelcontextprotocol.sdk</groupId>
+            <artifactId>mcp</artifactId>
+            <version>0.12.0-SNAPSHOT</version>
+        </dependency>
+    </dependencies>
+</project>

pom.xml

@@ -106,7 +106,8 @@
 		<module>mcp-spring/mcp-spring-webflux</module>
 		<module>mcp-spring/mcp-spring-webmvc</module>
 		<module>mcp-test</module>
-	</modules>
+        <module>mcp-examples</module>
+    </modules>
 
 	<build>
 		<plugins>