Wire Types Reference

lauren_mcp

lauren-mcp — Model Context Protocol server and client for Lauren applications.

JsonRpcRequest dataclass

JsonRpcRequest(method, params=None, id=None, jsonrpc='2.0')

A JSON-RPC 2.0 request (has both method and id).

JsonRpcNotification dataclass

JsonRpcNotification(method, params=None, jsonrpc='2.0')

A JSON-RPC 2.0 notification (has method but no id).

JsonRpcResponse dataclass

JsonRpcResponse(id, result, jsonrpc='2.0')

A JSON-RPC 2.0 success response.

JsonRpcErrorResponse dataclass

JsonRpcErrorResponse(id, error, jsonrpc='2.0')

A JSON-RPC 2.0 error response.

McpErrorCode

Bases: IntEnum

Standard JSON-RPC and MCP-extension error codes.

ToolSchema dataclass

ToolSchema(
    name,
    description,
    inputSchema=dict(),
    outputSchema=None,
    annotations=None,
    title=None,
)

Descriptor for a single MCP tool.

ResourceSchema dataclass

ResourceSchema(
    uri,
    name,
    description=None,
    mimeType=None,
    title=None,
    annotations=None,
)

Descriptor for a single MCP resource.

PromptSchema dataclass

PromptSchema(
    name, description=None, arguments=list(), title=None
)

Descriptor for a single MCP prompt.

TextContent dataclass

TextContent(text, type='text')

A plain-text content item.

ImageContent dataclass

ImageContent(data, mimeType, type='image')

A base64-encoded image content item.

parse_message

parse_message(raw)

Parse a raw JSON string or bytes into the appropriate JSON-RPC type.

Dispatch rules (per JSON-RPC 2.0 spec):

• Has both method and id → :class:JsonRpcRequest
• Has method but no id → :class:JsonRpcNotification
• Has result (no method) → :class:JsonRpcResponse
• Has error (no method) → :class:JsonRpcErrorResponse

Raises :class:McpParseError on bad JSON, missing jsonrpc field, or a shape that matches none of the above.

Source code in src/lauren_mcp/_types.py

def parse_message(
    raw: str | bytes,
) -> JsonRpcRequest | JsonRpcNotification | JsonRpcResponse | JsonRpcErrorResponse:
    """Parse a raw JSON string or bytes into the appropriate JSON-RPC type.

    Dispatch rules (per JSON-RPC 2.0 spec):

    * Has both ``method`` **and** ``id``          → :class:`JsonRpcRequest`
    * Has ``method`` but **no** ``id``            → :class:`JsonRpcNotification`
    * Has ``result`` (no ``method``)              → :class:`JsonRpcResponse`
    * Has ``error``  (no ``method``)              → :class:`JsonRpcErrorResponse`

    Raises :class:`McpParseError` on bad JSON, missing ``jsonrpc`` field,
    or a shape that matches none of the above.
    """
    if isinstance(raw, bytes):
        raw = raw.decode("utf-8", errors="replace")

    try:
        obj = json.loads(raw)
    except json.JSONDecodeError as exc:
        raise McpParseError(f"Invalid JSON: {exc}") from exc

    if not isinstance(obj, dict):
        raise McpParseError(f"Expected a JSON object, got {type(obj).__name__}")

    jsonrpc = obj.get("jsonrpc")
    if jsonrpc != "2.0":
        raise McpParseError(f"Missing or invalid 'jsonrpc' field: {jsonrpc!r} (expected '2.0')")

    has_method = "method" in obj
    has_id = "id" in obj
    has_result = "result" in obj
    has_error = "error" in obj

    if has_method and has_id:
        # JSON-RPC request
        return JsonRpcRequest(
            method=obj["method"],
            params=obj.get("params"),
            id=obj["id"],
            jsonrpc=jsonrpc,
        )

    if has_method and not has_id:
        # JSON-RPC notification
        return JsonRpcNotification(
            method=obj["method"],
            params=obj.get("params"),
            jsonrpc=jsonrpc,
        )

    if has_result and not has_method:
        # JSON-RPC success response
        return JsonRpcResponse(
            id=obj.get("id"),
            result=obj["result"],
            jsonrpc=jsonrpc,
        )

    if has_error and not has_method:
        # JSON-RPC error response
        err_obj = obj.get("error", {})
        if not isinstance(err_obj, dict):
            raise McpParseError(f"'error' field must be an object, got {type(err_obj).__name__}")
        error = JsonRpcError(
            code=err_obj.get("code", McpErrorCode.INTERNAL_ERROR),
            message=err_obj.get("message", ""),
            data=err_obj.get("data"),
        )
        return JsonRpcErrorResponse(
            id=obj.get("id"),
            error=error,
            jsonrpc=jsonrpc,
        )

    raise McpParseError(f"Cannot determine JSON-RPC message type from fields: {list(obj.keys())}")

