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

[BEASTSHRIRAM]

AgentScope-Java Version

1.0.12-SNAPSHOT

Description

Adds native MCP server support to AgentScope Java, enabling developers to build and expose custom tool servers via the Model Context Protocol.
Includes complete implementation with StdIO/TCP transports, tool registry, protocol handlers, and a working calculator example with CLI agent integration.
Resolves #229

Background

AgentScope Java previously only supported MCP client integration (connecting to external MCP servers). This PR adds native MCP server support, enabling developers to build and expose their own tool servers via the Model Context Protocol.

Purpose

Enable AgentScope Java applications to:

• Implement custom domain-specific tool servers
• Expose tools to external clients (Claude, VSCode extensions, other agents)
• Follow MCP protocol standards (JSON-RPC 2.0)
• Support multiple transport options (StdIO, TCP)

Changes Made

Core Implementation (agentscope-core/src/main/java/io/agentscope/core/mcp/)

• Tool interface: Server-side tool abstraction with execute(), getName(), getDescription(), getInputSchema()
• ToolManager: Thread-safe concurrent registry for tool management
• InitializeHandler: Implements MCP initialize handshake
• ListToolsHandler: Implements tools/list discovery endpoint
• CallToolHandler: Implements tools/call execution endpoint
• StdioTransport: JSON-RPC communication via stdin/stdout
• TcpTransport: Network-based JSON-RPC communication
• McpServer: Main facade for server creation and tool registration

Example Module (agentscope-examples/mcp-native-example/)

• CalculatorTool: MCP tool implementing arithmetic operations (add, subtract, multiply, divide)
• McpServerRunner: Standalone MCP server exposing calculator tools
• ReActAgentCliRunner: Interactive CLI agent integrating calculator tools via toolkit
• CalculatorToolAdapter: AgentScope @tool annotation adapter with logging
• Unit tests and fat JAR build configuration

Documentation (docs/en/task/mcp-native.md)

• 500+ line comprehensive guide covering server concepts, tool implementation, protocol details, transport configuration, and integration patterns
• Complete working examples with code snippets
• Best practices and troubleshooting guide

How to Test

1. Build the modules:

   mvn clean install -pl agentscope-core,agentscope-examples/mcp-native-example

2. Run MCP Server (StdIO):

   java -jar agentscope-examples/mcp-native-example/target/mcp-native-example.jar

3. Run Interactive CLI Agent:

   OPENAI_API_KEY="sk-..." java -cp agentscope-examples/mcp-native-example/target/mcp-native-example.jar \
       io.agentscope.examples.mcp.ReActAgentCliRunner

4. Test with queries:

   • "What is 100 + 39869 + 2922355?"
   • "Calculate 2^10"
   • "Add 15.5 and 24.7"

5. Run unit tests:

   mvn test -pl agentscope-core,agentscope-examples/mcp-native-example

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (docs/en/task/mcp-native.md, README.md)
• Code is ready for review

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

AgentScope Developer seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Copilot]

Pull request overview

Introduces a native, in-house MCP (Model Context Protocol) server implementation in agentscope-core (JSON-RPC 2.0 messages, handler/router, ToolManager, StdioTransport, TcpTransport, McpServer facade) plus a calculator example module exposing tools both as an MCP server and as ReActAgent tools, and a 500‑line user guide. The intent is to let AgentScope Java apps build and expose MCP servers (previously only client integration existed). Several pieces of the new server stack have correctness, transport, naming and convention issues that should be resolved before merge.

Changes:

• Add io.agentscope.core.mcp.{message,handler,schema,tool,server,transport} packages implementing JSON-RPC 2.0 plumbing, initialize/tools/list/tools/call handlers, a ToolManager, and StdioTransport/TcpTransport.
• Add agentscope-examples/mcp-native-example (Calculator/OpenAI tools, McpServerRunner, ReActAgentCliRunner, fat-JAR shade build) and wire it into the examples reactor.
• Add docs/en/task/mcp-native.md user guide and a jackson-datatype-jdk8 dependency to agentscope-core.

Reviewed changes

