tachyon core

⚙️ tachyon-core

Verdict: the runtime. ~190 main files. Deps: slf4j-api, netty-codec-http, netty-handler, jackson-databind 3, json-schema-validator (networknt), tachyon-api (pom.xml). Generates protocol wire models at build (ts2java).

🗂️ Package map (tachyon-core/src/main/java/dev/tachyonmcp/core/)

Package	Holds	Page
server	TachyonServer, ServerBuilder, DefaultServerBuilder, DefaultTachyonServer, McpDispatcher, RpcMethodHandler, OutboundSseStream*, AnnotationContext, HandlerWatchdog	overview, request-lifecycle
server.annotations	TachyonAnnotationProvider, MethodInvoker, ResultMappers	declarative-configuration
server.internal	ServerEngine SPI, OperationTracker, AbstractJanitor, NotificationLogSupport	concurrency
server.config	config records + builders	configuration
server.domain	ServerErrors, InitializeResponse, MissingRequiredClientCapabilityException	errors
server.handlers	InitializeHandler, DiscoverHandler, PingHandler, EmptyResultHandler, LoggingHandlers, SubscriptionsListenHandler, ExtensionNegotiator	feature-registries, extensions
server.features.*	registries + *MethodHandlers for tools/resources/prompts/completions/tasks/subscriptions; AbstractRegistry, Pagination, ChangeSupport, ListRequests	feature-registries, tasks
server.session	SessionManager, stores, SessionEvent, DispatchContext, DefaultDispatchContext, NoopInteractionContext, WireClientContext	sessions
server.json	Jackson factories, JsonUtils, JsonSchemaUtils, networknt validator, KtSchemaResourceFactory, JavaTypeSchemaFactory/JavaTypeSchemas, MapJsonFactory	json-layer
server.observability	Observation, listener/scope/info/outcome, CapturedPayload	observability
runtime	Session, SessionState, ChannelContext, DefaultChannelContext, InteractionEvent, SseConnection, SseEvent, Backpressure	sessions
protocol	Protocol, Protocols, ProtocolRequestMapper, ProtocolResponseMapper, ProtocolMappers, RequestMappingException	protocol-versions
protocol.mcp	McpHeaderNames, McpHeaderValue (SEP-2243 Base64 sentinel), MirroredArgument (x-mcp-header ↔ argument), AbstractMcpRequestMapper (shared request mapping); v2025_11_25, v2026_07_28 (McpProtocol, codecs/, transport/, generated models/)	protocol-versions
transport.jsonrpc	JsonRpcCodec, JsonRpcMessage, JsonRpcError, ValueSerializer	json-layer
transport.netty	NettyServer, NettyServerConfig, NettyIoEngine, McpChannelInitializer, init/operation handlers, InteractionHandler, lifecycle coordinator, ChannelHandlerUtils	netty-pipeline
transport.netty.http	guards	security-guards
transport.netty.sse	PostSseStream, SseManager, SseHeartbeat, SseSerializer, NettySseConnection	sse-streams

🧠 Who holds what

• Annotation registration, binding, and proxy invocation: declarative-configuration.

• DefaultTachyonServer = state + registries + methodHandlers map + pending server→client requests + session manager + event store + extensions; implements ServerEngine and ExtensionContext DefaultTachyonServer.

• McpDispatcher = per-request flow, one per McpChannelInitializer (i.e. per server start) McpChannelInitializer.java ctor.

• DefaultDispatchContext = per request: delegates channel state, adds engine, request id, outbound stream, observation, notifications impl DefaultDispatchContext.

📦 Resources

• META-INF/services/dev.tachyonmcp.core.protocol.Protocol, ...JsonDocumentFactory, ...JsonSchemaFactory.
• dev/tachyonmcp/core/server/features/resources/mime-types.csv.

➕ How to add a JSON-RPC method

1. Mapper method on ProtocolRequestMapper (impl once in AbstractMcpRequestMapper, override per version only if shape differs) and ProtocolResponseMapper (+ both version impls).
2. RpcMethodHandler record in server.features.<x> *MethodHandlers.register(map, …) or server.handlers.
3. Wire in DefaultTachyonServer#registerDefaults.
4. Method addresses a named target (Mcp-Name mirror)? add it to McpHeaderNames#mirroredNameField — one switch drives both the all-version agreement check McpHeaderMatchHandler#matchName and the 2026 presence rule RequiredHeadersHandler#requireMirrors.
5. Capability flag? resolveCapabilities + ServerInfoMapper both versions.
6. e2e test per protocol package → testing.

🧪 Unit tests

tachyon-core/src/test/java/dev/tachyonmcp/core/ mirrors packages: server/McpDispatcherTest, ServerTest, ServerBuilderTest, ServerShutdownGraceTest, ObservationDispatchTest; transport/netty/*HandlerTest, ForeignThreadContinuationTest, NettyServerThreadingTest; protocol/mcp/v*/codecs/*MapperTest; session/SessionManagerTest, InMemorySessionStoreTest, InMemorySessionEventStoreTest; test utils core/test/TestUtils, VirtualThreads. JMH benchmarks (not Surefire, JaCoCo-excluded *Benchmark*, tachyon-core/pom.xml): session/InMemorySessionEventStoreBenchmark, session/InMemorySessionStoreBenchmark, gated by BenchmarkGate (make jmh) — see testing.

---

_{📄 source .llm-wiki/modules/tachyon-core.md · updated 2026-09-18 · verified at 2472a0d8 · tags [module, core]}