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.

module documentation

Provide mcp server operations.

Includes CompiledPrimitive, CompiledCatalog, CompiledMcpServer, compile_server.

Class _CatalogCall An independent catalog invocation, with no Python call kwargs.
Class _Compiler Own only boot-time schema caches; discard them after the registry is built.
Class _ExecutePayload Request limits are additionally enforced by the dispatcher configuration.
Class _SearchPayload Bounded searchable catalog arguments.
Class CompiledCatalog One hidden catalog and its deterministic boot-time lexical index.
Class CompiledMcpServer A definition reusable by every request, worker and supported transport.
Class CompiledPrimitive Unbound declaration metadata, with no identity or per-call service instance.
Function _capabilities Advertise only the methods and notifications backed by this registry.
Function _extend_metadata Let extensions attach data without changing compiled native contracts.
Function _extensions Reject extension collisions with built-in methods and other extensions.
Function _hook Compile optional per-request checks without resolving a handler instance.
Function _insert Reject collisions at boot instead of changing lookup semantics silently.
Function _metadata Snapshot common metadata before adding primitive-specific wire fields.
Function _name Derive readable kebab names while honoring explicit protocol identifiers.
Function _ordered Keep deterministic name order in the compiled mapping, including URI keys.
Function _resource_registry Reject identical URI/template names and automatically detectable ambiguity.
Function _tool_arguments Enumerate generic Tool arguments in method resolution order.
Function _tool_registry Compile visible and hidden tool namespaces with collision checks.
Function _tool_types Resolve explicit or generic input and output declarations.
Function _validate_static_metadata Check declaration constructors once, keeping validation off list hot paths.
Function _wire Freeze wire metadata into immutable JSON without retaining mutable maps.
Function compile_server Compile one definition without resolving services or retaining runtime state.
Async Function validate_output Enforce the advertised native output type before encoding structured data.
Async Function validate_payload Validate only the tool's argument object, never the HTTP JSON-RPC envelope.
Function validate_prompt_arguments Check required/unknown argument names and the protocol's string values.
Constant _CORE_METHODS Core methods used by compiler.
Constant _NAME Compiled pattern used to recognize name.
Type Alias _JsonObject Type alias for dict[str, object].
def _capabilities(definition: type[Server], tools: Mapping[str, CompiledPrimitive], resources: Mapping[str, CompiledPrimitive], prompts: Mapping[str, CompiledPrimitive], templates: tuple[CompiledPrimitive, ...]) -> dict[str, object]: (source)

Advertise only the methods and notifications backed by this registry.

Parameters
definition:type[orionis.mcp.Server]Class declaration whose metadata is being inspected.
tools:collections.abc.Mapping[str, orionis.mcp.server.compiler.CompiledPrimitive]Value supplied for tools.
resources:Mapping[str, CompiledPrimitive]Value supplied for resources.
prompts:Mapping[str, CompiledPrimitive]Value supplied for prompts.
templates:tuple[orionis.mcp.server.compiler.CompiledPrimitive, ...]Value supplied for templates.
Returns
dict[str, object]Result of the operation described above.
def _extend_metadata(metadata: dict[str, object], extensions: tuple[McpExtension, ...]) -> dict[str, object]: (source)

Let extensions attach data without changing compiled native contracts.

Parameters
metadata:dict[str, object]Metadata associated with the current operation.
extensions:tuple[orionis.mcp.McpExtension, ...]Value supplied for extensions.
Returns
dict[str, object]Result of the operation described above.
def _extensions(definition: type[Server]) -> tuple[McpExtension, ...]: (source)

Reject extension collisions with built-in methods and other extensions.

Parameters
definition:type[orionis.mcp.Server]Class declaration whose metadata is being inspected.
Returns
tuple[orionis.mcp.McpExtension, ...]Result of the operation described above.
def _hook(definition: type, method: str) -> McpInvoker | None: (source)

Compile optional per-request checks without resolving a handler instance.

Parameters
definition:typeClass declaration whose metadata is being inspected.
method:strValue supplied for method.
Returns
orionis.mcp.invoker.McpInvoker | NoneResult of the operation described above.
def _insert(registry: dict[str, CompiledPrimitive], key: str, primitive: CompiledPrimitive): (source)

Reject collisions at boot instead of changing lookup semantics silently.

Parameters
registry:dict[str, orionis.mcp.server.compiler.CompiledPrimitive]Value supplied for registry.
key:strValue supplied for key.
primitive:orionis.mcp.server.compiler.CompiledPrimitiveCompiled tool, resource or prompt declaration.
Returns
NoneComplete the documented operation without returning a value.
def _metadata(definition: type[Primitive], name: str) -> dict[str, object]: (source)

Snapshot common metadata before adding primitive-specific wire fields.

