java-sdk/spring-ai-mcp-sample/README.md

Spring AI MCP Sample Project

This sample project demonstrates the usage of the Spring AI Model Context Protocol (MCP) implementation. It showcases how to create and use MCP servers and clients with different transport modes and capabilities.

Overview

The sample provides:

• Two transport mode implementations: Stdio and SSE (Server-Sent Events)
• Server capabilities:
  • Tools support with list changes notifications
  • Resources support with list changes notifications (no subscribe support)
  • Prompts support with list changes notifications
• Sample implementations:
  • Two MCP tools: Weather and Calculator
  • One MCP resource: System Information
  • One MCP prompt: Greeting

Building the Project

./mvnw clean package

Running the Server

The server can be started in two transport modes, controlled by the transport.mode property:

Stdio Mode (Default)

java -Dtransport.mode=stdio -jar target/spring-ai-mcp-sample-0.3.0-SNAPSHOT.jar

The Stdio mode server is automatically started by the client - no explicit server startup is needed. But you have to build the server jar first: ./mvnw clean install -DskipTests.

In Stdio mode the server must not emit any messages/logs to the console (e.g. standard out) but the JSON messages produced by the server.

SSE Mode

java -Dtransport.mode=sse -jar target/spring-ai-mcp-sample-0.3.0-SNAPSHOT.jar

Sample Clients

The project includes example clients for both transport modes:

Stdio Client (ClientStdio.java)

var stdioParams = ServerParameters.builder("java")
    .args("-Dtransport.mode=stdio", "-jar",
            "target/spring-ai-mcp-sample-0.3.0-SNAPSHOT.jar")
    .build();

var transport = new StdioClientTransport(stdioParams);
var client = McpClient.using(transport).sync();

SSE Client (ClientSse.java)

var transport = new SseClientTransport(WebClient.builder().baseUrl("http://localhost:8080"));
var client = McpClient.using(transport).sync();

Available Tools

Weather Tool

• Name: weather
• Description: Weather forecast tool by location
• Parameters:
  • city: String - The city to get weather for
• Example:

CallToolResult response = client.callTool(
    new CallToolRequest("weather", Map.of("city", "Sofia"))
);

Calculator Tool

• Name: calculator
• Description: Performs basic arithmetic operations
• Parameters (JSON Schema):

  {
    "operation": {
      "type": "string",
      "enum": ["add", "subtract", "multiply", "divide"],
      "description": "The arithmetic operation to perform"
    },
    "a": {
      "type": "number",
      "description": "First operand"
    },
    "b": {
      "type": "number",
      "description": "Second operand"
    }
  }
  

• Example:

CallToolResult response = client.callTool(
    new CallToolRequest("calculator", 
        Map.of("operation", "multiply", "a", 2.0, "b", 3.0))
);

Available Resources

System Information Resource

• URI: system://info
• Description: Provides basic system information including Java version, OS, etc.
• MIME Type: application/json
• Returns: JSON object containing: javaVersion, osName, osVersion, osArch, processors, timestamp

Available Prompts

Greeting Prompt

• Name: greeting
• Description: A friendly greeting prompt
• Parameters:
  • name: String (required) - The name to greet
• Returns: A personalized greeting message from an assistant

Client Usage Example

// Initialize client
client.initialize();

// Test connection
client.ping();

// List available tools
ListToolsResult tools = client.listTools();
System.out.println("Available tools: " + tools);

// Call weather tool
CallToolResult weather = client.callTool(
    new CallToolRequest("weather", Map.of("city", "Sofia"))
);
System.out.println("Weather: " + weather);

// Call calculator tool
CallToolResult calc = client.callTool(
    new CallToolRequest("calculator", 
        Map.of("operation", "multiply", "a", 2.0, "b", 3.0))
);
System.out.println("Calculation: " + calc);

// Access system info resource
ReadResourceResult sysInfo = client.readResource(
    new ReadResourceRequest("system://info")
);
System.out.println("System Info: " + sysInfo);

// Use greeting prompt
GetPromptResult greeting = client.getPrompt(
    new GetPromptRequest("greeting", Map.of("name", "John"))
);
System.out.println("Greeting: " + greeting);

// Close client
client.closeGracefully();

Server Usage Example

@Configuration
public class CustomMcpServerConfig {
    @Bean
    public McpAsyncServer mcpServer(McpTransport transport) {
        // Configure server capabilities
        var capabilities = McpSchema.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
            .build();

        // Create custom tool
        var customTool = new ToolRegistration(
            new McpSchema.Tool("custom-tool", "Description", Map.of("param", "String")),
            (arguments) -> {
                String param = (String) arguments.get("param");
                return new CallToolResult(
                    List.of(new TextContent("Result: " + param)),
                    false
                );
            }
        );

        // Create custom resource
        var customResource = new ResourceRegistration(
            new McpSchema.Resource(
                "custom://resource",
                "Custom Resource",
                "Description",
                "application/json",
                null
            ),
            (request) -> new ReadResourceResult(
                List.of(new TextResourceContents(
                    request.uri(),
                    "application/json",
                    "{\"data\": \"example\"}"
                ))
            )
        );

        // Create custom prompt
        var customPrompt = new PromptRegistration(
            new McpSchema.Prompt(
                "custom-prompt",
                "Description",
                List.of(new McpSchema.PromptArgument("input", "Description", true))
            ),
            request -> {
                String input = (String) request.arguments().get("input");
                var message = new PromptMessage(
                    Role.ASSISTANT,
                    new TextContent("Response to: " + input)
                );
                return new GetPromptResult("Result", List.of(message));
            }
        );

        // Create and configure the server
        return McpServer.using(transport)
            .info("Custom MCP Server", "1.0.0")
            .capabilities(capabilities)
            .tools(List.of(customTool))
            .resources(Map.of("custom://resource", customResource))
            .prompts(List.of(customPrompt))
            .async();
    }
}

Configuration

The application can be configured through application.properties:

• transport.mode: Transport mode to use (stdio/sse)
• server.port: Server port for SSE mode (default: 8080)
• Various logging configurations are available for debugging

Implementation Details

The sample demonstrates:

• Creating an MCP server with custom tools, resources, and prompts
• Configuring different transport modes
• Implementing tool handlers with JSON schema validation
• Resource implementations with dynamic content generation
• Prompt implementations with parameter handling
• Error handling and response formatting
• Synchronous client usage patterns