Copilot reviewed 48 out of 48 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
agentscope-core/pom.xml	Adds jackson-datatype-jdk8 for Optional serialization used by new MCP schema records.
agentscope-core/src/main/java/io/agentscope/core/mcp/message/*.java	Base JsonRpcMessage + Request/Response/Notification/Error types for JSON-RPC 2.0.
agentscope-core/src/main/java/io/agentscope/core/mcp/handler/*.java	MethodHandler SPI, registry, router, initialize/tools/list/tools/call handlers; uses java.util.logging instead of SLF4J.
agentscope-core/src/main/java/io/agentscope/core/mcp/schema/*.java	Auto-generated MCP schema records with PascalCase builder methods and several empty placeholder types (RequestId, ContentBlock).
agentscope-core/src/main/java/io/agentscope/core/mcp/tool/{Tool,ToolManager}.java	Server-side tool SPI and concurrent registry; name collides with schema.Tool.
agentscope-core/src/main/java/io/agentscope/core/mcp/server/McpServer.java	Facade wiring transport, handlers, tool manager; runs router on a single-thread executor.
agentscope-core/src/main/java/io/agentscope/core/mcp/transport/{Transport,TransportException,StdioTransport,TcpTransport}.java	Transport SPI plus stdio and TCP implementations; TcpTransport is client-only despite being documented as server-side, and the private startReadThread() in both is never invoked.
agentscope-core/src/test/java/io/agentscope/core/mcp/**/*.java	New unit/Mockito tests for messages, handler registry, router, tool manager and CallToolHandler.
agentscope-examples/pom.xml	Registers the new mcp-native-example module.
agentscope-examples/mcp-native-example/pom.xml	Shaded fat-JAR build with McpServerRunner as main class.
agentscope-examples/mcp-native-example/src/main/java/.../CalculatorTool.java	Sample MCP tool returning a result map.
agentscope-examples/mcp-native-example/src/main/java/.../CalculatorToolAdapter.java	@Tool-annotated bridge for use from Toolkit/ReActAgent.
agentscope-examples/mcp-native-example/src/main/java/.../OpenAiChatTool.java	OkHttp-based OpenAI chat tool; duplicates the Content-Type header.
agentscope-examples/mcp-native-example/src/main/java/.../McpServerRunner.java	Stdio MCP server bootstrap; joins on the main thread (deadlocks self) and logs to stdout-sharing JVM.
agentscope-examples/mcp-native-example/src/main/java/.../ReActAgentCliRunner.java	CLI agent demo; selects between DashScope and an OpenAI model id that does not exist.
agentscope-examples/mcp-native-example/src/test/java/.../CalculatorToolTest.java	Basic JUnit Jupiter tests for the calculator tool.
agentscope-examples/mcp-native-example/README.md	Module README for build/run/protocol examples.
docs/en/task/mcp-native.md	User-facing guide; contains a Java sample with an invalid throw in a ternary and documents TCP "server" usage that the implementation does not support.

Comments suppressed due to low confidence (2)

agentscope-core/src/main/java/io/agentscope/core/mcp/server/McpServer.java:20

• This module uses java.util.logging.Logger (here and in StdioTransport, TcpTransport, MessageRouter, McpServerRunner, CalculatorToolAdapter), but the rest of agentscope-core consistently uses SLF4J (org.slf4j.Logger / LoggerFactory). See e.g. agentscope-core/src/main/java/io/agentscope/core/tool/McpClientManager.java:27-38 and dozens of other files. Please switch the new MCP code to SLF4J to stay consistent with the codebase logging convention.

import java.util.logging.Logger;

/**
 * Facade for creating and running an MCP server.
 */
public class McpServer {

    private static final Logger logger = Logger.getLogger(McpServer.class.getName());

agentscope-core/src/main/java/io/agentscope/core/mcp/schema/Tool.java:36

• The builder methods on this record (and on every other record in io.agentscope.core.mcp.schema.* — CallToolResult, CallToolRequest, CallToolRequestParams, InitializeResult, InitializeRequest, InitializeRequestParams, ListToolsRequest, ListToolsResult, PaginatedRequestParams, TextContent, Tool) use PascalCase setter names (Description, InputSchema, Name, Content, IsError, Id, Jsonrpc, Method, Params, Cursor, etc.). This violates the Java naming convention used throughout the codebase, where builder setters are camelCase (name(), model(), apiKey(), description() — see OpenAIChatModel.builder(), Msg.builder(), ReActAgent.builder() usage in this same PR). Please rename the builder methods to camelCase.

    public static class Builder {
        private Optional<String> description = Optional.empty(); // Optional field
        private Map<String, Object> inputSchema = null; // Required field
        private String name = null; // Required field

        public Builder Description(String value) {
            this.description = Optional.of(value);
            return this;
        }

        public Builder InputSchema(Map<String, Object> value) {
            this.inputSchema = value;
            return this;
        }

        public Builder Name(String value) {
            this.name = value;
            return this;
        }

[codecov]

Codecov Report

❌ Patch coverage is 24.45652% with 417 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...io/agentscope/core/mcp/transport/TcpTransport.java	0.00%	90 Missing ⚠️
.../agentscope/core/mcp/transport/StdioTransport.java	0.00%	73 Missing ⚠️
.../java/io/agentscope/core/mcp/server/McpServer.java	0.00%	25 Missing ⚠️
.../java/io/agentscope/core/mcp/schema/RequestId.java	0.00%	17 Missing ⚠️
...io/agentscope/core/mcp/schema/CallToolRequest.java	0.00%	16 Missing ⚠️
.../agentscope/core/mcp/schema/InitializeRequest.java	0.00%	16 Missing ⚠️
...o/agentscope/core/mcp/schema/ListToolsRequest.java	0.00%	16 Missing ⚠️
.../io/agentscope/core/mcp/handler/MessageRouter.java	60.60%	10 Missing and 3 partials ⚠️
...scope/core/mcp/schema/InitializeRequestParams.java	0.00%	13 Missing ⚠️
.../io/agentscope/core/mcp/schema/ToolDefinition.java	0.00%	13 Missing ⚠️
... and 18 more

📢 Thoughts on this report? Let us know!