tachyon

Mavenhttps://img.shields.io/maven-central/v/dev.tmcp/tach)](https://repo.org/maven2/dev/tachyonmcp/tachyon-server/) [](https://github.com/kpavlov/tachyon/actions/workflows/build.yml) [](https://github.com/modelcontextprotocol/conformance) [](http://java.com) [](https://deepwiki.com/kpavlov/tachyon) **Tachyon MCP** — 一个基于 Netty 4.2 的 Java 21 [模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器。完全实现了 MCP 规范 **2025-11-25** 版本，包括流式 HTTP 传输、会话生命周期、原生 I/O 传输和无状态模式，适用于无服务器部署。 **TL;DR** ```java import dev.tachyonmcp.server.TachyonMcpServer; import dev.tachyonmcp.server.features.tools.AbstractSyncToolHandler; import dev.tachyonmcp.server.features.tools.ToolDescriptor dev.tachyonmcp.server.features.tools.ToolResult; import dev.tachyonmcp.server.session.McpContext; import tools.jackson.JsonNodeFactory; void main() { var schemaNodeFactory.instance.objectNode(); schema.put("typeobject"); schema.putObject("properties").putObject("city").put("type", "string"); TachyonMcpServer.builder() .weather-mcp") .tool(new AbstractSyncToolHandler( ToolDescriptor.builder("get_forecast") .description("获取天气预测") .inputSchema(schema) .build()) { @Override public Object handle(McpContext ctx, Object args) { return ToolResult.text("☀️ 22°C"); } }) .stateless(true) .port(808 .bind(); } ``` ## 功能特点 ### 核心协议（46/46 一致性测试通过） - JSON-RPC 2.0 — 请求/响应/错误/通知 - 流式 HTTP — POST, GET (SSE), DELETE, OPTIONS - 生命周期 — 初始化 → 已初始化 → 活跃 - 分页 — 基于游标的分页，适用于所有列表方法 -状态机 — 初始化中 → 活跃 → 已关闭 - CORS 和来源验证 - DNS 重新绑定保护 - 严格的 Accept 头验证（406） - 待处理请求超时（60 秒） - 通过 Last-Event-ID 实现 SSE 可恢复性 ### 工具 - `tools/list` —nextCursor` 的分页 - `tools/call` — 返回带有 `isError` 的 `CallToolResult` - 列表中的 `outputSchema` - `annotations` 字段 - `execution.taskSupport`（禁止/可选/必需） - 同步和异步处理接口 - 名称验证（1-128 个字符） - 添加/删除时发送 `notifications/tools/list_changed` - 工具调用期间的内联通知和日志记录 - 输入模式验证 ### 资源 - `resources/list` — 分页 - `resources/read` — 文本和二进制内容 - `resources/templates/list` — URI- `resources/subscribe` / `unsubscribe` - `notifications/resources/list_changed` - `notifications/resources/updated` 发送给订阅者 - 通过 `ResourceHandler` 接口实现动态内容 ### 提示 - `prom` — 带 `nextCursor` 的分页 - `prompts/get` — 调用提示解析器 - `notifications/prompts/list_changed` ### 任务 - `tasks/list`, `tasks/get`, `tasks/cancel`, `tasks/result` - 状态机强制执行 — 已提交 → 正在执行 → 已完成/失败/取消 - 每次状态转换时广播 `notifications/tasks/status` - 任务清理器，用于清理过时任务 - 每个工具的 `execution.taskSupport`（禁止/可选/必需） - `TasksExtension`（[SEP-1686](https://modelcontextprotocol.io/seps/1686-tasks)）— 可协商的扩展，暴露 `create_task` 工具和 `task://{id}` 资源模板 - 扩展门控工具可见性（对未协商的客户端隐藏） ### 日志和可观察性 - `logging/setLevel` 每个会话 - 在阈值以上时发出 `notifications/message` - 进度通知 ### 客户端通信 - `sampling/createMessage` — 服务器 → 客户端请求 - 诱导 — ✅ 表单模式；❌ URL 模式 - `notifications/cancelled` — 双向 - `notifications/tasks/status` 来自客户端 ### 传输和 I/O - Netty 4.2 - io_uring / epoll / kqueue / nio 自动检测 - 平台线程事件循环 + 虚拟线程处理程序 - TCP_NODELAY, SO_KEEPALIVE - 通道可写性反压（`setAutoRead`） - 可配置的空闲超时（读取器/写入器） ### 会话管理 - **无状态模式** — 跳过无服务器会话 - 内存会话存储（ConcurrentHashMap） - 会话清理器 — 5 秒扫描，30 秒 TTL - SSE 断开连接 ≠ 会话删除（支持重新连接） - 重新连接时回放事件日志 --- ## 安装 **要求**：JDK 21+ ### Maven ```xml <dependency> <groupId>dev.tachyonmcp</groupId> <artifactId>tachyon-server</artifactId> <version>1.0.0-alpha.2</version> </dependency> ``` ### 从源码构建 ```bash git clone https://github.com/kpavachyon.git cd tachyon mvn install -pl tachyon-mcp-server -DskipTests ``` ## 快速入门 ### 带有工具的最小服务器 ```java import dev.tachyonmcp.server.TachyonMcpServer; import dev.tachcp.server.features.tools.AbstractSyncToolHandler; import dev.tachyonmcp.server.features.tools.ToolDescriptor; import dev.tachyonmcp.server.features.tools.ToolResult; import dev.tachyonmcp.server.session.McpContext; import tools.jackson.databind.node.JsonNodeFactory; void main() { var schema = JsonNodeFactory.instance.objectNode(); .put("type", "object"); schema.putObject("properties").putObject("city").put("type", "string"); TachyonMcpServer.builder() .name("weather-mcp") .tool(new AbstractSyncToolHandler ToolDescriptor.builder_forecast") .description("获取天气预测") .inputSchema(schema) .build()) { @Override Object handle(McpContext ctx, Object args) { return ToolResult.text("☀️ 22°C"); } }) eless(true) // 以无状态节点启动（无会话） .port(8080) // 绑定到 127.0.0.1:8080 .bind(); } ``` ### 带有 TasksExtension（可协商）--1686://modelcontextprotocol.io/seps/1686-tasks) ```java var handle = TachyonMcpServer.builder() .extension(new TasksExtension()) // 暴露 create_task 工具和 task://{id} 资源模板 .port(8080) .bind(); ``` 在其 `initialize` 功能中包含 `"extensions": {"io.modelcontextprotocol/tasks": {}}` 的客户端会收到扩展的工具和资源模板。 不支持该扩展的客户端会通过 `tasks/list` / `tasks/get` 看到标准的 MCP 任务。 ### 协议隔离 处理程序接口（``Handler`、`PromptHandler`）符类型使用稳定的领域类型。 当 Tachyon 升级到新协议版本时，只有内部映射层会发生变化； 处理程序实现不会受到影响。领域类型跟踪 2026-07-28 规范形状，其中它改进了 2025-11-25 版本（例如 `Annotations.lastModified`、`ResourceLink` 在 `ContentBlock` 中）。 ## 性能 - **原生传输** — io_uring > epoll > kqueue > NIO 自动检测 - **写入缓冲区水位 — 32 KB 低 / 128，连接反压 - **批量刷新** — `ctx.write()` 累积，在边界处单个 `ctx.flush()` - **最小分配**McpEndpointHandler` 是 `@Sharable`，无每请求处理程序创建 - **虚拟线程** — 从事件循环中卸载的处理程序，无需手动线程池 - **JSON-RPC** — Jackson 流式编码器，无 ObjectMapper。 ## 差距和 - [ ] **速率限制** — 尚未实现 - [ ] **URL 诱导模式 / -32042 错误** —模式有效，URL 模式缺失 - [ ] **2026-07-28 草案协议版本** — 不可协商；版本门控功能已准备就绪 - [ ] **重新初始化时的过时会话** — 30 秒 TTL 停留，仅影响重新连接 --- ## 常见问题 ### 我可以部署到 AWS Lambda 吗？ 是的。使用 `stateless(true)` 跳过会话持久化。每个调用独立处理一个请求。 ### 它支持 HTTP/2 吗？ 暂不支持。当前管道以 HTTP/1.1 为目标；HTTP/2 升级是即将到来的管道配置更改。 ### 如何编写自定义工具？ 扩展SyncToolHandler` 或 `AbstractAsyncToolHandler`，传递 `ToolDescriptor`： ```java class MyTool extends AbstractSyncToolHandler { MyTool() { super(ToolDescriptor.builder("my_tool") .description("执行有用的操作") .inputSchema(buildSchema()) .build()); } @Override public Object handle(McpContext ctx, Object args) throws Exception { return CallToolResult.ofText("完成"); } private static JsonNode buildSchema() { var s = JsonNodeFactory.instance.objectNode(); s.put("type", "object"); return s; } } ``` ### 如何实现自定义资源？ ```java server.resources().add( ResourceDescriptorcustom://data"), (ctx, req) -> new TextResourceContents("内容", req.uri(), "text/plain", null)); ``` ## 许可证 **T MCP** 遵循 [Apache 2.0](LICENSE) 协议。