Parameters
definition:type[orionis.mcp.server.primitives.Primitive]Class declaration whose metadata is being inspected.
name:strValue supplied for name.
Returns
dict[str, object]Result of the operation described above.
def _name(definition: type[Primitive]) -> str: (source)

Derive readable kebab names while honoring explicit protocol identifiers.

Parameters
definition:type[orionis.mcp.server.primitives.Primitive]Class declaration whose metadata is being inspected.
Returns
strResult of the operation described above.

Keep deterministic name order in the compiled mapping, including URI keys.

Parameters
registry:dict[str, orionis.mcp.server.compiler.CompiledPrimitive]Value supplied for registry.
Returns
dict[str, orionis.mcp.server.compiler.CompiledPrimitive]Result of the operation described above.
def _resource_registry(compiler: _Compiler, entries: tuple[type[Resource], ...]) -> tuple[dict[str, CompiledPrimitive], tuple[CompiledPrimitive, ...]]: (source)

Reject identical URI/template names and automatically detectable ambiguity.

Parameters
compiler:orionis.mcp.server.compiler._CompilerValue supplied for compiler.
entries:tuple[type[orionis.mcp.Resource], ...]Value supplied for entries.
Returns
tuple[dict[str, CompiledPrimitive], tuple[CompiledPrimitive, ...]]Result of the operation described above.
def _tool_arguments(definition: type[Tool]) -> Iterator[tuple[object, ...]]: (source)

Enumerate generic Tool arguments in method resolution order.

Parameters
definition:type[orionis.mcp.Tool]Tool declaration whose generic bases are inspected.
Yields
tuple[object, ...]Input and output declarations from each Tool generic base.
def _tool_registry(compiler: _Compiler, entries: tuple[object, ...]) -> tuple[dict[str, CompiledPrimitive], dict[str, CompiledPrimitive], tuple[CompiledCatalog, ...]]: (source)

Compile visible and hidden tool namespaces with collision checks.

Parameters
compiler:orionis.mcp.server.compiler._CompilerValue supplied for compiler.
entries:tuple[object, ...]Value supplied for entries.
Returns
tupleResult of the operation described above.
def _tool_types(definition: type[Tool]) -> tuple[object, object]: (source)

Resolve explicit or generic input and output declarations.

Parameters
definition:type[orionis.mcp.Tool]Tool class carrying explicit fields or inherited generic arguments.
Returns
tuple[object, object]Input type and output type, with UNSET for an undeclared output.
def _validate_static_metadata(metadata: dict[str, object], kind: type): (source)

Check declaration constructors once, keeping validation off list hot paths.

Parameters
metadata:dict[str, object]Metadata associated with the current operation.
kind:typeValue supplied for kind.
Returns
NoneComplete the documented operation without returning a value.
def _wire(value: object) -> msgspec.Raw: (source)

Freeze wire metadata into immutable JSON without retaining mutable maps.

Parameters
value:objectValue to inspect, transform or validate.
Returns
msgspec.RawResult of the operation described above.
def compile_server(definition: type[Server]) -> CompiledMcpServer: (source)

Compile one definition without resolving services or retaining runtime state.

Parameters
definition:type[orionis.mcp.Server]Class declaration whose metadata is being inspected.
Returns
orionis.mcp.server.compiler.CompiledMcpServerResult of the operation described above.
async def validate_output(primitive: CompiledPrimitive, value: object) -> object: (source)

Enforce the advertised native output type before encoding structured data.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitiveCompiled tool, resource or prompt declaration.
value:objectValue to inspect, transform or validate.
Returns
objectResult of the operation described above.
async def validate_payload(primitive: CompiledPrimitive, arguments: object) -> object: (source)

Validate only the tool's argument object, never the HTTP JSON-RPC envelope.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitiveCompiled tool, resource or prompt declaration.
arguments:objectArguments supplied for this operation.
Returns
objectResult of the operation described above.
def validate_prompt_arguments(primitive: CompiledPrimitive, arguments: Mapping[str, object]): (source)

Check required/unknown argument names and the protocol's string values.

Parameters
primitive:orionis.mcp.server.compiler.CompiledPrimitiveCompiled tool, resource or prompt declaration.
arguments:collections.abc.Mapping[str, object]Arguments supplied for this operation.
Returns
NoneComplete the documented operation without returning a value.
_CORE_METHODS = (source)

Core methods used by compiler.

Value
frozenset(set(['server/discover',
               'ping',
               'tools/list',
               'tools/call',
               'resources/list',
               'resources/templates/list',
               'resources/read',
...

Compiled pattern used to recognize name.

Value
re.compile(r'[A-Za-z0-9_\.-]{1,128}')

Type alias for dict[str, object].

Value
dict[str, object]