pyfect-dev 0.1.0__py3-none-any.whl

pyfect/ai/_mcp/http_admission.py

@@ -0,0 +1,269 @@
+"""Whether the Streamable HTTP endpoint takes a POST, before any of it runs
+(Effect's ``admitHttp`` and ``selectHttpProtocol``): the session and
+protocol-version headers, a 2026-07-28 request's metadata and routing
+headers, and which batches a revision accepts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+
+from pyfect.ai._mcp.dispatch import CLIENT_CAPABILITIES_META, PROTOCOL_VERSION_META
+from pyfect.ai._mcp.routing_header import decode_routing_header
+from pyfect.ai.mcp_protocol import AnyProtocolAdapter, Registry
+from pyfect.ai.mcp_schema import (
+    HEADER_MISMATCH_ERROR_CODE,
+    INVALID_PARAMS_ERROR_CODE,
+    INVALID_REQUEST_ERROR_CODE,
+    METHOD_NOT_FOUND_ERROR_CODE,
+    PARSE_ERROR_CODE,
+    UNSUPPORTED_PROTOCOL_VERSION_ERROR_CODE,
+    JsonObject,
+    RequestId,
+    parse_request_id,
+)
+
+SESSION_HEADER = "mcp-session-id"
+VERSION_HEADER = "mcp-protocol-version"
+METHOD_HEADER = "mcp-method"
+NAME_HEADER = "mcp-name"
+
+STATELESS_METHODS = frozenset(
+    {
+        "server/discover",
+        "completion/complete",
+        "prompts/get",
+        "prompts/list",
+        "resources/list",
+        "resources/templates/list",
+        "resources/read",
+        "tools/call",
+        "tools/list",
+        "subscriptions/listen",
+        "notifications/cancelled",
+    }
+)
+"""The messages a 2026-07-28 server takes (Effect's ``ClientRpcs``)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Accepted:
+    acknowledge: bool
+    """Nothing in the body expects an answer: reply 202."""
+
+
+@dataclass(frozen=True, slots=True)
+class Rejected:
+    status: int
+    error: JsonObject | None = None
+    """The JSON-RPC error of the reply; none for an empty one."""
+    id: RequestId | None = None
+
+
+type Admission = Accepted | Rejected
+
+type Session = AnyProtocolAdapter | Literal["absent", "unknown"]
+"""The protocol of the session the POST names, when it names a live one."""
+
+
+@dataclass(frozen=True, slots=True)
+class Unparsable:
+    """A body that is not JSON."""
+
+
+def _record(value: object) -> dict[str, Any] | None:
+    return cast("dict[str, Any]", value) if isinstance(value, dict) else None
+
+
+def _is_id(value: object) -> bool:
+    return isinstance(value, str) or (
+        isinstance(value, int | float) and not isinstance(value, bool)
+    )
+
+
+def _error(code: int, message: str, data: object = None) -> JsonObject:
+    error: JsonObject = {"code": code, "message": message}
+    if data is not None:
+        error["data"] = cast("Any", data)
+    return error
+
+
+def _header_mismatch(message: str) -> Rejected:
+    return Rejected(400, _error(HEADER_MISMATCH_ERROR_CODE, message))
+
+
+def has_request_protocol_version(message: object) -> bool:
+    params = _record((_record(message) or {}).get("params")) or {}
+    record = _record(params.get("_meta"))
+    return record is not None and PROTOCOL_VERSION_META in record
+
+
+@dataclass(frozen=True, slots=True)
+class Admitter:
+    registry: Registry
+
+    @property
+    def _stateless(self) -> AnyProtocolAdapter | None:
+        return next((p for p in self.registry.protocols if p.is_stateless), None)
+
+    @property
+    def _has_stateful(self) -> bool:
+        return any(not p.is_stateless for p in self.registry.protocols)
+
+    def unsupported(self, requested: str) -> Rejected:
+        data = {"supported": list(self.registry.versions), "requested": requested}
+        message = f"Unsupported protocol version '{requested}'"
+        return Rejected(400, _error(UNSUPPORTED_PROTOCOL_VERSION_ERROR_CODE, message, data))
+
+    def session(
+        self, headers: Mapping[str, str], session: Session, *, initialize: bool
+    ) -> Rejected | AnyProtocolAdapter | None:
+        """The session's protocol, checked against the version header."""
+        if session == "unknown":
+            return Rejected(404)
+        version = headers.get(VERSION_HEADER)
+        bound = None if session == "absent" else session
+        if not initialize and version is not None:
+            if version not in self.registry.versions:
+                return self.unsupported(version)
+            if (
+                bound is not None
+                and bound.requires_version_header
+                and version != bound.protocol_version
+            ):
+                return _header_mismatch(
+                    f"MCP-Protocol-Version header '{version}' does not match negotiated "
+                    f"protocol version '{bound.protocol_version}'"
+                )
+        return bound
+
+    def select(  # noqa: PLR0911
+        self, headers: Mapping[str, str], input: object, session: Session
+    ) -> Rejected | AnyProtocolAdapter | None:
+        """The protocol ``input`` is served on (``None``: no session yet)."""
+        version = headers.get(VERSION_HEADER)
+        record = _record(input)
+        params = _record((record or {}).get("params"))
+        metadata = _record((params or {}).get("_meta"))
+        claimed = metadata is not None and PROTOCOL_VERSION_META in metadata
+        claim = metadata.get(PROTOCOL_VERSION_META) if metadata is not None else None
+        id = (record or {}).get("id")
+        is_rpc = record is not None and record.get("jsonrpc") == "2.0"
+        method = (record or {}).get("method")
+        initialize = is_rpc and method == "initialize" and _is_id(id)
+        cancellation = is_rpc and method == "notifications/cancelled" and "id" not in (record or {})
+        stateless = self._stateless
+        has_stateful = self._has_stateful
+        stateless_request = claimed or (
+            (not initialize or not has_stateful)
+            and stateless is not None
+            and (
+                version == stateless.protocol_version
+                or (not has_stateful and is_rpc and isinstance(method, str) and _is_id(id))
+            )
+        )
+        if not stateless_request:
+            return self.session(headers, session, initialize=initialize)
+        if version is None:
+            return _header_mismatch("MCP-Protocol-Version header is required")
+        if not cancellation and (metadata is None or not isinstance(claim, str)):
+            return Rejected(
+                400, _error(INVALID_PARAMS_ERROR_CODE, "Required request metadata is missing")
+            )
+        if (not cancellation or claimed) and claim != version:
+            return _header_mismatch("MCP-Protocol-Version header does not match request metadata")
+        if not cancellation and _record((metadata or {}).get(CLIENT_CAPABILITIES_META)) is None:
+            return Rejected(
+                400,
+                _error(
+                    INVALID_PARAMS_ERROR_CODE,
+                    f"{CLIENT_CAPABILITIES_META} request metadata is required",
+                ),
+            )
+        if stateless is None or version != stateless.protocol_version:
+            return self.unsupported(version)
+        if not isinstance(method, str) or headers.get(METHOD_HEADER) != method:
+            return _header_mismatch("Mcp-Method header does not match request method")
+        key = {"tools/call": "name", "prompts/get": "name", "resources/read": "uri"}.get(method)
+        if key is not None:
+            name = (params or {}).get(key)
+            header = headers.get(NAME_HEADER)
+            if not isinstance(name, str) or header is None or decode_routing_header(header) != name:
+                return _header_mismatch("Mcp-Name header does not match request parameters")
+        return stateless
+
+    def admit(  # noqa: PLR0911
+        self, headers: Mapping[str, str], parsed: object, session: Session
+    ) -> Admission:
+        """Whether to serve a POST of ``parsed`` (``Unparsable()`` for a
+        body that is not JSON)."""
+        if isinstance(parsed, Unparsable):
+            version = headers.get(VERSION_HEADER)
+            if version is not None and version not in self.registry.versions:
+                return self.unsupported(version)
+            selected = self.select(headers, None, session)
+            # Session and protocol-header errors take precedence over parse errors.
+            if isinstance(selected, Rejected) and (
+                selected.error is None or selected.error["code"] == HEADER_MISMATCH_ERROR_CODE
+            ):
+                return selected
+            return Rejected(200, _error(PARSE_ERROR_CODE, "Parse error"))
+        if isinstance(parsed, list):
+            return self._batch(headers, cast("list[object]", parsed), session)
+        record = _record(parsed) or {}
+        has_id = "id" in record
+        id = parse_request_id(record.get("id"))
+        is_rpc = record.get("jsonrpc") == "2.0"
+        is_request = (
+            is_rpc
+            and (not has_id or _is_id(record["id"]))
+            and isinstance(record.get("method"), str)
+        )
+        is_response = (
+            is_rpc
+            and has_id
+            and (_is_id(record["id"]) or record["id"] is None)
+            and (("result" in record) != ("error" in record))
+        )
+        selected = self.select(headers, parsed, session)
+        if isinstance(selected, Rejected):
+            return Rejected(selected.status, selected.error, id)
+        if not is_request and not is_response:
+            return Rejected(200, _error(INVALID_REQUEST_ERROR_CODE, "Invalid Request"), id)
+        method = record.get("method")
+        has_session = session != "absent"
+        if method == "initialize" and has_session:
+            message = "initialize must not include an MCP-Session-Id header"
+            return Rejected(400, _error(INVALID_REQUEST_ERROR_CODE, message), id)
+        stateless = selected is not None and selected.is_stateless
+        if method != "initialize" and not has_session and not stateless:
+            if not self._has_stateful:
+                return Rejected(400, None, id)
+            message = "MCP-Session-Id header is required; send initialize to start a session"
+            return Rejected(400, _error(INVALID_REQUEST_ERROR_CODE, message), id)
+        if is_request and stateless and method not in STATELESS_METHODS:
+            message = f"Method not found: {method}"
+            return Rejected(404, _error(METHOD_NOT_FOUND_ERROR_CODE, message), id)
+        return Accepted(acknowledge=not is_request or not has_id)
+
+    def _batch(
+        self, headers: Mapping[str, str], messages: Sequence[object], session: Session
+    ) -> Admission:
+        if not messages:
+            return Rejected(400, _error(INVALID_REQUEST_ERROR_CODE, "Invalid Request"))
+        selected = self.select(headers, messages, session)
+        if (
+            isinstance(selected, Rejected)
+            or any(has_request_protocol_version(m) for m in messages)
+            or any((_record(m) or {}).get("method") == "initialize" for m in messages)
+            or isinstance(session, str)
+            or not session.accepts_batches
+        ):
+            return Rejected(400)
+        expects_answer = any(
+            "method" in record and "id" in record
+            for record in (_record(m) for m in messages)
+            if record is not None
+        )
+        return Accepted(acknowledge=not expects_answer)

pyfect/ai/_mcp/http_status.py

@@ -0,0 +1,27 @@
+"""A request's failure that also sets its HTTP response's status (Effect's
+``failWithHttpStatus``); over stdio only the failure counts."""
+
+from __future__ import annotations
+
+from typing import Any, Never
+
+from pyfect._core import Effect, _WithFiber  # pyright: ignore[reportPrivateUsage]
+from pyfect._fiber import Fiber
+from pyfect.ai.mcp_schema import McpError
+from pyfect.effect import fail, succeed
+from pyfect.http._request_state import append_pre_response_handler_unsafe
+from pyfect.http.server_request import ServerRequest
+from pyfect.http.server_response import HttpServerResponse
+
+
+def fail_with_http_status(status: int, error: McpError) -> Effect[Never, McpError]:
+    def body(fiber: Fiber[Any, Any]) -> Effect[Never, McpError]:
+        def set_status(
+            _request: ServerRequest, response: HttpServerResponse
+        ) -> Effect[HttpServerResponse]:
+            return succeed(response.set_status(status))
+
+        append_pre_response_handler_unsafe(fiber._context, set_status)  # pyright: ignore[reportPrivateUsage]
+        return fail(error)
+
+    return _WithFiber(body)

pyfect/ai/_mcp/input_wire.py

@@ -0,0 +1,226 @@
+"""2026-07-28's wire forms of input requests and input responses (Effect's
+``mcpSchema/v2026_07_28``). They are narrower than the session revisions' own
+sampling, roots and elicitation messages: decoding with them also drops what
+this revision does not carry, such as a URL elicitation's ``elicitationId``."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+from pyfect import schema as S
+from pyfect._json_value import JsonValue
+from pyfect.ai.mcp_schema import (
+    AUDIO_CONTENT,
+    CONTENT_BLOCK,
+    IMAGE_CONTENT,
+    JSON_OBJECT,
+    PRIMITIVE_SCHEMA_DEFINITION,
+    TEXT_CONTENT,
+    TOOL,
+    JsonObject,
+    PrimitiveSchemaDefinition,
+    Role,
+)
+
+_META = {"_meta": JSON_OBJECT}
+
+# --- sampling ---------------------------------------------------------------------------
+
+
+class _ToolUse(TypedDict):
+    type: Literal["tool_use"]
+    id: str
+    name: str
+    input: JsonObject
+    _meta: NotRequired[JsonObject]
+
+
+class _ToolResult(TypedDict):
+    type: Literal["tool_result"]
+    toolUseId: str
+    content: list[Any]
+    structuredContent: NotRequired[JsonValue]
+    isError: NotRequired[bool]
+    _meta: NotRequired[JsonObject]
+
+
+_BLOCK: S.Codec[Any, Any] = S.Union(
+    TEXT_CONTENT,
+    IMAGE_CONTENT,
+    AUDIO_CONTENT,
+    S.Struct(_ToolUse, input=JSON_OBJECT, **_META),
+    S.Struct(
+        _ToolResult,
+        content=S.List(CONTENT_BLOCK),
+        structuredContent=S.Json,
+        **_META,
+    ),
+)
+_CONTENT = S.Union(_BLOCK, S.List(_BLOCK))
+
+
+class _SamplingMessage(TypedDict):
+    role: Role
+    content: Any
+    _meta: NotRequired[JsonObject]
+
+
+class _ModelHint(TypedDict, total=False):
+    name: str
+
+
+_PRIORITY = S.Finite.check(S.is_between(minimum=0, maximum=1))
+
+
+class _ModelPreferences(TypedDict, total=False):
+    hints: list[Any]
+    costPriority: float
+    speedPriority: float
+    intelligencePriority: float
+
+
+class _ToolChoice(TypedDict, total=False):
+    mode: Literal["auto", "required", "none"]
+
+
+class _CreateMessage(TypedDict):
+    messages: list[Any]
+    maxTokens: int
+    modelPreferences: NotRequired[Any]
+    systemPrompt: NotRequired[str]
+    includeContext: NotRequired[Literal["none", "thisServer", "allServers"]]
+    temperature: NotRequired[float]
+    stopSequences: NotRequired[list[str]]
+    metadata: NotRequired[JsonObject]
+    tools: NotRequired[list[Any]]
+    toolChoice: NotRequired[_ToolChoice]
+
+
+_CREATE_MESSAGE = S.Struct(
+    _CreateMessage,
+    messages=S.List(S.Struct(_SamplingMessage, content=_CONTENT, **_META)),
+    modelPreferences=S.Struct(
+        _ModelPreferences,
+        hints=S.List(S.StructWithRest(S.Struct(_ModelHint), S.Record(S.String, S.Json))),
+        costPriority=_PRIORITY,
+        speedPriority=_PRIORITY,
+        intelligencePriority=_PRIORITY,
+    ),
+    temperature=S.Finite,
+    metadata=JSON_OBJECT,
+    tools=S.List(TOOL),
+)
+
+# --- elicitation ------------------------------------------------------------------------
+
+_RequestedSchema = TypedDict(
+    "_RequestedSchema",
+    {
+        "$schema": NotRequired[str],
+        "type": Literal["object"],
+        "properties": dict[str, PrimitiveSchemaDefinition],
+        "required": NotRequired[list[str]],
+    },
+)
+
+
+class _ElicitForm(TypedDict):
+    mode: NotRequired[Literal["form"]]
+    message: str
+    requestedSchema: _RequestedSchema
+
+
+class _ElicitUrl(TypedDict):
+    mode: Literal["url"]
+    message: str
+    url: str
+
+
+_ELICIT_PARAMS = S.Union(
+    S.Struct(
+        _ElicitForm,
+        requestedSchema=S.Struct(
+            _RequestedSchema, properties=S.Record(S.String, PRIMITIVE_SCHEMA_DEFINITION)
+        ),
+    ),
+    S.Struct(_ElicitUrl),
+)
+
+# --- requests ---------------------------------------------------------------------------
+
+
+class _RootsParams(TypedDict, total=False):
+    _meta: JsonObject
+
+
+class _Roots(TypedDict):
+    method: Literal["roots/list"]
+    params: NotRequired[_RootsParams]
+
+
+class _Sampling(TypedDict):
+    method: Literal["sampling/createMessage"]
+    params: _CreateMessage
+
+
+class _Elicitation(TypedDict):
+    method: Literal["elicitation/create"]
+    params: Any
+
+
+INPUT_REQUESTS: S.Codec[dict[str, Any], Any] = S.Record(
+    S.String,
+    S.Union(
+        S.Struct(_Sampling, params=_CREATE_MESSAGE),
+        S.Struct(_Roots, params=S.Struct(_RootsParams, **_META)),
+        S.Struct(_Elicitation, params=_ELICIT_PARAMS),
+    ),
+)
+"""What ``InputRequired.input_requests`` may hold; what it decodes to goes out."""
+
+# --- responses --------------------------------------------------------------------------
+
+
+class _CreateMessageResult(TypedDict):
+    role: Role
+    content: Any
+    _meta: NotRequired[JsonObject]
+    model: str
+    stopReason: NotRequired[str]
+
+
+class _Root(TypedDict):
+    uri: str
+    name: NotRequired[str]
+    _meta: NotRequired[JsonObject]
+
+
+class _ListRootsResult(TypedDict):
+    roots: list[_Root]
+
+
+class _ElicitResult(TypedDict):
+    action: Literal["accept", "decline", "cancel"]
+    content: NotRequired[dict[str, str | float | bool | list[str]]]
+
+
+_INPUT_RESPONSE = S.Union(
+    S.Struct(_CreateMessageResult, content=_CONTENT, **_META),
+    S.Struct(_ListRootsResult, roots=S.List(S.Struct(_Root, **_META))),
+    S.Struct(
+        _ElicitResult,
+        content=S.Record(S.String, S.Union(S.String, S.Finite, S.Boolean, S.List(S.String))),
+    ),
+)
+
+
+class ContinuationParams(TypedDict, total=False):
+    """A retried request's answers to its ``InputRequired``."""
+
+    inputResponses: dict[str, Any]
+    requestState: str
+
+
+CONTINUATION_PARAMS = S.Struct(
+    ContinuationParams, inputResponses=S.Record(S.String, _INPUT_RESPONSE)
+)

pyfect/ai/_mcp/log_levels.py

@@ -0,0 +1,55 @@
+"""MCP log levels against Effect's (Effect's ``mcpLogLevels``): which
+notifications a client's threshold lets through, and the ``CurrentLogLevel``
+a handler runs at."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeIs, get_args
+
+from pyfect.ai.mcp_schema import LoggingLevel
+from pyfect.logger import LogLevel, Severity
+
+REQUEST_LOG_LEVEL_META = "io.modelcontextprotocol/logLevel"
+
+LEVELS: tuple[LoggingLevel, ...] = get_args(LoggingLevel.__value__)
+
+_EFFECT_LEVELS: Mapping[LoggingLevel, Severity] = {
+    "debug": LogLevel.DEBUG,
+    "info": LogLevel.INFO,
+    "notice": LogLevel.INFO,
+    "warning": LogLevel.WARN,
+    "error": LogLevel.ERROR,
+    "critical": LogLevel.FATAL,
+    "alert": LogLevel.FATAL,
+    "emergency": LogLevel.FATAL,
+}
+
+
+def is_logging_level(value: object) -> TypeIs[LoggingLevel]:
+    return value in _EFFECT_LEVELS
+
+
+def effect_level(level: LoggingLevel) -> Severity:
+    return _EFFECT_LEVELS[level]
+
+
+def at_least(level: LoggingLevel, minimum: LoggingLevel) -> bool:
+    """``level`` is ``minimum`` or above in MCP's order."""
+    return LEVELS.index(level) >= LEVELS.index(minimum)
+
+
+def request_log_level(metadata: Mapping[str, Any]) -> object:
+    """The level a 2026-07-28 request's ``_meta`` names (unchecked)."""
+    return metadata.get(REQUEST_LOG_LEVEL_META)
+
+
+def session_delivers(level: object, threshold: LoggingLevel | Severity) -> bool:
+    """Whether a session at ``threshold`` (an MCP level once the client set
+    one, else the server's Effect level) gets a log at ``level``; a log of an
+    unknown level is never one Effect sends."""
+    if not is_logging_level(level):
+        return True
+    if isinstance(threshold, str):
+        return at_least(level, threshold)
+    return effect_level(level) >= threshold

pyfect/ai/_mcp/param_headers.py

@@ -0,0 +1,63 @@
+"""2026-07-28's ``Mcp-Param-*`` headers: a tool parameter annotated with
+``x-mcp-header`` is mirrored in a header, which must match the argument
+before the tool runs."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import Any, cast
+
+from pyfect._js import trim
+from pyfect.ai._mcp.routing_header import decode_routing_header
+from pyfect.schema.getter._coerce import to_number
+
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def _header_matches(header: str | None, argument: object) -> bool:  # noqa: PLR0911
+    if argument is None:
+        return header is None
+    if header is None:
+        return False
+    decoded = decode_routing_header(header)
+    if decoded is None:
+        return False
+    if isinstance(argument, str):
+        return decoded == argument
+    if isinstance(argument, bool):
+        return decoded == ("true" if argument else "false")
+    if isinstance(argument, int | float):
+        safe = abs(argument) <= _MAX_SAFE_INTEGER and float(argument).is_integer()
+        if not safe or not trim(decoded):
+            return False
+        number = to_number(decoded)
+        return not math.isnan(number) and number == argument
+    return False
+
+
+def _object(value: object) -> Mapping[str, Any] | None:
+    return cast("Mapping[str, Any]", value) if isinstance(value, dict) else None
+
+
+def mismatch(input_schema: object, arguments: object, headers: Mapping[str, str]) -> str | None:
+    """Why ``headers`` do not mirror ``arguments``, if so. Only ``properties``
+    paths may mirror a header; composition, arrays and references do not."""
+    pending: list[tuple[object, object, str]] = [(input_schema, arguments, "")]
+    while pending:
+        schema, argument, path = pending.pop()
+        node = _object(schema)
+        if node is None:
+            continue
+        annotation = node.get("x-mcp-header")
+        if isinstance(annotation, str):
+            name = f"mcp-param-{annotation.lower()}"
+            if not _header_matches(headers.get(name), argument):
+                return f"{name} does not match argument '{path}'"
+        properties = _object(node.get("properties"))
+        if properties is None:
+            continue
+        values = _object(argument) or {}
+        for key, property in properties.items():
+            pending.append((property, values.get(key), key if not path else f"{path}.{key}"))
+    return None