ORIONIS API REFERENCE

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

class documentation

Perform no connection negotiation and retain no request or identity.

Async Static Method _catalogResult Extract a catalog result while discarding intermediate stream notifications.
Static Method _cursor Decode and validate a stateless cursor for the requested listing method.
Static Method _subscriptionNotification Encode one change event while retaining subscription metadata ownership.
Method __init__ Bind compiled server metadata and shared services for stateless dispatch.
Async Method _access Resolve a primitive handler and apply its request-specific access hooks.
Method _cache Select cache hints and disable caching for requests carrying retry state.
Async Method _catalog Run a synthetic catalog search or batch-execution operation.
Async Method _complete Resolve completion values through the referenced primitive's access hooks.
Method _encode Validate a result, attach server metadata, and encode its response.
Async Method _execute Route a decoded request to a core method, extension, or primitive.
Async Method _executeCatalog Execute catalog tool calls sequentially with shared validation and access.
Async Method _extension Invoke an extension only when the client advertises its capability.
Async Method _finishStream Close a primitive stream without replacing an escaping primary failure.
Async Method _finishSubscription Join pending subscription work and close the owned event source.
Async Method _invoke Invoke a primitive through the shared policy and validation pipeline.
Async Method _list Build a bounded listing page after per-request access checks.
Async Method _listen Create a subscription stream from supported, currently authorized filters.
Async Method _normalize Normalize developer output into the requested method's validated result.
Async Method _normalizeTyped Validate an existing protocol result without changing observation order.
Async Method _report Observe a dispatch failure with normalized request and error context.
Method _request Build request context from the current envelope and typed parameters.
Method _resource Resolve exact resource URIs before matching compiled URI templates.
Async Method _searchCatalog Rank catalog text and return only request-accessible tool matches.
Async Method _stream Yield progress notifications and a result with bounded response buffering.
Method _streamError Encode a sanitized result or protocol error for a failed primitive stream.
Async Method _subscriptionResource Check subscription access with a temporary resource-specific context.
Async Method _subscriptionStream Yield an acknowledgement, subscription events, and transport keepalives.
Method _supports Check whether a compiled capability explicitly enables a feature.
Method decode Validate core request metadata and decode method-specific parameters.
Async Method dispatch Execute a decoded request with shared policy checks and dependency bindings.
Async Method handle Decode and dispatch one envelope without adding transport framing.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _extensions Extensions registered for this server or transport.
Instance Variable _list_sources Compiled primitive collections used by listing operations.
Instance Variable _server_id Stable server identifier used to bind protected request state.
Instance Variable app Application container supplying configuration and dependencies.
Instance Variable bus Subscription service delivering server changes.
Instance Variable config Validated configuration controlling this component.
Instance Variable server Precompiled metadata shared by request executions.
async def _catalogResult(result: object) -> dict[str, object]: (source)

Extract a catalog result while discarding intermediate stream notifications.

Parameters
result:objectImmediate tool result or asynchronous stream of encoded protocol messages.
Returns
dict[str, object]Built-in immediate result, or the last result mapping received from the stream.
Raises
McpInvalidParamsIf a stream emits a protocol error or finishes without a result.
def _cursor(method: str, cursor: str | msgspec.UnsetType) -> str: (source)

Decode and validate a stateless cursor for the requested listing method.

Parameters
method:strListing method to which the cursor must be bound.
cursor:str | msgspec.UnsetTypeEncoded cursor, or msgspec.UNSET for the first page.
Returns
strLast primitive name from the cursor, or "" for the first page.
Raises
McpInvalidParamsIf the cursor encoding, contents, or bound method is invalid.
def _subscriptionNotification(method: str, uri: str | None, metadata: dict[str, object]) -> bytes: (source)

Encode one change event while retaining subscription metadata ownership.

Parameters
method:strNotification method from the event source.
uri:str or NoneAuthorized resource URI, when this event identifies a resource.
metadata:dict[str, object]Subscription metadata retained by the surrounding stream.
Returns
bytesEncoded change notification.
def __init__(self, app: IContainer, compiled: CompiledMcpServer, config: McpConfig, event_bus: IMcpEventBus): (source)

Bind compiled server metadata and shared services for stateless dispatch.

