Package org.apache.juneau.rest.server.mcp.v20260728

Class McpRevision

java.lang.Object

org.apache.juneau.rest.server.mcp.v20260728.McpRevision

All Implemented Interfaces:

McpRevision

public final class McpRevision
extends Object
implements McpRevision

McpRevision implementation for MCP revision 2026-07-28.

Owns this revision's stateless JSON-RPC method table, per-request _meta negotiation, SEP-2243 Mcp-Method/Mcp-Name header agreement checks, server/discover dispatch, and error-code table. Every request is independently negotiated from its own _meta; no handshake, session, or prior-request state exists.

Constructed per binding, not shared as a singleton. The bound servlet or mixin builds a fresh instance on every revision() call, passing its McpOptions.getCapabilities() result and its published McpCacheConfig into the constructor — see McpRestServlet and McpEndpoint. A null capabilities override auto-derives server/discover capabilities from the registered tool/prompt/resource/resource-template lists; a non-null override is advertised as-is. The cache config is binding-owned: it is supplied once at construction, is never null, and is treated as static and request-independent for the lifetime of this instance — every page of a given list method resolves to identical cache values. The instance retains no request-derived state.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	CODE_INTERNAL_ERROR	JSON-RPC error code: internal error.
static final int	CODE_INVALID_PARAMS	JSON-RPC error code: invalid params.
static final int	CODE_INVALID_REQUEST	JSON-RPC error code: invalid request.
static final int	CODE_MAX_ROUNDS_EXCEEDED	MRTR error code: the echoed requestState's embedded round counter is at or above the configured max-rounds cap.
static final int	CODE_METHOD_NOT_FOUND	JSON-RPC error code: method not found.
static final int	CODE_MISSING_REQUIRED_CLIENT_CAPABILITY	SEP-2322 error code: the client did not advertise a capability (elicitation) required to receive an input_required result.
static final int	CODE_PARSE_ERROR	JSON-RPC error code: parse error.
static final int	CODE_REQUEST_STATE_ARGUMENTS_MISMATCH	MRTR error code: the current request's arguments do not hash to the same value as the arguments sealed at PAUSE time — the client has resumed with a different argument set than the one the paused operation originally authorized.
static final int	CODE_REQUEST_STATE_EXPIRED	MRTR error code: the echoed requestState has expired (past its sealed expiresAtMs).
static final int	CODE_REQUEST_STATE_REPLAYED	MRTR error code: an operator-configured ReplayCache reports that the echoed requestState has already been consumed once before.
static final int	CODE_TOO_MANY_SUBSCRIPTIONS	C8 error code: the server already has maxConcurrentSubscriptions live subscriptions/listen streams.
static final String	DEFAULT_SERVER_NAME	Default server name reported by server/discover when the config supplies no server identity.

Constructor Summary

Constructors

Constructor	Description
McpRevision(ServerCapabilities capabilities)	Constructor.
McpRevision(ServerCapabilities capabilities, McpCacheConfig cacheConfig)	Constructor.
McpRevision(ServerCapabilities capabilities, McpCacheConfig cacheConfig, String instructions)	Constructor.
McpRevision(ServerCapabilities capabilities, McpCacheConfig cacheConfig, String instructions, McpMrtrConfig mrtrConfig)	Constructor.

Method Summary

Modifier and Type	Method	Description
McpDispatchResult	dispatch(McpExchange exchange, McpServerConfig config, BeanStore ctx)	Dispatches one JSON-RPC request.
int	errorCode(McpErrorKind kind)	Maps a neutral failure classification to this revision's JSON-RPC error code.
String	protocolVersion()	The MCP protocol revision string this implementation speaks.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CODE_PARSE_ERROR

public static final int CODE_PARSE_ERROR

JSON-RPC error code: parse error. Never reported by this revision (see McpErrorKind.PARSE_ERROR).

See Also:

• Constant Field Values

CODE_INVALID_REQUEST

public static final int CODE_INVALID_REQUEST

JSON-RPC error code: invalid request.

See Also:

• Constant Field Values

CODE_METHOD_NOT_FOUND

public static final int CODE_METHOD_NOT_FOUND

JSON-RPC error code: method not found.

See Also:

• Constant Field Values

CODE_INVALID_PARAMS

public static final int CODE_INVALID_PARAMS

JSON-RPC error code: invalid params.

See Also:

• Constant Field Values

CODE_INTERNAL_ERROR

public static final int CODE_INTERNAL_ERROR

JSON-RPC error code: internal error.

See Also:

• Constant Field Values

CODE_MISSING_REQUIRED_CLIENT_CAPABILITY

public static final int CODE_MISSING_REQUIRED_CLIENT_CAPABILITY

