From fbcd51b3322c113f498e89baa2831a6a63fdbb7e Mon Sep 17 00:00:00 2001 From: Christian Tzolov Date: Sun, 12 Jan 2025 09:18:54 +0100 Subject: [PATCH] docs: improve documentation clarity and add WebFlux SSE transport example - Streamline overview documentation structure and content - Consolidate installation instructions - Simplify examples section descriptions - Add WebFlux SSE transport dependency and configuration example --- .../antora/modules/ROOT/pages/overview.adoc | 131 ++++++------------ .../mcp-webflux-sse-transport/README.md | 55 ++++++++ 2 files changed, 95 insertions(+), 91 deletions(-) diff --git a/mcp-docs/src/main/antora/modules/ROOT/pages/overview.adoc b/mcp-docs/src/main/antora/modules/ROOT/pages/overview.adoc index dc077ce..f38e3bd 100644 --- a/mcp-docs/src/main/antora/modules/ROOT/pages/overview.adoc +++ b/mcp-docs/src/main/antora/modules/ROOT/pages/overview.adoc @@ -1,92 +1,72 @@ = Java & Spring MCP -Set of tools to provide Java SDK and Spring Framework integration for the link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol]. -It enables Java applications to interact with AI models and tools through a standardized interface, supporting both synchronous and asynchronous communication patterns. +Java SDK and Spring Framework integration for the link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol], enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication. image::spring-ai-mcp-architecture.png[Spring AI MCP Architecture,600] -== Projects - -There are two main projects in this repository: +== Core Components === xref:mcp.adoc[MCP Java SDK] +Core implementation of the Model Context Protocol specification, providing: -Java implementation of the Model Context Protocol specification. It includes: +* Synchronous and asynchronous xref:mcp.adoc#mcp-client[Client] and xref:mcp.adoc#mcp-server[Server] implementations +* Tool discovery and execution +* Resource management with URI templates +* Prompt handling and management +* Structured logging +* Request and Notification handling -* Synchronous and asynchronous xref:mcp.adoc#mcp-client[MCP Client] and xref:mcp.adoc#mcp-server[MCP Server] implementations -* Standard MCP operations support: -** Tool discovery and execution -** Resource management with URI templates -** Prompt handling and management -** Structured logging -** Request and notification handling -* Multiple transport implementations: -** Core transports: -*** Stdio-based transport for process-based communication -*** Java HttpClient-based SSE transport for HTTP streaming -** Spring-based transports: -*** WebFlux SSE transport for reactive HTTP streaming -*** WebMVC SSE transport for servlet-based HTTP streaming +=== MCP Transports -==== WebFlux SSE Transport -The link:https://github.com/spring-projects-experimental/spring-ai-mcp/tree/main/mcp-transport/mcp-webflux-sse-transport[mcp-webflux-sse-transport] project provides WebFlux-based implementation for the SSE client and server transports, enabling reactive HTTP streaming with Spring WebFlux. +* *Core Transports* +** Stdio-based (`StdioClientTransport`, `StdioServerTransport`) for process-based communication +** Java HttpClient-based SSE client (`HttpClientSseClientTransport`) for HTTP streaming -==== WebMvc SSE Transport -The link:https://github.com/spring-projects-experimental/spring-ai-mcp/tree/main/mcp-transport/mcp-webmvc-sse-transport[mcp-webmvc-sse-transport] project provides WebMvc-based implementation for the SSE server transport. The core module's HttpClientSseClientTransport can be used for client-side communication. +* *Optional SSE Transports* +** link:https://github.com/spring-projects-experimental/spring-ai-mcp/tree/main/mcp-transport/mcp-webflux-sse-transport[WebFlux SSE Transport] - Reactive HTTP streaming with Spring WebFlux (Client & Server) +** link:https://github.com/spring-projects-experimental/spring-ai-mcp/tree/main/mcp-transport/mcp-webmvc-sse-transport[WebMvc SSE Transport] - Servlet-based HTTP streaming (Server only). +Use the core `HttpClientSseClientTransport` for SSE clients. === xref:spring-mcp.adoc[Spring AI MCP] +Spring integration features: -The Spring integration module provides Spring-specific functionality: - -* Integration with Spring AI's function calling system +* Spring AI tool/function calling system integration * Bidirectional conversion between Spring AI function callbacks and MCP tools * JSON schema generation for tool input validation * Automatic type conversion and error handling -* Spring-friendly abstractions for MCP clients +* Spring-friendly MCP client abstractions * Auto-configurations (WIP) == Installation -Add the following dependencies to your Maven project: - [tabs] ====== Maven:: + -The core MCP functionality: -+ [source,xml] ---- + org.springframework.experimental mcp 0.5.0-SNAPSHOT ----- -+ -For HTTP SSE transport implementations, add one or more of the following dependencies: -+ -[source,xml] ----- - + + org.springframework.experimental mcp-webflux-sse-transport 0.5.0-SNAPSHOT - + org.springframework.experimental mcp-webmvc-sse-transport 0.5.0-SNAPSHOT ----- -+ -For Spring AI integration: -+ -[source,xml] ----- + + org.springframework.experimental spring-ai-mcp @@ -94,8 +74,7 @@ For Spring AI integration: ---- + -This is a milestone release, not available on Maven Central. -Add the Spring milestone repository to your POM: +Add Spring milestone repository: + [source,xml] ---- @@ -113,40 +92,15 @@ Add the Spring milestone repository to your POM: Gradle:: + -The core MCP functionality: -+ [source,groovy] ---- dependencies { - implementation 'org.springframework.experimental:mcp' + implementation 'org.springframework.experimental:mcp' // Core + implementation 'org.springframework.experimental:mcp-webflux-sse-transport' // Optional + implementation 'org.springframework.experimental:mcp-webmvc-sse-transport' // Optional + implementation 'org.springframework.experimental:spring-ai-mcp' // Optional } ----- -+ -For HTTP SSE transport implementations, add one or more of the following dependencies: -+ -[source,groovy] ----- -// Spring WebFlux-based SSE client and server transport -implementation 'org.springframework.experimental:mcp-webflux-sse-transport' -// Spring WebMVC-based SSE server transport -implementation 'org.springframework.experimental:mcp-webmvc-sse-transport' ----- -+ -For Spring AI integration: -+ -[source,groovy] ----- -dependencies { - implementation 'org.springframework.experimental:spring-ai-mcp' -} ----- -+ -This is a milestone release, not available on Maven Central. -Add the Spring milestone repository to your build: -+ -[source,groovy] ----- repositories { maven { url 'https://repo.spring.io/milestone' } } @@ -155,16 +109,13 @@ repositories { == Examples -Explore these MCP examples in the link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol[spring-ai-examples/model-context-protocol] repository: - -* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/simple[SQLite Simple] - Demonstrates LLM integration with a database -* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/chatbot[SQLite Chatbot] - Interactive chatbot with SQLite database interaction -* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/filesystem[Filesystem] - Enables LLM interaction with local filesystem folders and files -* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/brave[Brave] - Enables natural language interactions with Brave Search -* link:https://github.com/habuma/spring-ai-examples/tree/main/spring-ai-mcp[Theme Park API Example] - Shows how to create an MCP server and client with Spring AI, exposing Theme Park API tools -* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webflux-server[WebFlux SSE Client + WebFlux SSE Server sample] - Showcases how to create and use MCP WebFlux servers and clients with different capabilities -* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webmvc-server[Http SSE Client + WebMvc SSE Server sample] - Showcases how to create and use MCP WebMvc servers and HttpClient clients with different capabilities - +* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/simple[SQLite Simple] - Basic LLM-database integration +* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/chatbot[SQLite Chatbot] - Interactive database chatbot +* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/filesystem[Filesystem] - LLM interaction with local files +* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/brave[Brave] - Natural language Brave Search integration +* link:https://github.com/habuma/spring-ai-examples/tree/main/spring-ai-mcp[Theme Park API] - MCP server/client with Theme Park API tools +* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webflux-server[WebFlux SSE] - WebFlux server/client implementation +* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-webmvc-server[WebMvc SSE] - WebMvc server with HttpClient implementation == Documentation @@ -173,15 +124,13 @@ Explore these MCP examples in the link:https://github.com/spring-projects/spring == Development -=== Building from Source - +Build from source: [source,bash] ---- mvn clean install ---- -=== Running Tests - +Run tests: [source,bash] ---- mvn test diff --git a/mcp-transport/mcp-webflux-sse-transport/README.md b/mcp-transport/mcp-webflux-sse-transport/README.md index d60d62b..dd14397 100644 --- a/mcp-transport/mcp-webflux-sse-transport/README.md +++ b/mcp-transport/mcp-webflux-sse-transport/README.md @@ -1 +1,56 @@ # WebFlux SSE Transport + +```xml + + org.springframework.experimental + mcp-webflux-sse-transport + 0.5.0-SNAPSHOT + +``` + +```java +String MESSAGE_ENDPOINT = "/mcp/message"; + +@Configuration +static class MyConfig { + + // SSE transport + @Bean + public WebFluxSseServerTransport sseServerTransport() { + return new WebFluxSseServerTransport(new ObjectMapper(), "/mcp/message"); + } + + // Router function for SSE transport used by Spring WebFlux to start an HTTP + // server. + @Bean + public RouterFunction mcpRouterFunction(WebFluxSseServerTransport transport) { + return transport.getRouterFunction(); + } + + @Bean + public McpAsyncServer mcpServer(ServerMcpTransport transport, OpenLibrary openLibrary) { + + // Configure server capabilities with resource support + var capabilities = McpSchema.ServerCapabilities.builder() + .resources(false, true) // No subscribe support, but list changes notifications + .tools(true) // Tool support with list changes notifications + .prompts(true) // Prompt support with list changes notifications + .logging() // Logging support + .build(); + + // Create the server with both tool and resource capabilities + var server = McpServer.using(transport) + .serverInfo("MCP Demo Server", "1.0.0") + .capabilities(capabilities) + .resources(systemInfoResourceRegistration()) + .prompts(greetingPromptRegistration()) + .tools(openLibraryToolRegistrations(openLibrary)) + .async(); + + return server; + } + + // ... + +} +```