MCP 服务器 SDK 使用说明

MCP 服务器 SDK 安装

添加如下依赖以构建 MCP 服务器：

<dependency>
    <groupId>com.ajaxjs</groupId>
    <artifactId>aj-mcp-server</artifactId>
    <version>1.5</version>
</dependency>

可在此处查看最新版本：

服务端模块包含：

• McpServer 核心处理引擎
• 基于注解的功能发现管理器 FeatureMgr
• @Tool、@Resource、@Prompt 等注解
• STDIO、旧版 HTTP/SSE 与 Streamable HTTP 传输实现

创建服务器

要创建 MCP 服务器，需要以下步骤：

1. 定义服务类：创建带有 @McpService 注解的类
2. 注解方法：使用 @Tool、@Prompt 或 @Resource 等注解标记方法
3. 初始化功能管理器：扫描包以发现注解
4. 配置传输层：设置 STDIO、旧版 HTTP/SSE 或 Streamable HTTP，并配置相关服务器参数
5. 启动服务器：调用 server.start()

创建 MCP 服务类

AJ-MCP 通过注解扫描自动发现、注册和管理 MCP 功能（工具、资源、提示）。开发者只需在带有 @McpService 注解的类中，使用 @Tool、 @Resource 或 @Prompt 注解标记方法，即可暴露相应功能。

@McpService
public class MyServerFeatures {
    @Tool(description = "回显字符串")
    public String echoString(@ToolArg(description = "输入字符串") String input) {
        return input;
    }

    @Prompt(description = "基础问候提示")
    public PromptMessage greeting(@PromptArg(description = "姓名") String name) {
        PromptMessage message = new PromptMessage();
        message.setRole(Role.USER);
        message.setContent(new ContentText("Hello " + name));
        return message;
    }
}

服务器功能管理

每个服务器使用独立的 FeatureMgr 实例负责包扫描、注解处理与功能存储，因此同一 JVM 中的多个服务器不会共享工具、资源或提示。

注解体系

注解体系围绕几个核心注解展开，用于标记类和方法以供 MCP 识别和暴露：

调用 FeatureMgr.init() 会扫描指定包，并注册 @McpService 类中的 @Tool、@Resource 和 @Prompt 方法。单个类无法加载时会记录日志并跳过，不会中断整个扫描过程。

初始化功能管理器

FeatureMgr.init() 方法负责整个注解发现流程。它首先扫描指定包下带有 @McpService 注解的类。

FeatureMgr mgr = new FeatureMgr();
mgr.

init("com.foo.myproduct");

服务器配置

包扫描初始化功能管理器后，可进行服务器配置，包括：

• 创建服务器实例并设置传输层
• 配置服务器名称与版本号
• 设置分页大小和协议版本等参数

服务器配置由 ServerConfig 类管理，包含服务端元数据。初始化时还会进行协议版本协商，返回所支持的最高版本，或与客户端请求一致的版本。

FeatureMgr mgr = new FeatureMgr();
mgr.

init("com.foo.myproduct");

McpServer server = new McpServer();
server.

setFeatureMgr(mgr);
server.

setTransport(new ServerStdio(server));

ServerConfig serverConfig = new ServerConfig();
serverConfig.

setName("MY_MCP_Server");
serverConfig.

setVersion("1.0");
server.

setServerConfig(serverConfig);

server.

start();

传输与生命周期规则

• ServerStdio 每行交换一个 JSON-RPC 消息，System.out 必须仅用于协议输出。
• ServerSse 是旧版双端点适配器：用 openSession(...) 建立会话，把 POST 消息交给 handle(sessionId, body) ，断开连接时移除会话，并在应用关闭时关闭适配器。
• ServerStreamableHttp 使用单一端点：POST 委托给 post(body, headers)，可选 GET event stream 委托给 openEventStream(sessionId, writer, headers)，DELETE 委托给 delete(sessionId, headers)。将返回 HttpResult 的状态码、响应头、content type 和正文复制到框架响应中。

初始化会协商支持的版本，并创建 Streamable HTTP session。使用 MCP 2025-06-18 时，后续 Streamable HTTP 请求必须带上协商后的 MCP-Protocol-Version header。strictLifecycle 默认开启，普通请求必须在 initialize 和 notifications/initialized 之后发送。本项目有意不支持 JSON-RPC batch。