feat(mcp): Add native MCP server implementation with calculator tool example and docs

Author: AgentScope Developer

agentscope-core/pom.xml

@@ -84,6 +84,12 @@
             <artifactId>jackson-datatype-jsr310</artifactId>
         </dependency>
 
+        <!-- Jackson Java 8 Optional support -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.datatype</groupId>
+            <artifactId>jackson-datatype-jdk8</artifactId>
+        </dependency>
+
         <!-- SLF4J API -->
         <dependency>
             <groupId>org.slf4j</groupId>

agentscope-core/src/main/java/io/agentscope/core/mcp/handler/AbstractMethodHandler.java

@@ -0,0 +1,46 @@
+package io.agentscope.core.mcp.handler;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.agentscope.core.mcp.message.JsonRpcError;
+import io.agentscope.core.mcp.message.JsonRpcMessage;
+import io.agentscope.core.mcp.message.JsonRpcNotification;
+import io.agentscope.core.mcp.message.JsonRpcRequest;
+import io.agentscope.core.mcp.message.JsonRpcResponse;
+import io.agentscope.core.mcp.transport.TransportException;
+
+/**
+ * Abstract base class for method handlers.
+ *
+ * <p>Provides common logic for handling requests and notifications.
+ */
+public abstract class AbstractMethodHandler implements MethodHandler {
+
+    protected ObjectMapper objectMapper = new ObjectMapper();
+
+    @Override
+    public JsonRpcResponse handleMessage(JsonRpcMessage message) throws TransportException {
+        try {
+            if (message instanceof JsonRpcRequest) {
+                JsonRpcRequest request = (JsonRpcRequest) message;
+                Object result = handle(request.getParams());
+                return new JsonRpcResponse(request.getId().orElse(null), result);
+            } else if (message instanceof JsonRpcNotification) {
+                JsonRpcNotification notification = (JsonRpcNotification) message;
+                handle(notification.getParams());
+                return null; // Notifications don't require responses
+            }
+            throw new TransportException("Unknown message type: " + message.getClass());
+        } catch (Exception e) {
+            if (message instanceof JsonRpcRequest) {
+                JsonRpcRequest request = (JsonRpcRequest) message;
+                JsonRpcError error =
+                        new JsonRpcError(
+                                JsonRpcError.ErrorCode.INTERNAL_ERROR,
+                                "Internal server error: " + e.getMessage(),
+                                e.toString());
+                return new JsonRpcResponse(request.getId().orElse(null), error);
+            }
+            throw new TransportException("Error handling notification", e);
+        }
+    }
+}

agentscope-core/src/main/java/io/agentscope/core/mcp/handler/CallToolHandler.java