SEP-2322 error code: the client did not advertise a capability (elicitation) required to receive an input_required result. Pinned directly by the SEP-2322 schema (spec Open item #3).

See Also:

• Constant Field Values

CODE_REQUEST_STATE_EXPIRED

public static final int CODE_REQUEST_STATE_EXPIRED

MRTR error code: the echoed requestState has expired (past its sealed expiresAtMs). This plan's own pin, chosen from the JSON-RPC-reserved -32000..-32099 server-error range adjacent to the schema-pinned -32021; not a SEP-2322-sourced value.

See Also:

• Constant Field Values

CODE_MAX_ROUNDS_EXCEEDED

public static final int CODE_MAX_ROUNDS_EXCEEDED

MRTR error code: the echoed requestState's embedded round counter is at or above the configured max-rounds cap. This plan's own pin (same range/rationale as CODE_REQUEST_STATE_EXPIRED).

See Also:

• Constant Field Values

CODE_TOO_MANY_SUBSCRIPTIONS

public static final int CODE_TOO_MANY_SUBSCRIPTIONS

C8 error code: the server already has maxConcurrentSubscriptions live subscriptions/listen streams. This plan's own pin (same -32000..-32099 server-error range and rationale as CODE_REQUEST_STATE_EXPIRED / CODE_MAX_ROUNDS_EXCEEDED); not sourced from SEP-2575.

See Also:

• Constant Field Values

CODE_REQUEST_STATE_REPLAYED

public static final int CODE_REQUEST_STATE_REPLAYED

MRTR error code: an operator-configured ReplayCache reports that the echoed requestState has already been consumed once before. Only ever thrown when McpMrtrConfig.getReplayCache() is non-null — replay rejection is opt-in (same range/rationale as CODE_REQUEST_STATE_EXPIRED).

See Also:

• Constant Field Values

CODE_REQUEST_STATE_ARGUMENTS_MISMATCH

public static final int CODE_REQUEST_STATE_ARGUMENTS_MISMATCH

MRTR error code: the current request's arguments do not hash to the same value as the arguments sealed at PAUSE time — the client has resumed with a different argument set than the one the paused operation originally authorized. Always checked, unlike CODE_REQUEST_STATE_REPLAYED (same range/rationale as CODE_REQUEST_STATE_EXPIRED).

See Also:

• Constant Field Values

DEFAULT_SERVER_NAME

public static final String DEFAULT_SERVER_NAME

Default server name reported by server/discover when the config supplies no server identity.

See Also:

• Constant Field Values

Constructor Details

McpRevision

public McpRevision(ServerCapabilities capabilities)

Constructor. Uses an empty McpCacheConfig (no cache hints emitted on any result) and no discovery instructions.

Parameters:

capabilities - Explicit capabilities to advertise on server/discover, or null to auto-derive from the registered tool/prompt/resource lists.

McpRevision

public McpRevision(ServerCapabilities capabilities,
 McpCacheConfig cacheConfig)

Constructor. Advertises no discovery instructions.

Parameters:

capabilities - Explicit capabilities to advertise on server/discover, or null to auto-derive from the registered tool/prompt/resource lists.

cacheConfig - Binding-owned cache configuration. Must not be null.

McpRevision

public McpRevision(ServerCapabilities capabilities,
 McpCacheConfig cacheConfig,
 String instructions)

Constructor. Uses a default McpMrtrConfig (AES-GCM ephemeral codec, 5-minute requestState TTL, 10-round cap).

Parameters:

capabilities - Explicit capabilities to advertise on server/discover, or null to auto-derive from the registered tool/prompt/resource lists.

cacheConfig - Binding-owned cache configuration. Must not be null.

instructions - Optional free-form server/discover usage instructions, or null to omit them.

McpRevision

public McpRevision(ServerCapabilities capabilities,
 McpCacheConfig cacheConfig,
 String instructions,
 McpMrtrConfig mrtrConfig)

Constructor.

Parameters:

capabilities - Explicit capabilities to advertise on server/discover, or null to auto-derive from the registered tool/prompt/resource lists.

cacheConfig - Binding-owned cache configuration. Must not be null.

instructions - Optional free-form server/discover usage instructions, or null to omit them.

mrtrConfig - Binding-owned MRTR (Multi-Round-Trip Request) configuration. Must not be null.

Method Details

protocolVersion

public String protocolVersion()

Description copied from interface: McpRevision

The MCP protocol revision string this implementation speaks.

Specified by:

protocolVersion in interface McpRevision

Returns:

The revision token (e.g. "2025-06-18"). Never null.

errorCode

public int errorCode(McpErrorKind kind)

Description copied from interface: McpRevision

Maps a neutral failure classification to this revision's JSON-RPC error code.

Specified by:

errorCode in interface McpRevision

Parameters:

kind - The failure classification. Never null.

Returns:

The JSON-RPC error code this revision reports for that kind.

dispatch

public McpDispatchResult dispatch(McpExchange exchange,
 McpServerConfig config,
 BeanStore ctx)

Description copied from interface: McpRevision

Dispatches one JSON-RPC request.

Specified by:

dispatch in interface McpRevision

Parameters:

exchange - The inbound envelope plus header access. Never null.

config - The neutral handler registry and pagination strategy. Never null.

ctx - The per-request bean store, passed through to handlers. Never null.

Returns:

A McpResponseResult for a normal request, a McpStreamResult (for example wrapping a Flow.Publisher produced by a v2-only method) for a request whose response is not a single JSON-RPC envelope, or null for a notification request (which the HTTP layer renders as an empty body).