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 McpDispatcher: (source)
Constructor: McpDispatcher(app, compiled, config, event_bus)
Perform no connection negotiation and retain no request or identity.
| Async Static Method | _catalog |
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 | _subscription |
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 | _execute |
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 | _finish |
Close a primitive stream without replacing an escaping primary failure. |
| Async Method | _finish |
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 | _normalize |
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 | _search |
Rank catalog text and return only request-accessible tool matches. |
| Async Method | _stream |
Yield progress notifications and a result with bounded response buffering. |
| Method | _stream |
Encode a sanitized result or protocol error for a failed primitive stream. |
| Async Method | _subscription |
Check subscription access with a temporary resource-specific context. |
| Async Method | _subscription |
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 |
Compiled primitive collections used by listing operations. |
| Instance Variable | _server |
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. |
Extract a catalog result while discarding intermediate stream notifications.
| Parameters | |
result:object | Immediate 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 | |
McpInvalidParams | If a stream emits a protocol error or finishes without a result. |
Decode and validate a stateless cursor for the requested listing method.
| Parameters | |
method:str | Listing method to which the cursor must be bound. |
cursor:str | msgspec.UnsetType | Encoded cursor, or msgspec.UNSET for the first page. |
| Returns | |
str | Last primitive name from the cursor, or "" for the first page. |
| Raises | |
McpInvalidParams | If the cursor encoding, contents, or bound method is invalid. |
str, uri: str | None, metadata: dict[ str, object]) -> bytes:
(source)
¶
Encode one change event while retaining subscription metadata ownership.
| Parameters | |
method:str | Notification method from the event source. |
uri:str or None | Authorized resource URI, when this event identifies a resource. |
metadata:dict[str, object] | Subscription metadata retained by the surrounding stream. |
| Returns | |
bytes | Encoded change notification. |
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.IContainer | Container used to build handlers and register request-scoped bindings. |
compiled:orionis.mcp.server.compiler.CompiledMcpServer | Compiled server definitions, primitives, and extension metadata. |
config:orionis.mcp.config.McpConfig | Limits and protocol options shared by dispatcher calls. |
eventorionis.mcp.contracts.event_bus.IMcpEventBus | Event service used to open change-notification subscriptions. |
| Returns | |
None | Store shared services and precompute extension and listing lookups. |
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.CompiledPrimitive | Compiled tool, resource, prompt, or synthetic catalog declaration. |
request:orionis.mcp.McpRequest | Context supplied to availability and authorization hooks. |
listing:bool, optional | Return None for unavailable or unauthorized entries instead of raising. |
| Returns | |
object | None | Resolved handler, the synthetic primitive itself, or None when a listing entry is denied. |
| Raises | |
McpInvalidParams | If the primitive is unavailable and listing is false. |
McpAuthorizationException | If authorization is denied and listing is false. |
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, optional | Primitive cache policy, or None to use server defaults. |
request:orionis.mcp.McpRequest or None, optional | Request whose input-response or retry state can disable caching. |
| Returns | |
orionis.mcp.normalization.CacheOptions | Cache fields ttlMs and cacheScope. Input-response or request-state data forces zero TTL and private scope. |
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.CompiledPrimitive | Synthetic primitive identifying the catalog and operation. |
request:orionis.mcp.McpRequest | Context supplying search arguments or catalog tool calls. |
| Returns | |
CallToolResult or InputRequiredResult | Tool-search or batch result, or a single-tool input-required response. |
| Raises | |
McpInvalidParams | If the primitive has no catalog or completed output exceeds its budget. |
McpRequest, params: CompleteParams) -> CompleteCompletionResult:
(source)
¶
Resolve completion values through the referenced primitive's access hooks.
| Parameters | |
request:orionis.mcp.McpRequest | Context supplied to access and completion hooks. |
params:orionis.mcp.protocol.requests.CompleteParams | Reference, argument, and context for a prompt or template completion. |
| Returns | |
orionis.mcp.protocol.results.CompleteCompletionResult | Completion containing a validated, bounded sequence of string values. |
| Raises | |
McpProtocolException | If the server does not advertise completion support. |
McpInvalidParams | If the reference, argument names, or returned completion values are invalid. |
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.McpRequest | Request supplying the response identifier and protocol method. |
result:object | Completion or input-required result to validate and encode. |
internaldict[str, object] or None, optional | Metadata merged over result metadata before server identity is set. |
| Returns | |
bytes | JSON-RPC response bytes within the configured response-size budget. |
| Raises | |
TypeError | If the result is neither a complete nor input-required result. |
ValueError | If result metadata exceeds its configured size limit. |
McpProtocolException | If the encoded response exceeds its configured size limit. |
Route a decoded request to a core method, extension, or primitive.
| Parameters | |
request:orionis.mcp.McpRequest | Request context identifying the operation and its caller. |
params:orionis.mcp.protocol.requests.RequestParams | Typed parameters selecting the operation and target primitive. |
| Returns | |
object | Operation result, or an asynchronous byte stream for streamed calls. |
| Raises | |
McpProtocolException | If the method is unsupported or an operation-specific protocol check fails. |
McpInvalidParams | If the requested primitive is unknown or unavailable. |
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.CompiledCatalog | Compiled tools that this catalog permits callers to execute. |
request:orionis.mcp.McpRequest | Context containing the ordered tool-call batch. |
| Returns | |
McpResponse or InputRequiredResult | Completed call results, a batch input-required error, or a single-call input-required protocol response. |
| Raises | |
McpInvalidParams | If the call count, target name, or accumulated output size is invalid. |
Invoke an extension only when the client advertises its capability.
| Parameters | |
request:orionis.mcp.McpRequest | Request context containing the method and client capability metadata. |
params:orionis.mcp.protocol.requests.RequestParams | Parameters accepted by the extension's decoder. |
| Returns | |
object | Handler result, awaited when the extension returns an awaitable. |
| Raises | |
McpProtocolException | If the client has not advertised the required extension capability. |
McpRequest, source: AsyncIterator[ object], original: BaseException | None):
(source)
¶
Close a primitive stream without replacing an escaping primary failure.
| Parameters | |
request:orionis.mcp.McpRequest | Request context attached to cleanup failure observation. |
source:collections.abc.AsyncIterator[object] | Source whose optional asynchronous close hook should run. |
original:BaseException or None | Escaping control-flow failure to preserve if cleanup also fails. |
| Returns | |
None | Finish any asynchronous source cleanup. |
| Raises | |
BaseException | If cleanup fails; re-raise original from that failure when supplied, otherwise propagate the cleanup failure. |
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.McpRequest | Context attached to subscription cleanup failure observation. |
pending:asyncio.Future or None | Pending source-advance operation to cancel and join, if any. |
source:object | Event source whose optional asynchronous close hook should run. |
original:BaseException or None | Escaping subscription failure to preserve if source cleanup also fails. |
| Returns | |
None | Observe pending-operation failures and finish source cleanup. |
| Raises | |
BaseException | If cleanup fails or caller cancellation must propagate. Keep original primary when source closure also fails. |
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.CompiledPrimitive | Compiled tool, resource, prompt, or synthetic catalog declaration. |
request:orionis.mcp.McpRequest | Context supplying arguments, retry state, and handler dependencies. |
| Returns | |
object | Normalized result, input-required response, or owned stream of encoded messages. |
| Raises | |
McpProtocolException | If access or protocol checks fail, or a non-tool handler raises. |
Build a bounded listing page after per-request access checks.
| Parameters | |
request:orionis.mcp.McpRequest | Context selecting a listing method and its access policies. |
params:orionis.mcp.protocol.requests.PaginatedParams | Listing parameters containing the previous page boundary, if any. |
| Returns | |
object | Method-specific listing with visible primitive metadata, a continuation cursor when needed, and server cache hints. |
| Raises | |
McpInvalidParams | If the pagination cursor is invalid or belongs to another method. |
McpRequest, params: ListenParams) -> AsyncIterator[ bytes]:
(source)
¶
Create a subscription stream from supported, currently authorized filters.
| Parameters | |
request:orionis.mcp.McpRequest | Request context used for resource-subscription access checks. |
params:orionis.mcp.protocol.requests.ListenParams | Requested change notifications and resource-subscription URIs. |
| Returns | |
collections.abc.AsyncIterator[bytes] | Owned byte stream carrying the accepted subscription filters and events. |
| Raises | |
McpInvalidParams | If the resource-subscription count exceeds its limit or a checked URI is invalid. |
CompiledPrimitive, request: McpRequest, result: object) -> object:
(source)
¶
Normalize developer output into the requested method's validated result.
| Parameters | |
primitive:orionis.mcp.server.compiler.CompiledPrimitive | Primitive supplying output validation, descriptions, and cache policy. |
request:orionis.mcp.McpRequest | Context identifying the result method and any input-response retry. |
result:object | Developer return value or an already typed protocol result. |
| Returns | |
object | Validated method result, including input-required or tool-error results when applicable. |
CompiledPrimitive, request: McpRequest, result: object) -> object:
(source)
¶
Validate an existing protocol result without changing observation order.
| Parameters | |
primitive:orionis.mcp.server.compiler.CompiledPrimitive | Output schema and resource cache policy. |
request:orionis.mcp.McpRequest | Result method and reporting context. |
result:object | Result already matching the requested protocol result type. |
| Returns | |
object | Validated result with normalized data and resource metadata. |
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:BaseException | Failure to observe, optionally unwrapped from an internal protocol error. |
request:orionis.mcp.McpRequest or None, optional | Context whose transport, method, and identifier override fallbacks. |
transport:str, optional | Transport name used when no request context is supplied. |
phase:str, optional | Execution or lifecycle phase attached to the failure. |
expected:bool, optional | Expected-failure flag, overridden for internal errors as described above. |
correlationstr | int | None, optional | Request identifier used when request is absent. |
operationstr or None, optional | Protocol method or operation name used without request context. |
| Returns | |
None | Await shared MCP failure observation without constructing a reply. |
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.JsonRpcRequest | Envelope supplying the request identifier and method. |
params:orionis.mcp.protocol.requests.RequestParams | Typed arguments, metadata, resource URI, and input-response retry state. |
transport:orionis.mcp.dispatcher.TransportName | Transport identifier to store in the request context. |
native:orionis.http.Request or None | Native request to expose in context, or None. |
| Returns | |
orionis.mcp.McpRequest | Context exposing arguments, metadata, retry state, and transport details. |
McpRequest, uri: str) -> tuple[ CompiledPrimitive | None, McpRequest]:
(source)
¶
Resolve exact resource URIs before matching compiled URI templates.
| Parameters | |
request:orionis.mcp.McpRequest | Base request context to enrich when a URI template matches. |
uri:str | Resource 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 | |
McpInvalidParams | If the supplied resource URI is invalid. |
CompiledCatalog, request: McpRequest) -> McpResponse:
(source)
¶
Rank catalog text and return only request-accessible tool matches.
| Parameters | |
catalog:orionis.mcp.server.compiler.CompiledCatalog | Compiled lexical index and tools available to this catalog. |
request:orionis.mcp.McpRequest | Context supplying search terms, result limits, and access checks. |
| Returns | |
orionis.mcp.McpResponse | Structured tools matches ordered by descending term score, then name, within the requested and configured result limits. |
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.CompiledPrimitive | Primitive supplying result normalization and output validation. |
request:orionis.mcp.McpRequest | Context supplying the response identifier and optional progress token. |
source:collections.abc.AsyncIterator[object] | Primitive iterator to consume and close when streaming ends. |
| Yields | |
bytes | Unframed JSON progress notifications when requested, followed by a result or sanitized error response. |
| Raises | |
BaseException | If cancellation or other control flow escapes, or source cleanup fails. |
Encode a sanitized result or protocol error for a failed primitive stream.
| Parameters | |
request:orionis.mcp.McpRequest | Context whose method selects a tool-error result or protocol error. |
| Returns | |
bytes | Encoded tool-error result for tool calls, or an internal JSON-RPC error. |
Check subscription access with a temporary resource-specific context.
Restore the original request binding after access checks.
| Parameters | |
request:orionis.mcp.McpRequest | Original request context to restore after checking the resource. |
uri:str | Resource URI whose existence and access hooks should be checked. |
| Returns | |
bool | True for a known resource passing its access hooks; False for unknown, unavailable, or unauthorized resources. |
| Raises | |
McpInvalidParams | If the resource URI is invalid. |
McpRequest, filters: SubscriptionFilter, source: AsyncIterator[ tuple[ str, str | None]]) -> AsyncIterator[ bytes]:
(source)
¶
Yield an acknowledgement, subscription events, and transport keepalives.
| Parameters | |
request:orionis.mcp.McpRequest | Context supplying subscription identity and transport behavior. |
filters:orionis.mcp.protocol.requests.SubscriptionFilter | Accepted notification flags and resource subscriptions. |
source:collections.abc.AsyncIterator[tuple[str, str | None]] | Change events containing a notification method and optional resource URI. |
| Yields | |
bytes | Encoded acknowledgement, change notifications, and final completion. HTTP keepalives are b""; stdio also emits a cancellation notification when the event source ends. |
| Raises | |
BaseException | If event delivery or cleanup fails, or iteration is cancelled. |
Validate core request metadata and decode method-specific parameters.
| Parameters | |
envelope:orionis.mcp.protocol.requests.JsonRpcRequest | Decoded envelope whose method selects the parameter schema. |
| Returns | |
orionis.mcp.protocol.requests.RequestParams | Validated core parameters or the extension decoder's typed parameters. |
| Raises | |
McpInvalidParams | If an extension payload cannot be decoded. |
TypeError | If an extension decoder returns something other than RequestParams. |
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.JsonRpcRequest | Envelope supplying the request identifier and method. |
params:orionis.mcp.protocol.requests.RequestParams | Method parameters already decoded by decode or the transport. |
transport:orionis.mcp.dispatcher.TransportName, optional | Transport identifier included in request context and failure metadata. |
nativeorionis.http.Request or None, optional | Native request to expose to handlers, when available. |
| Returns | |
orionis.mcp.dispatcher.DispatchResult | Encoded result, sanitized error, or lazy byte stream. Notifications return an empty 202 response. |
| Raises | |
BaseException | If cancellation or other non-Exception control flow interrupts execution. |
bytes, *, transport: TransportName = 'test', native_request: http_module.Request | None = None) -> DispatchResult:
(source)
¶
Decode and dispatch one envelope without adding transport framing.
| Parameters | |
data:bytes | Encoded JSON-RPC envelope; the transport owns framing and request scope. |
transport:orionis.mcp.dispatcher.TransportName, optional | Transport identifier recorded in execution and failure metadata. |
nativeorionis.http.Request or None, optional | Native request to attach to the execution context, when available. |
| Returns | |
orionis.mcp.dispatcher.DispatchResult | Encoded reply or lazy byte stream. Notifications return an empty 202 response; protocol decoding errors retain their response status. |
| Raises | |
BaseException | If an unexpected decoder failure or unhandled control-flow interruption must propagate. |