About Client Support

[bulefire-fox]

This thread will be where I share all my ongoing development thoughts, progress updates, and any questions I have while implementing the MCP client feature. I’ll organize all content clearly here to keep our communication efficient and easy to follow.

[bulefire-fox]

@codeboyzhou

What do you think about how the client support should be designed? Does it need to be annotation-driven? In fact, I think the official SDK's design is also easy to use, but when I use it, I need to handle a lot of classes, so I must understand them. Also, the documentation in the code is too sparse to understand what I can do and what I should do.

---

I envision a client design approach based on interface proxy + annotation-driven, where the core idea is that users declare remote MCP operations using interfaces, and the SDK generates implementations via JDK dynamic proxies. For example:

@McpClientApplication(host="127.0.0.1", port=8080, token="...", ...) // set connection info in code
public interface CalculatorClient {

    @McpClientTool(name = "add")
    int add(@McpToolParam(name = "a") int a, @McpToolParam(name = "b") int b);

    @McpClientResource(uri = "system://info")
    Map<String, String> getSystemInfo();

    @McpClientPrompt(name = "generate-code")
    String generateCode(@McpPromptParam(name = "language") String lang,
                        @McpPromptParam(name = "task") String task);
}

or:

public interface CalculatorClient extends McpClient {
    Map<String, Object> params = Map.of("host", "127.0.0.1", ...); // set the connection info
    // Keep it as it is
}

and usage:

// One-line creation, type-safe
CalculatorClient client = McpClientFactory.create(CalculatorClient.class);
int sum = client.add(3, 5);

or

// create method extends McpClient.create()
CalculatorClient client = CalculatorClient.create();

Using this approach requires adding some new classes and annotations, which I plan to place under the package com.github.thought2code.mcp.annotated.client. I wonder what you think about this. I hope you can give me some suggestions on my plan.

[codeboyzhou]

Hi @bulefire-fox

Yes, I think it should also be annotation-driven, aligning with the server-side design pattern.

It looks like interface proxy + annotation-driven is a good way to implement your idea, and the SDK could generate the necessary code. However, there are a few points you should consider:

• For the @McpClientApplication annotation: when the server runs in STDIO mode, it doesn't need host and port. You'll need a way to distinguish STDIO mode from Streamable HTTP mode (HTTP SSE mode is deprecated and will be removed in future versions, so you can ignore it). Also, have you considered using a configuration file for these properties?

• @McpClientTool, @McpClientResource, and @McpClientPrompt are OK, but @McpToolParam and @McpPromptParam conflict with server-side annotations.

The package path you plan to use is fine.

Please feel free to open a PR when you're ready.

[bulefire-fox]

@codeboyzhou I actually didn't consider the different modes. To solve this problem, I think it can be solved by adding a couple of annotations like @StreamableHttp and @STDIO to distinguish them from each other and provide properties.

Regarding the configuration file, it is a good idea to keep it consistent with the server-side. But I'm worried that it is too cumbersome for users to create an MCP client. I think annotations can be used to provide basic properties like IP, port, launch command, and so on, and at the same time a configuration file can be used to deeply configure the client, like the HTTP version, timeout, and so on.

Regarding the conflict, it can be solved by adding a client-side annotation such as @ClientMcpToolParam to distinguish them from server-side ones, or by changing the scanner logic to exclude client-side annotations.

I plan to put the annotations in the existing package com.github.thought2code.mcp.annotated.annotation and this approach will change some existing code. I want to know your viewpoint on this.

I wonder what your thoughts are about these ideas.

[codeboyzhou]

@codeboyzhou I actually didn't consider the different modes. To solve this problem, I think it can be solved by adding a couple of annotations like @StreamableHttp and @STDIO to distinguish them from each other and provide properties.

Regarding the configuration file, it is a good idea to keep it consistent with the server-side. But I'm worried that it is too cumbersome for users to create an MCP client. I think annotations can be used to provide basic properties like IP, port, launch command, and so on, and at the same time a configuration file can be used to deeply configure the client, like the HTTP version, timeout, and so on.

Regarding the conflict, it can be solved by adding a client-side annotation such as @ClientMcpToolParam to distinguish them from server-side ones, or by changing the scanner logic to exclude client-side annotations.

I plan to put the annotations in the existing package com.github.thought2code.mcp.annotated.annotation and this approach will change some existing code. I want to know your viewpoint on this.

I wonder what your thoughts are about these ideas.

Hi @bulefire-fox, thank you. I don't think adding new annotations like @StreamableHttp and @STDIO is a good approach. If we already have the annotation @McpClientApplication, we should not need one more annotation. Annotations are indeed more convenient to use, but it should not be abused.

Configuration file is necessary, it ensures better readability, maintainability, and consistency in a large-scale project, avoiding configuration fragmentation. By contrast, using annotations to manage configuration properties is not a good practice.

In addition, another new idea in recent, maybe client and server should be separated to different maven modules and jar packages (not yet finalized). In this way, users can decide for themselves whether they need more lightweight dependency.

Recently, I conducted a major project refactoring, the server-side core implementation has been changed from runtime reflection scanning to compile-time code generation, this should also be the main direction for the future of this project.