orchestrata_ultimate.gateway.mcp_tool_spec

Reference › orchestrata_ultimate › gateway › mcp_tool_spec

McpToolSpec is a frozen dataclass describing one MCP tool backed by one gateway JSON-RPC method (SPEC-014 REQ-014-204). Its fields are the tool name, the method, a description, an input schema and a gated flag. from_method adapts a method_spec row: dots in the method name become underscores (volk.list becomes volk_list), the description falls back to a generic line, and for a mutating method the schema gains a string argument for the single-use approval token and gated is set. mcp_transport builds its tool table from these.

At a glance

Class diagram

Dependency diagram

API

Classes

McpToolSpec (dataclass)

Decorators: traces(spec='014', story='US-013', reqs=['REQ-014-204']), dataclass(frozen=True) · Line 25

One MCP tool backed by one gateway JSON-RPC method.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/gateway/mcp_tool_spec.py

"""McpToolSpec -- one generated MCP tool, adapted from a MethodSpec.

ADR-0099 rule 2: the tool list is generated from the gateway's method table,
never hand-written. A gated (mutating) method also takes the server-issued
``approval_token`` argument.

Author: Mohamed
"""

# Spec: 014 - WebSocket Gateway

from __future__ import annotations

from dataclasses import dataclass
from typing import Any

from orchestrata_ultimate.core.base.traces import traces
from orchestrata_ultimate.gateway.method_spec import MethodSpec

TOKEN_ARG = "approval_token"


@traces(spec="014", story="US-013", reqs=["REQ-014-204"])
@dataclass(frozen=True)
class McpToolSpec:
    """One MCP tool backed by one gateway JSON-RPC method."""

    name: str
    method: str
    description: str
    input_schema: dict[str, Any]
    gated: bool

    @classmethod
    def from_method(cls, spec: MethodSpec) -> McpToolSpec:
        """Adapt a table row. MCP tool names cannot contain ``.``, so the
        method name's dots become underscores (``volk.list`` -> ``volk_list``).
        """
        schema = spec.input_schema()
        if spec.mutates:
            schema = {
                **schema,
                "properties": {
                    **schema.get("properties", {}),
                    TOKEN_ARG: {
                        "type": "string",
                        "description": "single-use token from the `approve` tool",
                    },
                },
            }
        description = spec.description or f"Gateway method {spec.name}."
        return cls(
            name=spec.name.replace(".", "_"),
            method=spec.name,
            description=description,
            input_schema=schema,
            gated=spec.mutates,
        )