轻量级 Java MCP 服务器
AJ-MCP Server 是一个轻量级的 Java MCP 服务器。它为构建 MCP 服务器提供了简单而强大的方式,支持 Java 8 及以上版本。
它可以通过注解把普通 Java 方法注册为 MCP 工具、资源、资源模板、提示词和自动补全能力,并通过 STDIO、旧版 HTTP/SSE 或 Streamable HTTP 对外提供服务。
主要功能
- 兼容 Java 8 和 Spring Boot 2.x。
- 扫描标记了
@McpService的业务类。 - 通过注解声明工具、资源、资源模板、提示词和参数自动补全。
- 自动生成工具输入 JSON Schema,无参数工具也会生成非空对象 schema。
- 在初始化期间协商
2024-11-05、2025-03-26和2025-06-18协议版本。 - 支持分页、资源订阅、取消、进度/日志通知、Roots、Sampling 和 Elicitation。
- STDIO 与 HTTP 传输具有按会话路由和关闭生命周期。
- 对错误方法、参数和能力调用返回结构化 JSON-RPC 错误。
源代码
链接
安装
运行环境:Java 8 及以上。Maven 配置如下:
<dependency>
<groupId>com.ajaxjs</groupId>
<artifactId>aj-mcp-server</artifactId>
<version>1.6</version>
</dependency>
该依赖会自动传递引入 aj-mcp-common。
快速开始:声明 MCP 能力
把 MCP 方法放在带有公共无参构造方法,并标记了 @McpService 的类中:
@McpService
public class DemoFeatures {
@Tool(description = "两个整数相加")
public String add(@ToolArg("a") Integer a,
@ToolArg("b") Integer b) {
return String.valueOf(a + b);
}
@Tool(description = "返回服务器时间")
public String serverTime() {
return new Date().toString();
}
@Resource(uri = "config:///application", mimeType = "text/plain",
description = "当前应用配置")
public ResourceContentText configuration() {
ResourceContentText content = new ResourceContentText();
content.setUri("config:///application");
content.setMimeType("text/plain");
content.setText("mode=production");
return content;
}
@Prompt(description = "生成代码审查提示词")
public PromptMessage review(@PromptArg("language") String language) {
PromptMessage message = new PromptMessage();
message.setRole(Role.USER);
message.setContent(new ContentText("请审查这段 " + language + " 代码"));
return message;
}
}
工具方法的每个 Java 参数都必须标记 @ToolArg。参数默认必填,允许省略时设置 required = false。无参数工具是合法的,并会发布为空对象输入
schema。
快速开始:STDIO 服务
public static void main(String[] args) {
FeatureMgr features = new FeatureMgr();
features.init("com.example.mcp");
ServerConfig config = new ServerConfig();
config.setName("example-server");
config.setVersion("1.0.0");
McpServer server = new McpServer();
server.setFeatureMgr(features);
server.setServerConfig(config);
server.setTransport(new ServerStdio(server));
server.start();
}
STDIO 每行传输一个 JSON-RPC 消息。不要向 System.out 输出业务内容,否则会破坏协议流;日志应配置到标准错误或文件。
server.start() 会阻塞,直到标准输入关闭或传输停止。
旧版 HTTP/SSE
ServerSse 是旧版 MCP HTTP/SSE 的框架无关适配器。Servlet 或 Controller 需要:
- 提供
Content-Type: text/event-stream的GET端点; - 生成客户端/会话 ID,并调用
openSession(id, writer, messageEndpoint); - 提供服务端公布的
POST消息端点,并把 JSON 请求体交给handle(id, body); - 连接断开时调用
removeConnection(id); - 应用停止时关闭传输层。
McpServer server = new McpServer();
server.
setFeatureMgr(features);
server.
setServerConfig(config);
ServerSse transport = new ServerSse(server);
server.
setTransport(transport);
server.
start();
Controller 和 Servlet 接线方式请参考 Spring Boot 与内嵌 Tomcat 示例。
Streamable HTTP
ServerStreamableHttp 同样不绑定具体 Servlet 框架。在同一个 MCP 端点上分别委托:
POST请求调用post(body, headers);- 可选的
GET事件流调用openEventStream(sessionId, writer, headers); DELETE请求调用delete(sessionId, headers)。
把 HttpResult 中的状态码、响应头、内容类型和正文复制到框架响应。初始化会创建会话并返回 Mcp-Session-Id。使用 2025-06-18
时,后续请求必须携带协商后的 MCP-Protocol-Version 请求头。浏览器 Origin 白名单通过 ServerConfig.allowedOrigins
配置;空列表会拒绝所有携带 Origin 的请求。
本项目有意不支持 JSON-RPC batch 请求。
POST 请求返回 JSON;客户端响应和通知返回无正文的 202。服务端未实现请求级 POST SSE 输出,MCP 传输规范允许返回 JSON,
服务端主动消息通过 GET 发送。框架须异步保持 GET 响应打开、立即 flush 响应头,并在完成、错误或超时回调中调用
closeEventStream(sessionId, writer)。注册后的 Writer 由适配器持有,在断开、替换或关闭时释放。
每 15 秒发送心跳,空闲会话默认 30 分钟过期,包括未打开 GET 的会话;正在处理的 POST 不会过期,GET 心跳本身不延长空闲时间。
DELETE 和关闭传输层均清理完整会话状态。
整数工具参数使用 JSON Schema integer,小数和越界值返回 INVALID_PARAMS。取消仍是协作式的,但取消先于执行结束时,
忽略中断的工具也不能返回成功结果。日志阈值按会话保存并过滤。
补全方法可采用 String value 或 (String value, Map<String, String> arguments) 签名。
第二个参数是 MCP 2025-06-18 context.arguments 的只读视图;原单参数方法保持兼容,客户端
complete(ref, argument, context) 的 Map API 保持不变。
配置
ServerConfig 的主要属性:
| 属性 | 含义 | 默认值 |
|---|---|---|
name、version |
初始化时返回的服务身份 | 未设置 |
pageSize |
每页工具、资源或提示词数量 | 3 |
protocolVersions |
支持的协议版本,新版本优先 | 所有已实现版本 |
strictLifecycle |
普通请求前是否强制 initialize → initialized | true |
allowedOrigins |
Streamable HTTP 接受的浏览器 Origin | 空列表 |
clientRequestTimeout |
反向调用传入 null/零时使用的超时 | Duration.ofSeconds(60) |
sessionIdleTimeout |
HTTP 会话空闲过期时间 | Duration.ofMinutes(30) |
stdioWorkers |
STDIO 最大并发请求数 | 16 |
stdioQueueCapacity |
STDIO 队列容量,满时返回繁忙错误 | 256 |
STDIO 固定使用 UTF-8。在构造 ServerStdio 前设置线程和队列上限;工具队列满时,握手、ping、取消和反向响应仍可处理。
每个服务创建一个 FeatureMgr,并通过 setFeatureMgr 赋给 McpServer。能力存储是实例级的,扫描一个服务不会自动填充另一个服务。
关闭服务
应用停止时应关闭已配置的传输层。关闭会清理会话、停止心跳/执行器线程、中断适用的 STDIO 处理,并释放 Writer。框架应用可放在
@PreDestroy、Servlet destroy 或对应的销毁钩子中执行。