Package dev.tachyonmcp.api.runtime

Interface InteractionContext

All Known Subinterfaces:
ChannelContext, DispatchContext
All Known Implementing Classes:
DefaultChannelContext, DefaultDispatchContext, NoopInteractionContext
public interface InteractionContext
Handler-facing view of the per-channel interaction: the current lifecycle phase, protocol version, optional session identifier, and the collaboration channels a tool/resource/prompt handler legitimately needs (notifications() and sendRequest(String, Object)).

This interface deliberately exposes no mutators — handlers may read state and use the attribute scratch space, but lifecycle and session mutation live on the internal channel context handed to extension and dispatch code only.

The attribute scratch space (get(AttributeKey)/set(AttributeKey, Object)) is keyed by AttributeKey, not a String, so unrelated handlers can never collide on a shared name — see AttributeKey for why.

  • Method Details

    • protocolVersion

      String protocolVersion()
      Returns the protocol version negotiated during initialisation.
      Returns:
      the negotiated protocol version

    • lifecycle

      @Nullable InteractionContext.Lifecycle lifecycle()
      Returns the current lifecycle phase, or null before initialisation.
      Returns:
      the lifecycle phase, or null

    • sessionId

      @Nullable String sessionId()
      Returns the session identifier, or null in stateless mode.
      Returns:
      the session ID, or null

    • isExtensionEnabled

      boolean isExtensionEnabled(String extensionId)
      Returns true if the given extension is active for this interaction.
      Parameters:
      extensionId - the extension identifier
      Returns:
      true if the extension is active

    • notifications

      ContextNotifications notifications()
      Returns the notification sender bound to this interaction.
      Returns:
      the notification sender

    • client

      ClientContext client()
      Returns typed access to the client-facing elicitation and sampling services.

      Prefer this over sendRequest(String, Object) for sampling/elicitation round-trips — it returns domain results instead of raw JSON.

      Returns:
      the client context

    • sendRequest

      @ExperimentalApi CompletableFuture<String> sendRequest(String method, Object params)
      Sends a request to the client and returns a future that completes with the raw JSON response.

      Experimental escape hatch for client requests not covered by client(), such as URL-mode elicitation or sampling parameters beyond what SamplingService models.

      Parameters:
      method - the request method name
      params - the request parameters
      Returns:
      a future that completes with the raw JSON response

    • get

      <T> Optional<T> get(AttributeKey<T> key)
      Returns the value stored under key, or empty if never set.

      Scoped to the underlying channel/session, not the current request — a value set on one request is visible to later requests on the same connection. Backed by a concurrent map: safe to call from multiple handler threads without external synchronization.

      Type Parameters:
      T - the type of value
      Parameters:
      key - the attribute key
      Returns:
      the value, or empty if not set

    • set

      <T> void set(AttributeKey<T> key, T value)
      Stores value under key, visible to later get(AttributeKey) calls — see get(AttributeKey) for scope and thread-safety.
      Type Parameters:
      T - the type of value
      Parameters:
      key - the attribute key
      value - the value to store