diff --git a/README.md b/README.md index 4133b9a..d38005a 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,27 @@ -# Java & Spring MCP +# MCP Java SDK [![Build Status](https://github.com/modelcontextprotocol/java-sdk/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/modelcontextprotocol/java-sdk/actions/workflows/continuous-integration.yml) -Set of projects that provide Java SDK and Spring Framework integration for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture). +Set of projects that provide Java SDK integration for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture). It enables Java applications to interact with AI models and tools through a standardized interface, supporting both synchronous and asynchronous communication patterns. ## đź“š Reference Documentation -For comprehensive guides and API documentation, visit the [Spring AI MCP Reference Documentation](https://docs.spring.io/spring-ai-mcp/reference/overview.html). - +For comprehensive guides and API documentation, visit the [MCP Java SDK Reference Documentation](docs/docs/overview.mdx). - + + + ## Projects -### [MCP Java SDK](https://docs.spring.io/spring-ai-mcp/reference/mcp.html) +### MCP Java implementation of the Model Context Protocol specification. It includes: - Synchronous and asynchronous [MCP Client](https://docs.spring.io/spring-ai-mcp/reference/mcp.html#_mcp_client) and [MCP Server](https://docs.spring.io/spring-ai-mcp/reference/mcp.html#_mcp_server) implementations - Standard MCP operations support (tool discovery, resource management, prompt handling, structured logging). Support for request and notification handling. - [Stdio](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#stdio) and [SSE](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) transport implementations. -### MCP Transports +### MCP Spring #### Core Transports - Stdio-based (`StdioClientTransport`, `StdioServerTransport`) for process-based communication @@ -32,13 +33,6 @@ Java implementation of the Model Context Protocol specification. It includes: - [WebMvc SSE Transport](https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-spring/mcp-spring-webmvc) - Spring MVC based HTTP SSE transport (Server only). You can use the core `HttpClientSseClientTransport` transport as a SSE client. -### [Spring AI MCP](https://docs.spring.io/spring-ai-mcp/reference/spring-mcp.html) - -The Spring integration module provides Spring-specific functionality: -- Integration with Spring AI's function calling system -- Spring-friendly abstractions for MCP clients -- Auto-configurations (WIP) - ## Installation @@ -64,24 +58,6 @@ Add the following dependencies to your Maven project: ``` -This is a milestone release, not available on Maven Central. -Add this repository to your POM: - -```xml - - - spring-milestones - Spring Milestones - https://repo.spring.io/milestone - - false - - - -``` - -Reffer to the [Dependency Management](https://docs.spring.io/spring-ai-mcp/reference/dependency-management.html) page for more information. - ## Example Demos Explore these MCP examples in the [spring-ai-examples/model-context-protocol](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol) repository: diff --git a/docs/docs/dependency-management.mdx b/docs/docs/dependency-management.mdx index dbd69e4..6520721 100644 --- a/docs/docs/dependency-management.mdx +++ b/docs/docs/dependency-management.mdx @@ -64,41 +64,3 @@ The following dependencies are available and managed by the BOM: - `org.modelcontextprotocol.sdk:mcp-test` - Testing utilities and support for MCP-based applications. -### Milestone and Snapshot Repositories - -To use the Milestone and Snapshot version, you need to add references to the Spring Milestone and/or Snapshot repositories in your build file. -Add the following repository definitions to your Maven or Gradle build file: - - - -```xml - - - spring-milestones - Spring Milestones - https://repo.spring.io/milestone - - false - - - - spring-snapshots - Spring Snapshots - https://repo.spring.io/snapshot - - false - - - -``` - - - -```groovy -repositories { - maven { url 'https://repo.spring.io/milestone' } - maven { url 'https://repo.spring.io/snapshot' } -} -``` - - diff --git a/docs/docs/mcp-overview.mdx b/docs/docs/mcp-overview.mdx index 18ae2b7..d1d2742 100644 --- a/docs/docs/mcp-overview.mdx +++ b/docs/docs/mcp-overview.mdx @@ -7,8 +7,8 @@ description: Overview of the Model Context Protocol (MCP) architecture and key c Java SDK implementation of the [Model Context Protocol](https://modelcontextprotocol.io/introduction), enabling seamless integration with language models and AI tools. -![Spring AI MCP Client Architecture](/images/spring-ai-mcp-client-architecture.jpg) -![Spring AI MCP Server Architecture](/images/spring-ai-mcp-server-architecture.jpg) +![Spring AI MCP Client Architecture](/images/java-mcp-client-architecture.jpg) +![Spring AI MCP Server Architecture](/images/java-mcp-server-architecture.jpg) ## Features @@ -43,7 +43,7 @@ The SDK follows a layered architecture with clear separation of concerns: Following class diagram illustrates the layered architecture of the MCP SDK, showing the relationships between core interfaces (McpTransport, McpSession), their implementations, and the client/server components. It highlights how the transport layer connects to sessions, which in turn support both synchronous and asynchronous client/server implementations. -![MCP SDK Class Diagram](/images/spring-ai-mcp-uml-classdiagram.svg) +![MCP SDK Class Diagram](/images/java-mcp-uml-classdiagram.svg) Key Interactions: diff --git a/docs/docs/overview.mdx b/docs/docs/overview.mdx index 28d9e3d..e9c5e32 100644 --- a/docs/docs/overview.mdx +++ b/docs/docs/overview.mdx @@ -3,36 +3,12 @@ title: Overview description: Introduction to the Model Context Protocol (MCP) Java SDK --- -# Java & Spring MCP +# MCP Java SDK -Java SDK and Spring Framework integration for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture), enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication. +Java SDK for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture), enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication. -![Spring AI MCP Client Architecture](/images/spring-ai-mcp-client-architecture.jpg) -![Spring AI MCP Server Architecture](/images/spring-ai-mcp-server-architecture.jpg) - -## Core Components - -### [MCP Java SDK](/docs/mcp) -Core implementation of the Model Context Protocol specification, providing: - -- Synchronous and asynchronous [Client](/docs/mcp#mcp-client) and [Server](/docs/mcp#mcp-server) implementations -- Tool discovery and execution -- Resource management with URI templates -- Prompt handling and management -- Structured logging -- Request and Notification handling - -### MCP Transports - -#### Core Transports -- Stdio-based (`StdioClientTransport`, `StdioServerTransport`) for process-based communication -- Java HttpClient-based SSE client (`HttpClientSseClientTransport`) for HTTP SSE Client-side streaming -- Servlet-based SSE server (`HttpServletSseServerTransport`) for HTTP SSE Server streaming using traditional Servlet API - -#### Optional SSE Transports -- [WebFlux SSE Transport](https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-spring/mcp-spring-webflux) - Reactive HTTP streaming with Spring WebFlux (Client & Server) -- [WebMvc SSE Transport](https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-spring/mcp-spring-webmvc) - Spring MVC based SSE transport (Server only). -You can use the core `HttpClientSseClientTransport` transport as a SSE client. +![Java MCP Client Architecture](/images/java-mcp-client-architecture.jpg) +![Java MCP Server Architecture](/images/java-mcp-server-architecture.jpg) ## Getting Started diff --git a/docs/images/java-mcp-client-architecture.jpg b/docs/images/java-mcp-client-architecture.jpg new file mode 100644 index 0000000..688a2b4 Binary files /dev/null and b/docs/images/java-mcp-client-architecture.jpg differ diff --git a/docs/images/java-mcp-server-architecture.jpg b/docs/images/java-mcp-server-architecture.jpg new file mode 100644 index 0000000..4b05ca1 Binary files /dev/null and b/docs/images/java-mcp-server-architecture.jpg differ diff --git a/docs/images/spring-ai-mcp-uml-classdiagram.svg b/docs/images/java-mcp-uml-classdiagram.svg similarity index 100% rename from docs/images/spring-ai-mcp-uml-classdiagram.svg rename to docs/images/java-mcp-uml-classdiagram.svg diff --git a/docs/images/spring-ai-mcp-client-architecture.jpg b/docs/images/spring-ai-mcp-client-architecture.jpg deleted file mode 100644 index f858b8d..0000000 Binary files a/docs/images/spring-ai-mcp-client-architecture.jpg and /dev/null differ diff --git a/docs/images/spring-ai-mcp-server-architecture.jpg b/docs/images/spring-ai-mcp-server-architecture.jpg deleted file mode 100644 index c6ebea0..0000000 Binary files a/docs/images/spring-ai-mcp-server-architecture.jpg and /dev/null differ diff --git a/docs/mint.json b/docs/mint.json index 397b8c0..eb4ddaa 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -33,7 +33,7 @@ "docs/mcp-overview", "docs/mcp-client", "docs/mcp-server", - "docs/mcp-spring", + "docs/mcp-transport", "docs/mcp-capabilities" ] } diff --git a/mcp-bom/pom.xml b/mcp-bom/pom.xml index 26bfce4..6178bde 100644 --- a/mcp-bom/pom.xml +++ b/mcp-bom/pom.xml @@ -13,8 +13,8 @@ mcp-bom pom - Spring AI MCP BOM - Spring AI MCP Bill of Materials + Java SDK MCP BOM + Java SDK MCP Bill of Materials https://github.com/modelcontextprotocol/java-sdk diff --git a/mcp-docs/pom.xml b/mcp-docs/pom.xml deleted file mode 100644 index feac637..0000000 --- a/mcp-docs/pom.xml +++ /dev/null @@ -1,89 +0,0 @@ - - - - - 4.0.0 - - io.modelcontextprotocol.sdk - mcp-parent - 0.7.0-SNAPSHOT - - mcp-docs - Spring AI MCP Docs - Spring AI MCP documentation - - - - - org.antora - antora-maven-plugin - ${org.maven.antora-version} - true - - - - - - - src/main/antora/antora-playbook.yml - - @antora/cli@3.2.0-alpha.6 - @antora/atlas-extension@1.0.0-alpha.2 - @antora/collector-extension@1.0.0-beta.1 - @asciidoctor/tabs@1.0.0-beta.6 - @springio/antora-extensions@1.14.2 - @springio/asciidoctor-extensions@1.0.0-alpha.12 - @djencks/asciidoctor-mathjax@0.0.9 - - - - - io.spring.maven.antora - antora-component-version-maven-plugin - ${io.spring.maven.antora-version} - - - - antora-component-version - - - - - - org.apache.maven.plugins - maven-assembly-plugin - ${maven-assembly-plugin.version} - - - src/assembly/javadocs.xml - - mcp-${project.version} - true - - - - org.apache.maven.plugins - maven-deploy-plugin - ${maven-deploy-plugin.version} - - true - - - - - - \ No newline at end of file diff --git a/mcp-docs/src/assembly/javadocs.xml b/mcp-docs/src/assembly/javadocs.xml deleted file mode 100644 index a12b36e..0000000 --- a/mcp-docs/src/assembly/javadocs.xml +++ /dev/null @@ -1,31 +0,0 @@ - - - - docs - - zip - - false - - - ../target/site/apidocs - api - - - \ No newline at end of file diff --git a/mcp-docs/src/main/antora/antora-playbook.yml b/mcp-docs/src/main/antora/antora-playbook.yml deleted file mode 100644 index bb45a0b..0000000 --- a/mcp-docs/src/main/antora/antora-playbook.yml +++ /dev/null @@ -1,48 +0,0 @@ -# PACKAGES antora@3.2.0-alpha.6 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2 -# -# The purpose of this Antora playbook is to build the docs in the current branch. -antora: - extensions: - - '@antora/collector-extension' - # - require: '@springio/antora-extensions/root-component-extension' - - require: '@springio/antora-extensions' - root_component_name: 'ai' -site: - title: Spring AI Reference - url: https://docs.spring.io/spring-ai-mcp/reference - robots: allow -git: - ensure_git_suffix: false -content: - sources: - - url: ./../../../.. - branches: HEAD - start_path: mcp-docs/src/main/antora - worktrees: true -asciidoc: - attributes: - page-related-doc-categories: ai,java,ml,mcp - page-pagination: '' - hide-uri-scheme: '@' - tabs-sync-option: '@' - chomp: 'all' - stem: 'asciimath' - extensions: - - '@asciidoctor/tabs' - - '@springio/asciidoctor-extensions' - - '@springio/asciidoctor-extensions/javadoc-extension' - - '@springio/asciidoctor-extensions/include-code-extension' - - '@djencks/asciidoctor-mathjax' - sourcemap: true -urls: - latest_version_segment_strategy: redirect:to - latest_version_segment: '' - redirect_facility: httpd -runtime: - log: - failure_level: warn - format: pretty -ui: - bundle: - url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.4.17/ui-bundle.zip - snapshot: true \ No newline at end of file diff --git a/mcp-docs/src/main/antora/antora.yml b/mcp-docs/src/main/antora/antora.yml deleted file mode 100644 index 916c760..0000000 --- a/mcp-docs/src/main/antora/antora.yml +++ /dev/null @@ -1,12 +0,0 @@ -name: ai -version: true -title: Spring AI -nav: - - modules/ROOT/nav.adoc -ext: - collector: - - run: - command: mvnw process-resources - local: true - scan: - dir: mcp-docs/target/classes/antora-resources \ No newline at end of file diff --git a/mcp-docs/src/main/antora/modules/ROOT/images/class-diagrams.puml b/mcp-docs/src/main/antora/modules/ROOT/images/class-diagrams.puml deleted file mode 100644 index 5b08c73..0000000 --- a/mcp-docs/src/main/antora/modules/ROOT/images/class-diagrams.puml +++ /dev/null @@ -1,282 +0,0 @@ -@startuml Core Components - -' Core Interfaces -interface McpTransport { - +Mono connect(Function, Mono> handler) - +Mono sendMessage(JSONRPCMessage message) - +void close() - +Mono closeGracefully() - + T unmarshalFrom(Object data, TypeReference typeRef) -} - -interface McpSession { - + Mono sendRequest(String method, Object requestParams, TypeReference typeRef) - +Mono sendNotification(String method, Map params) - +Mono closeGracefully() - +void close() -} - -' Core Implementation Classes -class DefaultMcpSession { - +interface RequestHandler - +interface NotificationHandler -} - -' Client Classes -class McpClient { - +{static} Builder using(ClientMcpTransport transport) -} - -class McpAsyncClient { - +Mono initialize() - +ServerCapabilities getServerCapabilities() - +Implementation getServerInfo() - +ClientCapabilities getClientCapabilities() - +Implementation getClientInfo() - +void close() - +Mono closeGracefully() - +Mono ping() - +Mono addRoot(Root root) - +Mono removeRoot(String rootUri) - +Mono rootsListChangedNotification() - +Mono callTool(CallToolRequest request) - +Mono listTools() - +Mono listResources() - +Mono readResource(ReadResourceRequest request) - +Mono listResourceTemplates() - +Mono subscribeResource(SubscribeRequest request) - +Mono unsubscribeResource(UnsubscribeRequest request) - +Mono listPrompts() - +Mono getPrompt(GetPromptRequest request) - +Mono setLoggingLevel(LoggingLevel level) -} - -class McpSyncClient { - +InitializeResult initialize() - +ServerCapabilities getServerCapabilities() - +Implementation getServerInfo() - +ClientCapabilities getClientCapabilities() - +Implementation getClientInfo() - +void close() - +boolean closeGracefully() - +Object ping() - +void addRoot(Root root) - +void removeRoot(String rootUri) - +void rootsListChangedNotification() - +CallToolResult callTool(CallToolRequest request) - +ListToolsResult listTools() - +ListResourcesResult listResources() - +ReadResourceResult readResource(ReadResourceRequest request) - +ListResourceTemplatesResult listResourceTemplates() - +void subscribeResource(SubscribeRequest request) - +void unsubscribeResource(UnsubscribeRequest request) - +ListPromptsResult listPrompts() - +GetPromptResult getPrompt(GetPromptRequest request) - +void setLoggingLevel(LoggingLevel level) -} - -' Server Classes -class McpServer { - +{static} Builder using(ServerMcpTransport transport) -} - -class McpAsyncServer { - - +ServerCapabilities getServerCapabilities() - +Implementation getServerInfo() - +ClientCapabilities getClientCapabilities() - +Implementation getClientInfo() - +void close() - +Mono closeGracefully() - - ' Tool Management - +Mono addTool(ToolRegistration toolRegistration) - +Mono removeTool(String toolName) - +Mono notifyToolsListChanged() - - ' Resource Management - +Mono addResource(ResourceRegistration resourceHandler) - +Mono removeResource(String resourceUri) - +Mono notifyResourcesListChanged() - - ' Prompt Management - +Mono addPrompt(PromptRegistration promptRegistration) - +Mono removePrompt(String promptName) - +Mono notifyPromptsListChanged() - - ' Logging - +Mono loggingNotification(LoggingMessageNotification notification) - - ' Sampling - +Mono createMessage(CreateMessageRequest request) -} - -class McpSyncServer { - +McpAsyncServer getAsyncServer() - - +ServerCapabilities getServerCapabilities() - +Implementation getServerInfo() - +ClientCapabilities getClientCapabilities() - +Implementation getClientInfo() - +void close() - +void closeGracefully() - - ' Tool Management - +void addTool(ToolRegistration toolHandler) - +void removeTool(String toolName) - +void notifyToolsListChanged() - - ' Resource Management - +void addResource(ResourceRegistration resourceHandler) - +void removeResource(String resourceUri) - +void notifyResourcesListChanged() - - ' Prompt Management - +void addPrompt(PromptRegistration promptRegistration) - +void removePrompt(String promptName) - +void notifyPromptsListChanged() - - ' Logging - +void loggingNotification(LoggingMessageNotification notification) - - ' Sampling - +CreateMessageResult createMessage(CreateMessageRequest request) -} - -' Transport Implementations -class StdioClientTransport implements ClientMcpTransport { - +void setErrorHandler(Consumer errorHandler) - +Sinks.Many getErrorSink() -} - -class StdioServerTransport implements ServerMcpTransport { -} - - -class HttpServletSseServerTransport implements ServerMcpTransport { -} - - -class HttpClientSseClientTransport implements ClientMcpTransport { -} - - -class WebFluxSseClientTransport implements ClientMcpTransport { -} - - -class WebFluxSseServerTransport implements ServerMcpTransport { - +RouterFunction getRouterFunction() -} - -class WebMvcSseServerTransport implements ServerMcpTransport { - +RouterFunction getRouterFunction() -} - - -' Schema and Error Classes -class McpSchema { - +class ErrorCodes - +interface Request - +interface JSONRPCMessage - +interface ResourceContents - +interface Content - +interface ServerCapabilities - +{static} JSONRPCMessage deserializeJsonRpcMessage() -} - -class McpError { -} - -' Relationships -McpTransport <|.. ClientMcpTransport -McpTransport <|.. ServerMcpTransport - -McpSession <|.. DefaultMcpSession -DefaultMcpSession --o McpAsyncClient -DefaultMcpSession --o McpAsyncServer - -McpClient ..> McpAsyncClient : creates -McpClient ..> McpSyncClient : creates -McpSyncClient --> McpAsyncClient : delegates to - -McpServer ..> McpAsyncServer : creates -McpServer ..> McpSyncServer : creates -McpSyncServer o-- McpAsyncServer - -DefaultMcpSession o-- McpTransport -McpSchema <.. McpSession : uses -McpError ..> McpSession : throws - -@enduml - -@startuml Message Flow - -package "MCP Schema" { - interface JSONRPCMessage { - +String jsonrpc() - } - - interface Request { - } - - class InitializeRequest - class CallToolRequest - class ListToolsRequest - class ListResourcesRequest - class ReadResourceRequest - class ListResourceTemplatesRequest - class ListPromptsRequest - class GetPromptRequest -} - -package "Resource Types" { - interface ResourceContents { - +String uri() - +String mimeType() - } - - class TextResourceContents - class BlobResourceContents - - interface Content { - +String type() - } - - class TextContent - class ImageContent - class EmbeddedResource - - interface Annotated { - +Annotations annotations() - } - - interface PromptOrResourceReference { - +String type() - } - - class PromptReference - class ResourceReference -} - -JSONRPCMessage <|.. Request -Request <|.. InitializeRequest -Request <|.. CallToolRequest -Request <|.. ListToolsRequest -Request <|.. ListResourcesRequest -Request <|.. ReadResourceRequest -Request <|.. ListResourceTemplatesRequest -Request <|.. ListPromptsRequest -Request <|.. GetPromptRequest - -ResourceContents <|.. TextResourceContents -ResourceContents <|.. BlobResourceContents - -Content <|.. TextContent -Content <|.. ImageContent -Content <|.. EmbeddedResource - -PromptOrResourceReference <|.. PromptReference -PromptOrResourceReference <|.. ResourceReference - -@enduml diff --git a/mcp-docs/src/main/antora/modules/ROOT/images/mcp-stack.svg b/mcp-docs/src/main/antora/modules/ROOT/images/mcp-stack.svg deleted file mode 100644 index 3847eaa..0000000 --- a/mcp-docs/src/main/antora/modules/ROOT/images/mcp-stack.svg +++ /dev/null @@ -1,197 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/mcp-docs/src/main/antora/modules/ROOT/images/spring-ai-mcp-clinet-architecture.jpg b/mcp-docs/src/main/antora/modules/ROOT/images/spring-ai-mcp-clinet-architecture.jpg deleted file mode 100644 index f858b8d..0000000 Binary files a/mcp-docs/src/main/antora/modules/ROOT/images/spring-ai-mcp-clinet-architecture.jpg and /dev/null differ diff --git a/mcp-docs/src/main/antora/modules/ROOT/images/spring-ai-mcp-server-architecture.jpg b/mcp-docs/src/main/antora/modules/ROOT/images/spring-ai-mcp-server-architecture.jpg deleted file mode 100644 index c6ebea0..0000000 Binary files a/mcp-docs/src/main/antora/modules/ROOT/images/spring-ai-mcp-server-architecture.jpg and /dev/null differ diff --git a/mcp-docs/src/main/antora/modules/ROOT/images/spring-ai-mcp-uml-classdiagram.svg b/mcp-docs/src/main/antora/modules/ROOT/images/spring-ai-mcp-uml-classdiagram.svg deleted file mode 100644 index f83a586..0000000 --- a/mcp-docs/src/main/antora/modules/ROOT/images/spring-ai-mcp-uml-classdiagram.svg +++ /dev/null @@ -1 +0,0 @@ -McpTransportMono<Void> connect(Function<Mono<JSONRPCMessage>, Mono<JSONRPCMessage>> handler)Mono<Void> sendMessage(JSONRPCMessage message)void close()Mono<Void> closeGracefully()<T> T unmarshalFrom(Object data, TypeReference<T> typeRef)McpSession<T> Mono<T> sendRequest(String method, Object requestParams, TypeReference<T> typeRef)Mono<Void> sendNotification(String method, Map<String, Object> params)Mono<Void> closeGracefully()void close()DefaultMcpSessioninterface RequestHandlerinterface NotificationHandlerMcpClientBuilder using(ClientMcpTransport transport)McpAsyncClientMono<InitializeResult> initialize()ServerCapabilities getServerCapabilities()Implementation getServerInfo()ClientCapabilities getClientCapabilities()Implementation getClientInfo()void close()Mono<Void> closeGracefully()Mono<Object> ping()Mono<Void> addRoot(Root root)Mono<Void> removeRoot(String rootUri)Mono<Void> rootsListChangedNotification()Mono<CallToolResult> callTool(CallToolRequest request)Mono<ListToolsResult> listTools()Mono<ListResourcesResult> listResources()Mono<ReadResourceResult> readResource(ReadResourceRequest request)Mono<ListResourceTemplatesResult> listResourceTemplates()Mono<Void> subscribeResource(SubscribeRequest request)Mono<Void> unsubscribeResource(UnsubscribeRequest request)Mono<ListPromptsResult> listPrompts()Mono<GetPromptResult> getPrompt(GetPromptRequest request)Mono<Void> setLoggingLevel(LoggingLevel level)McpSyncClientInitializeResult initialize()ServerCapabilities getServerCapabilities()Implementation getServerInfo()ClientCapabilities getClientCapabilities()Implementation getClientInfo()void close()boolean closeGracefully()Object ping()void addRoot(Root root)void removeRoot(String rootUri)void rootsListChangedNotification()CallToolResult callTool(CallToolRequest request)ListToolsResult listTools()ListResourcesResult listResources()ReadResourceResult readResource(ReadResourceRequest request)ListResourceTemplatesResult listResourceTemplates()void subscribeResource(SubscribeRequest request)void unsubscribeResource(UnsubscribeRequest request)ListPromptsResult listPrompts()GetPromptResult getPrompt(GetPromptRequest request)void setLoggingLevel(LoggingLevel level)McpServerBuilder using(ServerMcpTransport transport)McpAsyncServerServerCapabilities getServerCapabilities()Implementation getServerInfo()ClientCapabilities getClientCapabilities()Implementation getClientInfo()void close()Mono<Void> closeGracefully() Mono<Void> addTool(ToolRegistration toolRegistration)Mono<Void> removeTool(String toolName)Mono<Void> notifyToolsListChanged() Mono<Void> addResource(ResourceRegistration resourceHandler)Mono<Void> removeResource(String resourceUri)Mono<Void> notifyResourcesListChanged() Mono<Void> addPrompt(PromptRegistration promptRegistration)Mono<Void> removePrompt(String promptName)Mono<Void> notifyPromptsListChanged() Mono<Void> loggingNotification(LoggingMessageNotification notification) Mono<CreateMessageResult> createMessage(CreateMessageRequest request)McpSyncServerMcpAsyncServer getAsyncServer() ServerCapabilities getServerCapabilities()Implementation getServerInfo()ClientCapabilities getClientCapabilities()Implementation getClientInfo()void close()void closeGracefully() void addTool(ToolRegistration toolHandler)void removeTool(String toolName)void notifyToolsListChanged() void addResource(ResourceRegistration resourceHandler)void removeResource(String resourceUri)void notifyResourcesListChanged() void addPrompt(PromptRegistration promptRegistration)void removePrompt(String promptName)void notifyPromptsListChanged() void loggingNotification(LoggingMessageNotification notification) CreateMessageResult createMessage(CreateMessageRequest request)StdioClientTransportvoid setErrorHandler(Consumer<String> errorHandler)Sinks.Many<String> getErrorSink()ClientMcpTransportStdioServerTransportServerMcpTransportHttpServletSseServerTransportHttpClientSseClientTransportWebFluxSseClientTransportWebFluxSseServerTransportRouterFunction<?> getRouterFunction()WebMvcSseServerTransportRouterFunction<?> getRouterFunction()McpSchemaclass ErrorCodesinterface Requestinterface JSONRPCMessageinterface ResourceContentsinterface Contentinterface ServerCapabilitiesJSONRPCMessage deserializeJsonRpcMessage()McpErrorcreatescreatesdelegates tocreatescreatesusesthrows \ No newline at end of file diff --git a/mcp-docs/src/main/antora/modules/ROOT/nav.adoc b/mcp-docs/src/main/antora/modules/ROOT/nav.adoc deleted file mode 100644 index 5edc6ee..0000000 --- a/mcp-docs/src/main/antora/modules/ROOT/nav.adoc +++ /dev/null @@ -1,3 +0,0 @@ -* xref:overview.adoc[Overview] -** xref:dependency-management.adoc[Dependency Management] -* xref:mcp.adoc[MCP Java SDK] diff --git a/mcp-docs/src/main/antora/modules/ROOT/pages/dependency-management.adoc b/mcp-docs/src/main/antora/modules/ROOT/pages/dependency-management.adoc deleted file mode 100644 index 517973c..0000000 --- a/mcp-docs/src/main/antora/modules/ROOT/pages/dependency-management.adoc +++ /dev/null @@ -1,109 +0,0 @@ -[[dependency-management]] -= Dependency Management - -[[mcp-bom]] -== Bill of Materials (BOM) - -The Bill of Materials (BOM) declares the recommended versions of all the dependencies used by a given release. -Using the BOM from your application’s build script avoids the need for you to specify and maintain the dependency versions yourself. -Instead, the version of the BOM you’re using determines the utilized dependency versions. -It also ensures that you’re using supported and tested versions of the dependencies by default, unless you choose to override them. - -Add the BOM to your project: - -[tabs] -====== -Maven:: -+ -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - io.modelcontextprotocol.sdk - mcp-bom - 0.6.0-SNAPSHOT - pom - import - - - ----- - -Gradle:: -+ -[source,groovy,indent=0,subs="verbatim,quotes"] ----- -dependencies { - implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.6.0-SNAPSHOT") - //... -} ----- -Gradle users can also use the Spring AI MCP BOM by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM. -This is implemented by adding a 'platform' dependency handler method to the dependencies section of your Gradle build script. -As shown in the snippet below this can then be followed by version-less declarations of the Starter Dependencies for the one or more spring-ai modules you wish to use, e.g. spring-ai-openai. -====== - -Replace the version number with the version of the BOM you want to use. - -[[dependencies]] -== Available Dependencies - -The following dependencies are available and managed by the BOM: - -=== Core Dependencies - -* `io.modelcontextprotocol.sdk:mcp` - Core MCP library providing the base functionality and APIs for Model Context Protocol implementation. - -=== Transport Dependencies - -* `io.modelcontextprotocol.sdk:mcp-spring-webflux` - WebFlux-based Server-Sent Events (SSE) transport implementation for reactive applications. -* `io.modelcontextprotocol.sdk:mcp-spring-webmvc` - WebMVC-based Server-Sent Events (SSE) transport implementation for servlet-based applications. - -=== Testing Dependencies - -* `io.modelcontextprotocol.sdk:mcp-test` - Testing utilities and support for MCP-based applications. - -[[repositories]] -=== Milestone and Snapshot Repositories - -To use the Milestone and Snapshot version, you need to add references to the Spring Milestone and/or Snapshot repositories in your build file. -Add the following repository definitions to your Maven or Gradle build file: - -[tabs] -====== -Maven:: -+ -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - spring-milestones - Spring Milestones - https://repo.spring.io/milestone - - false - - - - spring-snapshots - Spring Snapshots - https://repo.spring.io/snapshot - - false - - - ----- - -Gradle:: -+ -[source,groovy,indent=0,subs="verbatim,quotes"] ----- -repositories { - mavenCentral() - maven { url 'https://repo.spring.io/milestone' } - maven { url 'https://repo.spring.io/snapshot' } -} ----- -====== diff --git a/mcp-docs/src/main/antora/modules/ROOT/pages/mcp.adoc b/mcp-docs/src/main/antora/modules/ROOT/pages/mcp.adoc deleted file mode 100644 index 7a48722..0000000 --- a/mcp-docs/src/main/antora/modules/ROOT/pages/mcp.adoc +++ /dev/null @@ -1,675 +0,0 @@ -= Java MCP SDK - -Java SDK implementation of the link:https://modelcontextprotocol.io/introduction[Model Context Protocol], enabling seamless integration with language models and AI tools. - -== Features - -* Synchronous and Asynchronous MCP Client and MCP Server implementations -* Standard MCP operations support: -** Protocol link:https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#initialization[version compatibility negotiation] -** link:https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/[Tool] discovery, execution, list change notifications -** link:https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/[Resource] management with URI templates -** link:https://spec.modelcontextprotocol.io/specification/2024-11-05/client/roots/[Roots] list management and notifications -** link:https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/[Prompt] handling and management -** link:https://spec.modelcontextprotocol.io/specification/2024-11-05/client/sampling/[Sampling] support for AI model interactions -* Multiple transport implementations: -** Core transports: -*** Stdio-based transport for process-based communication -*** Java HttpClient-based SSE client transport for HTTP SSE Client-side streaming -*** Servlet-based SSE server transport for HTTP SSE Server streaming -** Spring-based transports: -*** WebFlux SSE transport for reactive HTTP streaming -*** WebMVC SSE transport for servlet-based HTTP streaming - -=== Dependencies - -Add the following dependency to your Maven project: - -[tabs] -====== -Maven:: -+ -The core MCP functionality: -+ -[source,xml] ----- - - io.modelcontextprotocol.sdk - mcp - ----- -+ -For HTTP SSE transport implementations, add one of the following dependencies -(Note that you already have HTTP Client SSE client transport in the core module): -+ -[source,xml] ----- - - - io.modelcontextprotocol.sdk - mcp-spring-webflux - - - - - io.modelcontextprotocol.sdk - mcp-spring-webmvc - ----- - -Gradle:: -+ -The core MCP functionality: -+ -[source,groovy] ----- -dependencies { - implementation 'io.modelcontextprotocol.sdk:mcp' -} ----- -+ -For HTTP SSE transport implementations, add one of the following dependencies -(note that you already have HTTP Client SSE client transport in the core module): -+ -[source,groovy] ----- -// Spring WebFlux-based SSE client and server transport -implementation 'io.modelcontextprotocol.sdk:mcp-spring-webflux' - -// Spring WebMVC-based SSE server transport -implementation 'io.modelcontextprotocol.sdk:mcp-spring-webmvc' ----- -====== - -Reffer to the xref:dependency-management.adoc[Dependency Management] page for more information. - -== Architecture - -image::mcp-stack.svg[width=400,float=right] - -The SDK follows a layered architecture with clear separation of concerns: - -* *Client/Server Layer*: Both use McpSession for sync/async operations, with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations. -* *Session Layer (McpSession)*: Manages communication patterns and state using DefaultMcpSession implementation. -* *Transport Layer (McpTransport)*: Handles JSON-RPC message serialization/deserialization via: -** StdioTransport (stdin/stdout) in the core module -** HTTP SSE transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC) - -Following class diagram illustrates the layered architecture of the MCP SDK, showing the relationships between core interfaces (McpTransport, McpSession), their implementations, and the client/server components. It highlights how the transport layer connects to sessions, which in turn support both synchronous and asynchronous client/server implementations. - -image::spring-ai-mcp-uml-classdiagram.svg[width=1000] - -Key Interactions: - -* *Client/Server Initialization*: Transport setup, protocol compatibility check, capability negotiation, and implementation details exchange. -* *Message Flow*: JSON-RPC message handling with validation, type-safe response processing, and error handling. -* *Resource Management*: Resource discovery, URI template-based access, subscription system, and content retrieval. -* *Prompt System*: Discovery, parameter-based retrieval, change notifications, and content management. -* *Tool Execution*: Discovery, parameter validation, timeout-aware execution, and result processing. - -[[mcp-client]] -== MCP Client - -The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling: - -* Protocol version negotiation to ensure compatibility with servers -* Capability negotiation to determine available features -* Message transport and JSON-RPC communication -* Tool discovery and execution -* Resource access and management -* Prompt system interactions -* Optional features like roots management and sampling support - -The client provides both synchronous and asynchronous APIs for flexibility in different application contexts. - -[tabs] -====== -Sync API:: -+ -[source,java] ----- -// Create a sync client with custom configuration -McpSyncClient client = McpClient.sync(transport) - .requestTimeout(Duration.ofSeconds(10)) - .capabilities(ClientCapabilities.builder() - .roots(true) // Enable roots capability - .sampling() // Enable sampling capability - .build()) - .sampling(request -> new CreateMessageResult(response)) - .build(); - -// Initialize connection -client.initialize(); - -// List available tools -ListToolsResult tools = client.listTools(); - -// Call a tool -CallToolResult result = client.callTool( - new CallToolRequest("calculator", - Map.of("operation", "add", "a", 2, "b", 3)) -); - -// List and read resources -ListResourcesResult resources = client.listResources(); -ReadResourceResult resource = client.readResource( - new ReadResourceRequest("resource://uri") -); - -// List and use prompts -ListPromptsResult prompts = client.listPrompts(); -GetPromptResult prompt = client.getPrompt( - new GetPromptRequest("greeting", Map.of("name", "Spring")) -); - -// Add/remove roots -client.addRoot(new Root("file:///path", "description")); -client.removeRoot("file:///path"); - -// Close client -client.closeGracefully(); ----- - -Async API:: -+ -[source,java] ----- -// Create an async client with custom configuration -McpAsyncClient client = McpClient.async(transport) - .requestTimeout(Duration.ofSeconds(10)) - .capabilities(ClientCapabilities.builder() - .roots(true) // Enable roots capability - .sampling() // Enable sampling capability - .build()) - .sampling(request -> Mono.just(new CreateMessageResult(response))) - .toolsChangeConsumer(tools -> Mono.fromRunnable(() -> { - logger.info("Tools updated: {}", tools); - })) - .resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> { - logger.info("Resources updated: {}", resources); - })) - .promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> { - logger.info("Prompts updated: {}", prompts); - })) - .build(); - -// Initialize connection -client.initialize() - .flatMap(initResult -> { - // List available tools - return client.listTools(); - }) - .flatMap(tools -> { - // Call a tool - return client.callTool(new CallToolRequest( - "calculator", - Map.of("operation", "add", "a", 2, "b", 3) - )); - }) - .flatMap(result -> { - // List and read resources - return client.listResources() - .flatMap(resources -> - client.readResource(new ReadResourceRequest("resource://uri")) - ); - }) - .flatMap(resource -> { - // List and use prompts - return client.listPrompts() - .flatMap(prompts -> - client.getPrompt(new GetPromptRequest( - "greeting", - Map.of("name", "Spring") - )) - ); - }) - .flatMap(prompt -> { - // Add/remove roots - return client.addRoot(new Root("file:///path", "description")) - .then(client.removeRoot("file:///path")); - }) - .doFinally(signalType -> { - // Close client - client.closeGracefully().subscribe(); - }) - .subscribe(); ----- -====== - -=== Client Transport - -The transport layer handles the communication between MCP clients and servers, providing different implementations for various use cases. The client transport manages message serialization, connection establishment, and protocol-specific communication patterns. - -[tabs] -====== -STDIO:: -+ -Creates transport for in-process based communication -+ -[source,java] ----- -ServerParameters params = ServerParameters.builder("npx") - .args("-y", "@modelcontextprotocol/server-everything", "dir") - .build(); -McpTransport transport = new StdioClientTransport(params); ----- -+ -SSE (HttpClient):: -+ -Creates a framework agnostic (pure Java API) SSE client transport. -Included in the core `mcp` module. -+ -[source,java] ----- -McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server"); ----- -+ -SSE (WebFlux):: -+ -Creates WebFlux-based SSE client transport. -Requires the `mcp-spring-webflux` dependency. -+ -[source,java] ----- -WebClient.Builder webClientBuilder = WebClient.builder() - .baseUrl("http://your-mcp-server"); -McpTransport transport = new WebFluxSseClientTransport(webClientBuilder); ----- -====== - -=== Client Capabilities - -The client can be configured with various capabilities: - -[source,java] ----- -var capabilities = ClientCapabilities.builder() - .roots(true) // Enable filesystem roots support with list changes notifications - .sampling() // Enable LLM sampling support - .build(); ----- - -==== Roots Support - -Roots define the boundaries of where servers can operate within the filesystem: - -[source,java] ----- -// Add a root dynamically -client.addRoot(new Root("file:///path", "description")); - -// Remove a root -client.removeRoot("file:///path"); - -// Notify server of roots changes -client.rootsListChangedNotification(); ----- - -The roots capability allows servers to: - -* Request the list of accessible filesystem roots -* Receive notifications when the root list changes -* Understand which directories and files they have access to - -==== Sampling Support - -Sampling enables servers to request LLM interactions ("completions" or "generations") through the client: - -[source,java] ----- -// Configure sampling handler -Function samplingHandler = request -> { - // Sampling implementation that interfaces with LLM - return new CreateMessageResult(response); -}; - -// Create client with sampling support -var client = McpClient.using(transport) - .capabilities(ClientCapabilities.builder() - .sampling() - .build()) - .sampling(samplingHandler) - .build(); ----- - -This capability allows: - -* Servers to leverage AI capabilities without requiring API keys -* Clients to maintain control over model access and permissions -* Support for both text and image-based interactions -* Optional inclusion of MCP server context in prompts - -[[mcp-server]] -== MCP Server - -The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients. It implements the server-side of the protocol, responsible for: - -* Exposing tools that clients can discover and execute -* Managing resources with URI-based access patterns -* Providing prompt templates and handling prompt requests -* Supporting capability negotiation with clients -* Implementing server-side protocol operations -* Managing concurrent client connections -* Providing structured logging and notifications - -The server supports both synchronous and asynchronous APIs, allowing for flexible integration in different application contexts. It can expose various capabilities such as file system operations, AI model interactions, and custom tool implementations. - -[tabs] -====== -Sync API:: -+ -[source,java] ----- -// Create a server with custom configuration -McpSyncServer syncServer = McpServer.sync(transport) - .serverInfo("my-server", "1.0.0") - .capabilities(ServerCapabilities.builder()...build()) - .tools(new McpServerFeatures.SyncToolRegistration(calculatorTool, calculatorHandler)) - .resources(new McpServerFeatures.SyncResourceRegistration(resource, resourceHandler)) - .prompts(new McpServerFeatures.SyncPromptRegistration(prompt, promptHandler)) - .build(); - -// Add a tool handler at runtime -syncServer.addTool(new CalculatorTool()); - -// Remove a tool handler at runtime -syncServer.removeTool("calculator"); - -// Add a resource at runtime -syncServer.addResource(resourceRegistration); - -// Remove a resource at runtime -syncServer.removeResource(resourceUri); - -// Add a prompt at runtime -syncServer.addPrompt(promptRegistration); - -// Remove a prompt at runtime -syncServer.removePrompt(promptName); - -// Graceful shutdown -syncServer.closeGracefully(); ----- - -Async API:: -+ -[source,java] ----- -// Create an async server with custom configuration -McpAsyncServer asyncServer = McpServer.async(transport) - .serverInfo("my-server", "1.0.0") - .capabilities(ServerCapabilities.builder()...build()) - .tools(new McpServerFeatures.AsyncToolRegistration(calculatorTool, args -> Mono.just(calculatorHandler.apply(args)))) - .resources(new McpServerFeatures.AsyncResourceRegistration(resource, req -> Mono.just(resourceHandler.apply(req)))) - .prompts(new McpServerFeatures.AsyncPromptRegistration(prompt, req -> Mono.just(promptHandler.apply(req)))) - .build(); - -// Add a tool handler at runtime -asyncServer.addTool(new CalculatorTool()) - .doOnSuccess(v -> logger.info("Tool added")) - .subscribe(); - -// Remove a tool handler at runtime -asyncServer.removeTool("calculator") - .doOnSuccess(v -> logger.info("Tool removed")) - .subscribe(); - -// Add a resource at runtime -asyncServer.addResource(resourceRegistration) - .doOnSuccess(v -> logger.info("Resource added")) - .subscribe(); - -// Remove a resource at runtime -asyncServer.removeResource(resourceUri) - .doOnSuccess(v -> logger.info("Resource removed")) - .subscribe(); - -// Add a prompt at runtime -asyncServer.addPrompt(promptRegistration) - .doOnSuccess(v -> logger.info("Prompt added")) - .subscribe(); - -// Remove a prompt at runtime -asyncServer.removePrompt(promptName) - .doOnSuccess(v -> logger.info("Prompt removed")) - .subscribe(); - -// Notify clients of changes -asyncServer.notifyToolsListChanged().subscribe(); -asyncServer.notifyResourcesListChanged().subscribe(); -asyncServer.notifyPromptsListChanged().subscribe(); - -// Graceful shutdown -asyncServer.closeGracefully().subscribe(); ----- -====== - -=== Server Transport - -The server transport layer implements the server-side communication protocols, enabling reliable message exchange with MCP clients. It provides implementations for different communication patterns while ensuring proper message handling, connection management, and protocol compliance. - -[tabs] -====== -STDIO:: -+ -Create in-process based transport -+ -[source,java] ----- -StdioServerTransport transport = new StdioServerTransport(new ObjectMapper()); ----- -+ -Provides bidirectional JSON-RPC message handling over standard input/output streams with non-blocking message processing, serialization/deserialization, and graceful shutdown support. - -SSE (WebFlux):: -+ -Creates WebFlux-based SSE server transport. -Requires the `mcp-spring-webflux` dependency. -+ -[source,java] ----- -@Configuration -class McpConfig { - @Bean - WebFluxSseServerTransport webFluxSseServerTransport(ObjectMapper mapper) { - return new WebFluxSseServerTransport(mapper, "/mcp/message"); - } - - @Bean - RouterFunction mcpRouterFunction(WebFluxSseServerTransport transport) { - return transport.getRouterFunction(); - } -} ----- -+ -Implements the MCP HTTP with SSE transport specification, providing: -+ -* Reactive HTTP streaming with WebFlux -* Concurrent client connections through SSE endpoints -* Message routing and session management -* Graceful shutdown capabilities - -SSE (WebMvc):: -+ -Creates WebMvc-based SSE server transport. -Requires the `mcp-spring-webmvc` dependency. -+ -[source,java] ----- -@Configuration -@EnableWebMvc -class McpConfig { - @Bean - WebMvcSseServerTransport webMvcSseServerTransport(ObjectMapper mapper) { - return new WebMvcSseServerTransport(mapper, "/mcp/message"); - } - - @Bean - RouterFunction mcpRouterFunction(WebMvcSseServerTransport transport) { - return transport.getRouterFunction(); - } -} ----- -+ -Implements the MCP HTTP with SSE transport specification, providing: -+ -* Servlet-based HTTP streaming with Spring MVC -* Concurrent client connections through SSE endpoints -* Message routing and session management -* Graceful shutdown capabilities - -SSE (Servlet):: -+ -Creates a Servlet-based SSE server transport. -Included in the core `mcp` module. -The `HttpServletSseServerTransport` can be used with any Servlet container. -To using it with a Spring Web application, you can register it as a Servlet bean: -+ -[source,java] ----- -@Configuration -@EnableWebMvc -public class McpServerConfig implements WebMvcConfigurer { - - @Bean - public HttpServletSseServerTransport servletSseServerTransport() { - return new HttpServletSseServerTransport(new ObjectMapper(), "/mcp/message"); - } - - @Bean - public ServletRegistrationBean customServletBean(HttpServletSseServerTransport servlet) { - return new ServletRegistrationBean(servlet); - } -} ----- -+ -(You can implment non Spring web container as well link:https://github.com/modelcontextprotocol/java-sdk/blob/main/mcp/src/test/java/org/springframework/ai/mcp/server/transport/HttpServletSseServerTransportIntegrationTests.java[HttpServletSseServerTransportIntegrationTests]) -+ -Implements the MCP HTTP with SSE transport specification using the traditional Servlet API, providing: -+ -* Asynchronous message handling using Servlet 6.0 async support -* Session management for multiple client connections -* Two types of endpoints: -** SSE endpoint (/sse) for server-to-client events -** Message endpoint (configurable) for client-to-server requests -* Error handling and response formatting -* Graceful shutdown support - -====== - -=== Server Capabilities - -The server can be configured with various capabilities: - -[source,java] ----- -var capabilities = ServerCapabilities.builder() - .resources(false, true) // Resource support with list changes notifications - .tools(true) // Tool support with list changes notifications - .prompts(true) // Prompt support with list changes notifications - .logging() // Enable logging support (enabled by default with loging level INFO) - .build(); ----- - -==== Logging Support - -The server provides structured logging capabilities that allow sending log messages to clients with different severity levels: - -[source,java] ----- -// Send a log message to clients -server.loggingNotification(LoggingMessageNotification.builder() - .level(LoggingLevel.INFO) - .logger("custom-logger") - .data("Custom log message") - .build()); ----- - -Clients can control the minimum logging level they receive through the `mcpClient.setLoggingLevel(level)` request. Messages below the set level will be filtered out. -Supported logging levels (in order of increasing severity): DEBUG (0), INFO (1), NOTICE (2), WARNING (3), ERROR (4), CRITICAL (5), ALERT (6), EMERGENCY (7) - - -==== Tool Registration - -[source,java] ----- -// Sync tool registration -var syncToolRegistration = new McpServerFeatures.SyncToolRegistration( - new Tool("calculator", "Basic calculator", Map.of( - "operation", "string", - "a", "number", - "b", "number" - )), - arguments -> { - // Tool implementation - return new CallToolResult(result, false); - } -); - -// Async tool registration -var asyncToolRegistration = new McpServerFeatures.AsyncToolRegistration( - new Tool("calculator", "Basic calculator", Map.of( - "operation", "string", - "a", "number", - "b", "number" - )), - arguments -> { - // Tool implementation - return Mono.just(new CallToolResult(result, false)); - } -); ----- - -==== Resource Registration - -[source,java] ----- -// Sync resource registration -var syncResourceRegistration = new McpServerFeatures.SyncResourceRegistration( - new Resource("custom://resource", "name", "description", "mime-type", null), - request -> { - // Resource read implementation - return new ReadResourceResult(contents); - } -); - -// Async resource registration -var asyncResourceRegistration = new McpServerFeatures.AsyncResourceRegistration( - new Resource("custom://resource", "name", "description", "mime-type", null), - request -> { - // Resource read implementation - return Mono.just(new ReadResourceResult(contents)); - } -); ----- - -==== Prompt Registration - -[source,java] ----- -// Sync prompt registration -var syncPromptRegistration = new McpServerFeatures.SyncPromptRegistration( - new Prompt("greeting", "description", List.of( - new PromptArgument("name", "description", true) - )), - request -> { - // Prompt implementation - return new GetPromptResult(description, messages); - } -); - -// Async prompt registration -var asyncPromptRegistration = new McpServerFeatures.AsyncPromptRegistration( - new Prompt("greeting", "description", List.of( - new PromptArgument("name", "description", true) - )), - request -> { - // Prompt implementation - return Mono.just(new GetPromptResult(description, messages)); - } -); ----- - -== Error Handling - -The SDK provides comprehensive error handling through the McpError class, covering protocol compatibility, transport communication, JSON-RPC messaging, tool execution, resource management, prompt handling, timeouts, and connection issues. This unified error handling approach ensures consistent and reliable error management across both synchronous and asynchronous operations. diff --git a/mcp-docs/src/main/antora/modules/ROOT/pages/overview.adoc b/mcp-docs/src/main/antora/modules/ROOT/pages/overview.adoc deleted file mode 100644 index 9dc040b..0000000 --- a/mcp-docs/src/main/antora/modules/ROOT/pages/overview.adoc +++ /dev/null @@ -1,126 +0,0 @@ -= Java & Spring MCP - -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-clinet-architecture.jpg[Spring AI MCP Client Architecture,600,float="right",align="left"] -image::spring-ai-mcp-server-architecture.jpg[Spring AI MCP Server Architecture,600,align="right"] - -== Core Components - -=== xref:mcp.adoc[MCP Java SDK] -Core implementation of the Model Context Protocol specification, providing: - -* 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 - -=== MCP Transports - -* *Core Transports* -** Stdio-based (`StdioClientTransport`, `StdioServerTransport`) for process-based communication -** Java HttpClient-based SSE client (`HttpClientSseClientTransport`) for HTTP SSE Client-side streaming -** Servlet-based SSE server (`HttpServletSseServerTransport`) for HTTP SSE Server streaming using traditional Servlet API - -* *Optional SSE Transports* -** link:https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-spring/mcp-spring-webflux[WebFlux SSE Transport] - Reactive HTTP streaming with Spring WebFlux (Client & Server) -** link:https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-spring/mcp-spring-webmvc[WebMvc SSE Transport] - Spring MVC based SSE transport (Server only). -You can use the core `HttpClientSseClientTransport` transport as a SSE client. - -== Getting Started - -[tabs] -====== -Maven:: -+ -[source,xml] ----- - - - io.modelcontextprotocol.sdk - mcp - - - - - io.modelcontextprotocol.sdk - mcp-spring-webflux - - - - - io.modelcontextprotocol.sdk - mcp-spring-webmvc - - ----- -+ -Add Spring milestone repository: -+ -[source,xml] ----- - - - spring-milestones - Spring Milestones - https://repo.spring.io/milestone - - false - - - ----- - -Gradle:: -+ -[source,groovy] ----- -dependencies { - implementation 'io.modelcontextprotocol.sdk:mcp' // Core - implementation 'io.modelcontextprotocol.sdk:mcp-spring-webflux' // Optional - implementation 'io.modelcontextprotocol.sdk:mcp-spring-webmvc' // Optional -} - -repositories { - maven { url 'https://repo.spring.io/milestone' } -} ----- -====== - -Reffer to the xref:dependency-management.adoc[Dependency Management] page for more information. - -== Examples - -* 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 -* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-servlet-server[Servlet SSE] - SSE Servlet server with HttpClient implementation - -== Documentation - -* xref:mcp.adoc[Java MCP SDK Documentation] -* xref:spring-mcp.adoc[Spring Integration Documentation] - -== Development - -Build from source: -[source,bash] ----- -mvn clean install ----- - -Run tests: -[source,bash] ----- -mvn test ----- - -== License - -This project is licensed under the link:LICENSE[MIT]. diff --git a/mcp-docs/src/main/antora/resources/antora-resources/antora.yml b/mcp-docs/src/main/antora/resources/antora-resources/antora.yml deleted file mode 100644 index 99706e0..0000000 --- a/mcp-docs/src/main/antora/resources/antora-resources/antora.yml +++ /dev/null @@ -1,2 +0,0 @@ -version: ${antora-component.version} -prerelease: ${antora-component.prerelease} \ No newline at end of file diff --git a/mcp-docs/src/main/javadoc/overview.html b/mcp-docs/src/main/javadoc/overview.html deleted file mode 100644 index 9dabad0..0000000 --- a/mcp-docs/src/main/javadoc/overview.html +++ /dev/null @@ -1,33 +0,0 @@ - - - - -

- This document is the API specification for MCP Java SDK -

-
-

- For further API reference and developer documentation, see the - - Spring AI MCP reference documentation. - That documentation contains more detailed, developer-targeted - descriptions, with conceptual overviews, definitions of terms, - and working code examples. -

-
- - \ No newline at end of file diff --git a/pom.xml b/pom.xml index 0edd15f..835735a 100644 --- a/pom.xml +++ b/pom.xml @@ -98,7 +98,6 @@ mcp mcp-spring/mcp-spring-webflux mcp-spring/mcp-spring-webmvc - mcp-test @@ -352,14 +351,6 @@ true - - spring-milestones - Spring Milestones - https://repo.spring.io/milestone - - false - - \ No newline at end of file