build_error_response

build_error_response(id, code, message, data=None)

Construct a :class:JsonRpcErrorResponse from primitive parts.

Source code in src/lauren_mcp/_types.py

def build_error_response(
    id: str | int | None,
    code: int | McpErrorCode,
    message: str,
    data: Any = None,
) -> JsonRpcErrorResponse:
    """Construct a :class:`JsonRpcErrorResponse` from primitive parts."""
    return JsonRpcErrorResponse(
        id=id,
        error=JsonRpcError(code=int(code), message=message, data=data),
    )

AudioContent dataclass

AudioContent(data, mimeType, type='audio')

A base64-encoded audio content item.

data must be base64-encoded audio bytes. mimeType should be a valid audio MIME type such as "audio/wav", "audio/mpeg", or "audio/ogg".

from_bytes classmethod

from_bytes(data, mime_type='audio/wav')

Construct from raw audio data, base64-encoding it automatically.

Source code in src/lauren_mcp/_types.py

@classmethod
def from_bytes(cls, data: bytes, mime_type: str = "audio/wav") -> AudioContent:
    """Construct from raw audio *data*, base64-encoding it automatically."""
    return cls(data=base64.b64encode(data).decode("ascii"), mimeType=mime_type)

ResourceLink dataclass

ResourceLink(
    uri,
    name=None,
    description=None,
    mimeType=None,
    type="resource_link",
)

A lightweight reference to a resource by URI.

Unlike :class:EmbeddedResource, a ResourceLink does not inline the resource's content — it provides only the URI and optional metadata. The MCP client may choose to fetch the resource separately via resources/read if needed.

ToolUseContent dataclass

ToolUseContent(id, name, input, type='tool_use')

A tool invocation block inside a sampling message.

Represents the LLM requesting to call a tool, as returned inside a sampling/createMessage response when the model decides to use a tool. Also used when re-sending past assistant turns that contained tool calls.

Attributes

id: Unique opaque identifier for this tool call, supplied by the model. Must match the tool_use_id of the corresponding :class:ToolResultContent. name: Name of the tool to call. input: Tool arguments as a JSON-serialisable dict. No schema validation is performed here — the tool author is responsible. type: Wire discriminator. Always "tool_use"; do not override.

ToolResultContent dataclass

ToolResultContent(
    tool_use_id,
    content=list(),
    is_error=False,
    type="tool_result",
)

The result of a prior tool invocation, placed in a user-role message.

When the tool author has handled the :class:ToolUseContent from an assistant turn, they create a ToolResultContent and append it as a role="user" :class:SamplingMessage to continue the conversation.

Attributes

tool_use_id: Must match the id of the :class:ToolUseContent this result corresponds to. content: One or more content blocks (text or image) that constitute the tool's output. An empty list is valid (the tool produced no output). is_error: Set to True when the tool call failed; the LLM can then decide how to proceed. type: Wire discriminator. Always "tool_result"; do not override.

ResourceAnnotations dataclass

ResourceAnnotations(audience=None, priority=None)

Annotations attached to an MCP resource for UI and routing hints.

Attributes:

Name	Type	Description
audience	list[Role] | None	List of intended readers; omitted means unrestricted. Valid values are "user" and "assistant".
priority	float | None	Relevance weighting in [0.0, 1.0]. Higher values indicate higher priority. Omitted when not specified.

to_dict

to_dict()

Serialise to the MCP wire representation.

Source code in src/lauren_mcp/_types.py

def to_dict(self) -> dict[str, Any]:
    """Serialise to the MCP wire representation."""
    out: dict[str, Any] = {}
    if self.audience is not None:
        out["audience"] = list(self.audience)
    if self.priority is not None:
        out["priority"] = self.priority
    return out

from_dict classmethod

from_dict(obj)

Deserialise from a wire annotations dict.

Source code in src/lauren_mcp/_types.py

@classmethod
def from_dict(cls, obj: dict[str, Any]) -> ResourceAnnotations:
    """Deserialise from a wire ``annotations`` dict."""
    return cls(
        audience=obj.get("audience"),
        priority=obj.get("priority"),
    )

UrlElicitResult dataclass

UrlElicitResult(action)

Result of a URL-elicitation elicitation/create request.

action values:

• "accept" — the user completed the external URL flow successfully.
• "cancel" — the user dismissed the dialog or the flow was aborted.

Note: URL elicitation has no "decline" state. The only outcomes are completion ("accept") or abandonment ("cancel").

CompletionResult dataclass

CompletionResult(values, total=None, has_more=False)

Result of a completion/complete request.

Root dataclass

Root(uri, name=None)

A filesystem root exposed by an MCP client to servers.