@@ -0,0 +1,65 @@
+package io.agentscope.core.mcp.handler;
+
+import io.agentscope.core.mcp.schema.CallToolResult;
+import io.agentscope.core.mcp.tool.Tool;
+import io.agentscope.core.mcp.tool.ToolManager;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * Handler for `tools/call` requests. Looks up a registered server-side Tool and executes it.
+ */
+public class CallToolHandler extends AbstractMethodHandler {
+
+    private final ToolManager toolManager;
+
+    public CallToolHandler(ToolManager toolManager) {
+        this.toolManager = toolManager;
+    }
+
+    @Override
+    public String getMethod() {
+        return "tools/call";
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public Object handle(Object params) throws Exception {
+        if (!(params instanceof Map)) {
+            throw new IllegalArgumentException("Invalid params for tools/call");
+        }
+        Map<String, Object> map = (Map<String, Object>) params;
+        String name = (String) map.get("name");
+        Object arguments = map.get("arguments");
+
+        if (name == null || name.isBlank()) {
+            throw new IllegalArgumentException("Tool name is required");
+        }
+
+        Optional<Tool> toolOpt = toolManager.get(name);
+        if (toolOpt.isEmpty()) {
+            throw new IllegalArgumentException("Tool not found: " + name);
+        }
+
+        Tool tool = toolOpt.get();
+        Object result = tool.execute(arguments);
+
+        // Normalize result into a content block list. Always wrap in a text block.
+        Map<String, Object> block = new HashMap<>();
+        block.put("type", "text");
+        String text;
+        if (result instanceof String) {
+            text = (String) result;
+        } else {
+            text = objectMapper.writeValueAsString(result == null ? "" : result);
+        }
+        block.put("text", text);
+        List<Object> content = new ArrayList<>();
+        content.add(block);
+
+        return new CallToolResult(content, Optional.empty());
+    }
+}

agentscope-core/src/main/java/io/agentscope/core/mcp/handler/HandlerRegistry.java

@@ -0,0 +1,70 @@
+package io.agentscope.core.mcp.handler;
+
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Registry for MCP method handlers.
+ *
+ * <p>Stores and retrieves handlers by method name.
+ */
+public class HandlerRegistry {
+
+    private final Map<String, MethodHandler> handlers = new ConcurrentHashMap<>();
+
+    /**
+     * Register a handler for a method.
+     *
+     * @param method the method name
+     * @param handler the handler
+     */
+    public void register(String method, MethodHandler handler) {
+        handlers.put(method, handler);
+    }
+
+    /**
+     * Get a handler for a method.
+     *
+     * @param method the method name
+     * @return the handler, or empty if not found
+     */
+    public Optional<MethodHandler> get(String method) {
+        return Optional.ofNullable(handlers.get(method));
+    }
+
+    /**
+     * Check if a handler is registered for a method.
+     *
+     * @param method the method name
+     * @return true if handler exists
+     */
+    public boolean has(String method) {
+        return handlers.containsKey(method);
+    }
+
+    /**
+     * Unregister a handler for a method.
+     *
+     * @param method the method name
+     */
+    public void unregister(String method) {
+        handlers.remove(method);
+    }
+
+    /**
+     * Get all registered method names.
+     *
+     * @return set of method names
+     */
+    public Map<String, MethodHandler> getAll() {
+        return new ConcurrentHashMap<>(handlers);
+    }
+
+    /**
+     * Clear all handlers.
+     */
+    public void clear() {
+        handlers.clear();
+    }
+}

agentscope-core/src/main/java/io/agentscope/core/mcp/handler/InitializeHandler.java

@@ -0,0 +1,36 @@
+package io.agentscope.core.mcp.handler;
+
+import io.agentscope.core.mcp.schema.InitializeResult;
+import io.agentscope.core.mcp.tool.ToolManager;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Handler for `initialize` requests (handshake).
+ */
+public class InitializeHandler extends AbstractMethodHandler {
+
+    private final ToolManager toolManager;
+
+    public InitializeHandler(ToolManager toolManager) {
+        this.toolManager = toolManager;
+    }
+
+    @Override
+    public String getMethod() {
+        return "initialize";
+    }
+
+    @Override
+    public Object handle(Object params) throws Exception {
+        Map<String, Object> capabilities = new HashMap<>();
+        capabilities.put("tools", new HashMap<>());
+        capabilities.put("protocol", "mcp");
+
+        Map<String, Object> serverInfo = new HashMap<>();
+        serverInfo.put("name", "agentscope-core");
+        serverInfo.put("version", "0.1.0");
+
+        return new InitializeResult(capabilities, "2.0", serverInfo);
+    }
+}

agentscope-core/src/main/java/io/agentscope/core/mcp/handler/ListToolsHandler.java

@@ -0,0 +1,41 @@
+package io.agentscope.core.mcp.handler;
+
+import io.agentscope.core.mcp.schema.ListToolsResult;
+import io.agentscope.core.mcp.tool.Tool;
+import io.agentscope.core.mcp.tool.ToolManager;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * Handler for `tools/list` requests. Returns metadata about registered tools.
+ */
+public class ListToolsHandler extends AbstractMethodHandler {
+
+    private final ToolManager toolManager;
+
+    public ListToolsHandler(ToolManager toolManager) {
+        this.toolManager = toolManager;
+    }
+
+    @Override
+    public String getMethod() {
+        return "tools/list";
+    }
+
+    @Override
+    public Object handle(Object params) throws Exception {
+        List<Object> out = new ArrayList<>();
+        for (Tool t : toolManager.list()) {
+            Map<String, Object> m = new HashMap<>();
+            m.put("name", t.getName());
+            m.put("description", t.getDescription());
+            m.put("inputSchema", t.getInputSchema());
+            out.add(m);
+        }
+
+        return new ListToolsResult(Optional.empty(), out);
+    }
+}

agentscope-core/src/main/java/io/agentscope/core/mcp/handler/MessageRouter.java

@@ -0,0 +1,97 @@
+package io.agentscope.core.mcp.handler;
+
+import io.agentscope.core.mcp.message.JsonRpcError;
+import io.agentscope.core.mcp.message.JsonRpcMessage;
+import io.agentscope.core.mcp.message.JsonRpcRequest;
+import io.agentscope.core.mcp.message.JsonRpcResponse;
+import io.agentscope.core.mcp.transport.Transport;
+import io.agentscope.core.mcp.transport.TransportException;
+import java.util.Optional;
+import java.util.logging.Logger;
+
+/**
+ * Routes incoming messages to appropriate handlers.
+ *
+ * <p>Manages request/response correlation and error handling for MCP protocol messages.
+ */
+public class MessageRouter {
+
+    private static final Logger logger = Logger.getLogger(MessageRouter.class.getName());
+
+    private final Transport transport;
+    private final HandlerRegistry handlerRegistry;
+
+    public MessageRouter(Transport transport, HandlerRegistry handlerRegistry) {
+        this.transport = transport;
+        this.handlerRegistry = handlerRegistry;
+    }
+
+    /**
+     * Process an incoming message.
+     *
+     * @param message the incoming message
+     * @throws TransportException if processing fails
+     */
+    public void handleMessage(JsonRpcMessage message) throws TransportException {
+        String method = message.getMethod().orElse(null);
+
+        if (method == null) {
+            logger.warning("Received message without method");
+            return;
+        }
+
+        Optional<MethodHandler> handler = handlerRegistry.get(method);
+        if (!handler.isPresent()) {
+            handleUnknownMethod(message, method);
+            return;
+        }
+
+        JsonRpcResponse response = handler.get().handleMessage(message);
+        if (response != null && message instanceof JsonRpcRequest) {
+            // Only send response for requests, not notifications
+            transport.send(response);
+        }
+    }
+
+    /**
+     * Start processing messages from the transport.
+     *
+     * <p>This method runs indefinitely until the transport is closed or an error occurs.
+     *
+     * @throws TransportException if an error occurs
+     */
+    public void processMessages() throws TransportException {
+        while (transport.isConnected()) {
+            try {
+                JsonRpcMessage message = transport.receive();
+                handleMessage(message);
+            } catch (TransportException e) {
+                if (transport.isConnected()) {
+                    logger.warning("Error processing message: " + e.getMessage());
+                }
+            }
+        }
+    }
+
+    private void handleUnknownMethod(JsonRpcMessage message, String method)
+            throws TransportException {
+        if (message instanceof JsonRpcRequest) {
+            JsonRpcRequest request = (JsonRpcRequest) message;
+            JsonRpcError error =
+                    new JsonRpcError(
+                            JsonRpcError.ErrorCode.METHOD_NOT_FOUND, "Method not found: " + method);
+            JsonRpcResponse response = new JsonRpcResponse(request.getId().orElse(null), error);
+            transport.send(response);
+        }
+    }
+
+    /**
+     * Register a method handler.
+     *
+     * @param method the method name
+     * @param handler the handler
+     */
+    public void register(String method, MethodHandler handler) {
+        handlerRegistry.register(method, handler);
+    }
+}