feat: Add MCP server with Server stdio/sse transport improve MCP client
- Implement MCP server with async/sync support and builder pattern configuration - Add Server stdio/SSE transport layers with robust error handling - Convert McpClient and McpServer to interfaces for better extensibility - Add sampling capabilities for LLM interactions (text/image) - Implement dynamic root management and runtime tool management - Add comprehensive prompt and resource capabilities - Add support for dynamic root management (add/remove roots at runtime) Architecture Changes - Introduce registration records for tools, resources, and prompts - Improve thread safety with concurrent collections - Enhance resource template handling - Implement builder patterns for Server/Client capabilities - Add support for server capabilities and implementation info Transport Layer: - Implement SseServerTransport with SSE endpoints - Add StdioServerTransport for process-based communication - Reorganize transport packages for better organization - Improve transport error handling and shutdown processes Documentation: - Add detailed MCP reference documentation - Include architecture diagrams and API documentation - Add comprehensive test coverage for all components - Include sample projects demonstrating stdio/SSE transports BREAKING CHANGES: Transport Package Reorganization - Move StdioClientTransport to o.s.ai.mcp.client.transport - Move SseClientTransport to o.s.ai.mcp.client.transport - Move ServerParameters to o.s.ai.mcp.client.transport - StdioClientTransport.errorHandler changed to private with setter method Migration: Use setErrorHandler() method instead of direct field access API Changes - Replace static factory methods with builder pattern - Update ServerCapabilities to use builder pattern - Make StdioClientTransport.errorHandler private with setter - Replace rootsListProvider with direct root management - Remove deprecated static factory methods Resolves #27,#25,#24,#11 Related to #12
This commit is contained in:
Christian Tzolov
parent
c83a45f880
commit
abd0facf4e
1 changed files with 5727 additions and 471 deletions
162
docs/ref-server.md
Normal file
162
docs/ref-server.md
Normal file
|
|
@ -0,0 +1,162 @@
|
|||
# MCP Server Reference
|
||||
|
||||
## McpServer Factory
|
||||
|
||||
`org.springframework.ai.mcp.server.McpServer`
|
||||
|
||||
The `McpServer` class serves as a factory for creating Model Context Protocol (MCP) servers. It provides the main entry point for establishing MCP servers, offering both synchronous and asynchronous server implementations.
|
||||
|
||||
### Overview
|
||||
|
||||
The server factory uses a builder pattern for flexible configuration, allowing you to customize various aspects of the server including server information, capabilities, tools, resource providers, and prompt providers.
|
||||
|
||||
### Server Types
|
||||
|
||||
The factory can create two types of servers:
|
||||
- `McpAsyncServer` for non-blocking operations
|
||||
- `McpSyncServer` for blocking operations
|
||||
|
||||
### Builder Configuration
|
||||
|
||||
#### Basic Usage
|
||||
```java
|
||||
McpServer.using(transport)
|
||||
.serverInfo("my-server", "1.0.0")
|
||||
.addTool(new MyToolHandler())
|
||||
.async(); // or .sync()
|
||||
```
|
||||
|
||||
#### Builder Methods
|
||||
|
||||
##### using(McpTransport transport)
|
||||
```java
|
||||
public static Builder using(McpTransport transport)
|
||||
```
|
||||
Start building an MCP server with the specified transport.
|
||||
|
||||
##### serverInfo(Implementation serverInfo)
|
||||
```java
|
||||
public Builder serverInfo(McpSchema.Implementation serverInfo)
|
||||
```
|
||||
Set the server implementation information.
|
||||
|
||||
##### serverInfo(String name, String version)
|
||||
```java
|
||||
public Builder serverInfo(String name, String version)
|
||||
```
|
||||
Set the server implementation information using name and version.
|
||||
|
||||
##### serverCapabilities(ServerCapabilities capabilities)
|
||||
```java
|
||||
public Builder serverCapabilities(McpSchema.ServerCapabilities serverCapabilities)
|
||||
```
|
||||
Set the server capabilities configuration.
|
||||
|
||||
##### addTool(ToolHandler handler)
|
||||
```java
|
||||
public <T extends McpAsyncServer.ToolHandler> Builder addTool(T toolHandler)
|
||||
```
|
||||
Add a tool handler to the server.
|
||||
|
||||
##### tool(Tool tool, Function<Map<String, Object>, CallToolResult> handler)
|
||||
```java
|
||||
public Builder tool(McpSchema.Tool tool, Function<Map<String, Object>, McpSchema.CallToolResult> handler)
|
||||
```
|
||||
Add a tool with its handler function.
|
||||
|
||||
##### addTools(List<ToolHandler> handlers)
|
||||
```java
|
||||
public Builder addTools(List<ToolHandler> toolHandlers)
|
||||
```
|
||||
Add multiple tool handlers to the server.
|
||||
|
||||
##### resourcesProvider(Function<String, List<Resource>> provider)
|
||||
```java
|
||||
public Builder resourcesProvider(Function<String, List<McpSchema.Resource>> resourcesProvider)
|
||||
```
|
||||
Set the resources provider function.
|
||||
|
||||
##### promptsProvider(Function<String, List<Prompt>> provider)
|
||||
```java
|
||||
public Builder promptsProvider(Function<String, List<McpSchema.Prompt>> promptsProvider)
|
||||
```
|
||||
Set the prompts provider function.
|
||||
|
||||
##### sync()
|
||||
```java
|
||||
public McpSyncServer sync()
|
||||
```
|
||||
Build and return a synchronous MCP server.
|
||||
|
||||
##### async()
|
||||
```java
|
||||
public AsyncServerBuilder async()
|
||||
```
|
||||
Build and return an asynchronous server builder.
|
||||
|
||||
### Usage Examples
|
||||
|
||||
#### Creating a Basic Server
|
||||
```java
|
||||
McpTransport transport = // obtain transport instance
|
||||
McpServer.using(transport)
|
||||
.serverInfo("my-server", "1.0.0")
|
||||
.sync();
|
||||
```
|
||||
|
||||
#### Creating a Server with Tools
|
||||
```java
|
||||
McpServer.using(transport)
|
||||
.serverInfo("calculation-server", "1.0.0")
|
||||
.tool(
|
||||
new McpSchema.Tool("calculate", "Performs calculations", Map.of(
|
||||
"operation", Map.of("type", "string"),
|
||||
"numbers", Map.of("type", "array")
|
||||
)),
|
||||
args -> {
|
||||
// Handle calculation
|
||||
return new McpSchema.CallToolResult(/* result */);
|
||||
}
|
||||
)
|
||||
.async();
|
||||
```
|
||||
|
||||
#### Creating a Server with Resources and Prompts
|
||||
```java
|
||||
McpServer.using(transport)
|
||||
.serverInfo("content-server", "1.0.0")
|
||||
.resourcesProvider(cursor -> {
|
||||
// Return list of resources based on cursor
|
||||
return List.of(/* resources */);
|
||||
})
|
||||
.promptsProvider(cursor -> {
|
||||
// Return list of prompts based on cursor
|
||||
return List.of(/* prompts */);
|
||||
})
|
||||
.sync();
|
||||
```
|
||||
|
||||
### Implementation Notes
|
||||
|
||||
- The server factory uses a builder pattern for configuration
|
||||
- Default server info is "mcp-server" version "1.0.0" if not specified
|
||||
- Tool handlers must be thread-safe as they may be called concurrently
|
||||
- The synchronous server is implemented as a wrapper around the asynchronous server
|
||||
- Resource and prompt providers use cursor-based pagination
|
||||
- The AsyncServerBuilder allows adding tools after server creation
|
||||
|
||||
### Tool Handler Interface
|
||||
|
||||
```java
|
||||
public interface ToolHandler {
|
||||
String getName();
|
||||
String getDescription();
|
||||
Map<String, Object> getInputSchema();
|
||||
McpSchema.CallToolResult call(Map<String, Object> arguments);
|
||||
}
|
||||
```
|
||||
|
||||
Tool handlers implement this interface to define:
|
||||
- Tool name and description
|
||||
- Input schema for validation
|
||||
- Execution logic in the call method
|
||||
Loading…
Reference in a new issue