Parameters
app:orionis.container.contracts.container.IContainerContainer used to build handlers and register request-scoped bindings.
compiled:orionis.mcp.server.compiler.CompiledMcpServerCompiled server definitions, primitives, and extension metadata.
config:orionis.mcp.config.McpConfigLimits and protocol options shared by dispatcher calls.
event_bus:orionis.mcp.contracts.event_bus.IMcpEventBusEvent service used to open change-notification subscriptions.
Returns
NoneStore shared services and precompute extension and listing lookups.
async def _access(self, primitive: CompiledPrimitive, request: McpRequest, *, listing: bool = False) -> object | None: (source)

Resolve a primitive handler and apply its request-specific access hooks.

Return synthetic primitives directly without invoking handler access hooks.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitiveCompiled tool, resource, prompt, or synthetic catalog declaration.
request:orionis.mcp.McpRequestContext supplied to availability and authorization hooks.
listing:bool, optionalReturn None for unavailable or unauthorized entries instead of raising.
Returns
object | NoneResolved handler, the synthetic primitive itself, or None when a listing entry is denied.
Raises
McpInvalidParamsIf the primitive is unavailable and listing is false.
McpAuthorizationExceptionIf authorization is denied and listing is false.
def _cache(self, primitive: CompiledPrimitive | None = None, request: McpRequest | None = None) -> CacheOptions: (source)

Select cache hints and disable caching for requests carrying retry state.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitive or None, optionalPrimitive cache policy, or None to use server defaults.
request:orionis.mcp.McpRequest or None, optionalRequest whose input-response or retry state can disable caching.
Returns
orionis.mcp.normalization.CacheOptionsCache fields ttlMs and cacheScope. Input-response or request-state data forces zero TTL and private scope.
async def _catalog(self, primitive: CompiledPrimitive, request: McpRequest) -> CallToolResult | InputRequiredResult: (source)

Run a synthetic catalog search or batch-execution operation.

Report tool-error outcomes and bound completed catalog responses by the configured output-size limit.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitiveSynthetic primitive identifying the catalog and operation.
request:orionis.mcp.McpRequestContext supplying search arguments or catalog tool calls.
Returns
CallToolResult or InputRequiredResultTool-search or batch result, or a single-tool input-required response.
Raises
McpInvalidParamsIf the primitive has no catalog or completed output exceeds its budget.
async def _complete(self, request: McpRequest, params: CompleteParams) -> CompleteCompletionResult: (source)

Resolve completion values through the referenced primitive's access hooks.

Parameters
request:orionis.mcp.McpRequestContext supplied to access and completion hooks.
params:orionis.mcp.protocol.requests.CompleteParamsReference, argument, and context for a prompt or template completion.
Returns
orionis.mcp.protocol.results.CompleteCompletionResultCompletion containing a validated, bounded sequence of string values.
Raises
McpProtocolExceptionIf the server does not advertise completion support.
McpInvalidParamsIf the reference, argument names, or returned completion values are invalid.
def _encode(self, request: McpRequest, result: object, *, internal_meta: dict[str, object] | None = None) -> bytes: (source)

Validate a result, attach server metadata, and encode its response.

Parameters
request:orionis.mcp.McpRequestRequest supplying the response identifier and protocol method.
result:objectCompletion or input-required result to validate and encode.
internal_meta:dict[str, object] or None, optionalMetadata merged over result metadata before server identity is set.
Returns
bytesJSON-RPC response bytes within the configured response-size budget.
Raises
TypeErrorIf the result is neither a complete nor input-required result.
ValueErrorIf result metadata exceeds its configured size limit.
McpProtocolExceptionIf the encoded response exceeds its configured size limit.
async def _execute(self, request: McpRequest, params: RequestParams) -> object: (source)

Route a decoded request to a core method, extension, or primitive.

Parameters
request:orionis.mcp.McpRequestRequest context identifying the operation and its caller.
params:orionis.mcp.protocol.requests.RequestParamsTyped parameters selecting the operation and target primitive.
Returns
objectOperation result, or an asynchronous byte stream for streamed calls.
Raises
McpProtocolExceptionIf the method is unsupported or an operation-specific protocol check fails.
McpInvalidParamsIf the requested primitive is unknown or unavailable.
async def _executeCatalog(self, catalog: CompiledCatalog, request: McpRequest) -> McpResponse | InputRequiredResult: (source)

Execute catalog tool calls sequentially with shared validation and access.

Stop after the first tool error. Return an error when a multi-call batch requires additional input, preserving input-required results for single calls.

Parameters
catalog:orionis.mcp.server.compiler.CompiledCatalogCompiled tools that this catalog permits callers to execute.
request:orionis.mcp.McpRequestContext containing the ordered tool-call batch.
Returns
McpResponse or InputRequiredResultCompleted call results, a batch input-required error, or a single-call input-required protocol response.
Raises
McpInvalidParamsIf the call count, target name, or accumulated output size is invalid.
async def _extension(self, request: McpRequest, params: RequestParams) -> object: (source)

Invoke an extension only when the client advertises its capability.

Parameters
request:orionis.mcp.McpRequestRequest context containing the method and client capability metadata.
params:orionis.mcp.protocol.requests.RequestParamsParameters accepted by the extension's decoder.
Returns
objectHandler result, awaited when the extension returns an awaitable.
Raises
McpProtocolExceptionIf the client has not advertised the required extension capability.
async def _finishStream(self, request: McpRequest, source: AsyncIterator[object], original: BaseException | None): (source)

Close a primitive stream without replacing an escaping primary failure.

Parameters
request:orionis.mcp.McpRequestRequest context attached to cleanup failure observation.
source:collections.abc.AsyncIterator[object]Source whose optional asynchronous close hook should run.
original:BaseException or NoneEscaping control-flow failure to preserve if cleanup also fails.
Returns
NoneFinish any asynchronous source cleanup.
Raises
BaseExceptionIf cleanup fails; re-raise original from that failure when supplied, otherwise propagate the cleanup failure.
async def _finishSubscription(self, request: McpRequest, pending: asyncio.Future | None, source: object, original: BaseException | None): (source)

Join pending subscription work and close the owned event source.

Parameters
request:orionis.mcp.McpRequestContext attached to subscription cleanup failure observation.
pending:asyncio.Future or NonePending source-advance operation to cancel and join, if any.
source:objectEvent source whose optional asynchronous close hook should run.
original:BaseException or NoneEscaping subscription failure to preserve if source cleanup also fails.
Returns
NoneObserve pending-operation failures and finish source cleanup.
Raises
BaseExceptionIf cleanup fails or caller cancellation must propagate. Keep original primary when source closure also fails.
async def _invoke(self, primitive: CompiledPrimitive, request: McpRequest) -> object: (source)

Invoke a primitive through the shared policy and validation pipeline.

Return tool-error results for invalid tool arguments and ordinary tool-handler failures.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitiveCompiled tool, resource, prompt, or synthetic catalog declaration.
request:orionis.mcp.McpRequestContext supplying arguments, retry state, and handler dependencies.
Returns
objectNormalized result, input-required response, or owned stream of encoded messages.
Raises
McpProtocolExceptionIf access or protocol checks fail, or a non-tool handler raises.
async def _list(self, request: McpRequest, params: PaginatedParams) -> object: (source)

Build a bounded listing page after per-request access checks.

Parameters
request:orionis.mcp.McpRequestContext selecting a listing method and its access policies.
params:orionis.mcp.protocol.requests.PaginatedParamsListing parameters containing the previous page boundary, if any.
Returns
objectMethod-specific listing with visible primitive metadata, a continuation cursor when needed, and server cache hints.
Raises
McpInvalidParamsIf the pagination cursor is invalid or belongs to another method.
async def _listen(self, request: McpRequest, params: ListenParams) -> AsyncIterator[bytes]: (source)

Create a subscription stream from supported, currently authorized filters.

Parameters
request:orionis.mcp.McpRequestRequest context used for resource-subscription access checks.
params:orionis.mcp.protocol.requests.ListenParamsRequested change notifications and resource-subscription URIs.
Returns
collections.abc.AsyncIterator[bytes]Owned byte stream carrying the accepted subscription filters and events.
Raises
McpInvalidParamsIf the resource-subscription count exceeds its limit or a checked URI is invalid.
async def _normalize(self, primitive: CompiledPrimitive, request: McpRequest, result: object) -> object: (source)

Normalize developer output into the requested method's validated result.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitivePrimitive supplying output validation, descriptions, and cache policy.
request:orionis.mcp.McpRequestContext identifying the result method and any input-response retry.
result:objectDeveloper return value or an already typed protocol result.
Returns
objectValidated method result, including input-required or tool-error results when applicable.
async def _normalizeTyped(self, primitive: CompiledPrimitive, request: McpRequest, result: object) -> object: (source)

Validate an existing protocol result without changing observation order.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitiveOutput schema and resource cache policy.
request:orionis.mcp.McpRequestResult method and reporting context.
result:objectResult already matching the requested protocol result type.
Returns
objectValidated result with normalized data and resource metadata.
async def _report(self, exception: BaseException, request: McpRequest | None = None, *, transport: str = 'in-process', phase: str = 'execution', expected: bool = False, correlation_id: str | int | None = None, operation_name: str | None = None): (source)

Observe a dispatch failure with normalized request and error context.

Reclassify JSON-RPC internal errors by status, treating 503 as expected. If such an error wraps an Exception, report its cause as unexpected.

Parameters
exception:BaseExceptionFailure to observe, optionally unwrapped from an internal protocol error.
request:orionis.mcp.McpRequest or None, optionalContext whose transport, method, and identifier override fallbacks.
transport:str, optionalTransport name used when no request context is supplied.
phase:str, optionalExecution or lifecycle phase attached to the failure.
expected:bool, optionalExpected-failure flag, overridden for internal errors as described above.
correlation_id:str | int | None, optionalRequest identifier used when request is absent.
operation_name:str or None, optionalProtocol method or operation name used without request context.
Returns
NoneAwait shared MCP failure observation without constructing a reply.
def _request(self, envelope: JsonRpcRequest, params: RequestParams, transport: TransportName, native: http_module.Request | None) -> McpRequest: (source)

Build request context from the current envelope and typed parameters.

Parameters
envelope:orionis.mcp.protocol.requests.JsonRpcRequestEnvelope supplying the request identifier and method.
params:orionis.mcp.protocol.requests.RequestParamsTyped arguments, metadata, resource URI, and input-response retry state.
transport:orionis.mcp.dispatcher.TransportNameTransport identifier to store in the request context.
native:orionis.http.Request or NoneNative request to expose in context, or None.
Returns
orionis.mcp.McpRequestContext exposing arguments, metadata, retry state, and transport details.
def _resource(self, request: McpRequest, uri: str) -> tuple[CompiledPrimitive | None, McpRequest]: (source)

Resolve exact resource URIs before matching compiled URI templates.

Parameters
request:orionis.mcp.McpRequestBase request context to enrich when a URI template matches.
uri:strResource URI to validate and resolve.
Returns
tuple[CompiledPrimitive | None, McpRequest]Primitive and context, enriched with URI variables for a template match, or (None, request) when no definition matches.
Raises
McpInvalidParamsIf the supplied resource URI is invalid.
async def _searchCatalog(self, catalog: CompiledCatalog, request: McpRequest) -> McpResponse: (source)

Rank catalog text and return only request-accessible tool matches.

Parameters
catalog:orionis.mcp.server.compiler.CompiledCatalogCompiled lexical index and tools available to this catalog.
request:orionis.mcp.McpRequestContext supplying search terms, result limits, and access checks.
Returns
orionis.mcp.McpResponseStructured tools matches ordered by descending term score, then name, within the requested and configured result limits.
async def _stream(self, primitive: CompiledPrimitive, request: McpRequest, source: AsyncIterator[object]) -> AsyncIterator[bytes]: (source)

Yield progress notifications and a result with bounded response buffering.

Enforce the response-size budget for accumulated non-progress values.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitivePrimitive supplying result normalization and output validation.
request:orionis.mcp.McpRequestContext supplying the response identifier and optional progress token.
source:collections.abc.AsyncIterator[object]Primitive iterator to consume and close when streaming ends.
Yields
bytesUnframed JSON progress notifications when requested, followed by a result or sanitized error response.
Raises
BaseExceptionIf cancellation or other control flow escapes, or source cleanup fails.
def _streamError(self, request: McpRequest) -> bytes: (source)

Encode a sanitized result or protocol error for a failed primitive stream.

Parameters
request:orionis.mcp.McpRequestContext whose method selects a tool-error result or protocol error.
Returns
bytesEncoded tool-error result for tool calls, or an internal JSON-RPC error.
async def _subscriptionResource(self, request: McpRequest, uri: str) -> bool: (source)

Check subscription access with a temporary resource-specific context.

Restore the original request binding after access checks.

Parameters
request:orionis.mcp.McpRequestOriginal request context to restore after checking the resource.
uri:strResource URI whose existence and access hooks should be checked.
Returns
boolTrue for a known resource passing its access hooks; False for unknown, unavailable, or unauthorized resources.
Raises
McpInvalidParamsIf the resource URI is invalid.
async def _subscriptionStream(self, request: McpRequest, filters: SubscriptionFilter, source: AsyncIterator[tuple[str, str | None]]) -> AsyncIterator[bytes]: (source)

Yield an acknowledgement, subscription events, and transport keepalives.

Parameters
request:orionis.mcp.McpRequestContext supplying subscription identity and transport behavior.
filters:orionis.mcp.protocol.requests.SubscriptionFilterAccepted notification flags and resource subscriptions.
source:collections.abc.AsyncIterator[tuple[str, str | None]]Change events containing a notification method and optional resource URI.
Yields
bytesEncoded acknowledgement, change notifications, and final completion. HTTP keepalives are b""; stdio also emits a cancellation notification when the event source ends.
Raises
BaseExceptionIf event delivery or cleanup fails, or iteration is cancelled.
def _supports(self, capability: str, feature: str) -> bool: (source)

Check whether a compiled capability explicitly enables a feature.

Parameters
capability:strCompiled capability section to inspect.
feature:strFeature flag within the capability mapping.
Returns
boolTrue only when the capability maps the feature to True.
def decode(self, envelope: JsonRpcRequest) -> RequestParams: (source)

Validate core request metadata and decode method-specific parameters.

Parameters
envelope:orionis.mcp.protocol.requests.JsonRpcRequestDecoded envelope whose method selects the parameter schema.
Returns
orionis.mcp.protocol.requests.RequestParamsValidated core parameters or the extension decoder's typed parameters.
Raises
McpInvalidParamsIf an extension payload cannot be decoded.
TypeErrorIf an extension decoder returns something other than RequestParams.
async def dispatch(self, envelope: JsonRpcRequest, params: RequestParams, *, transport: TransportName = 'test', native_request: http_module.Request | None = None) -> DispatchResult: (source)

Execute a decoded request with shared policy checks and dependency bindings.

Parameters
envelope:orionis.mcp.protocol.requests.JsonRpcRequestEnvelope supplying the request identifier and method.
params:orionis.mcp.protocol.requests.RequestParamsMethod parameters already decoded by decode or the transport.
transport:orionis.mcp.dispatcher.TransportName, optionalTransport identifier included in request context and failure metadata.
native_request:orionis.http.Request or None, optionalNative request to expose to handlers, when available.
Returns
orionis.mcp.dispatcher.DispatchResultEncoded result, sanitized error, or lazy byte stream. Notifications return an empty 202 response.
Raises
BaseExceptionIf cancellation or other non-Exception control flow interrupts execution.
async def handle(self, data: bytes, *, transport: TransportName = 'test', native_request: http_module.Request | None = None) -> DispatchResult: (source)

Decode and dispatch one envelope without adding transport framing.

Parameters
data:bytesEncoded JSON-RPC envelope; the transport owns framing and request scope.
transport:orionis.mcp.dispatcher.TransportName, optionalTransport identifier recorded in execution and failure metadata.
native_request:orionis.http.Request or None, optionalNative request to attach to the execution context, when available.
Returns
orionis.mcp.dispatcher.DispatchResultEncoded reply or lazy byte stream. Notifications return an empty 202 response; protocol decoding errors retain their response status.
Raises
BaseExceptionIf an unexpected decoder failure or unhandled control-flow interruption must propagate.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_extensions = (source)

Extensions registered for this server or transport.

_list_sources = (source)

Compiled primitive collections used by listing operations.

_server_id = (source)

Stable server identifier used to bind protected request state.

Application container supplying configuration and dependencies.

Subscription service delivering server changes.

Validated configuration controlling this component.

Precompiled metadata shared by request executions.