chore: 添加虚拟环境到仓库

- 添加 backend_service/venv 虚拟环境
- 包含所有Python依赖包
- 注意：虚拟环境约393MB，包含12655个文件

backend_service/venv/lib/python3.13/site-packages/mcp/shared/_httpx_utils.py

@@ -0,0 +1,83 @@
+"""Utilities for creating standardized httpx AsyncClient instances."""
+
+from typing import Any, Protocol
+
+import httpx
+
+__all__ = ["create_mcp_http_client"]
+
+
+class McpHttpClientFactory(Protocol):  # pragma: no branch
+    def __call__(  # pragma: no branch
+        self,
+        headers: dict[str, str] | None = None,
+        timeout: httpx.Timeout | None = None,
+        auth: httpx.Auth | None = None,
+    ) -> httpx.AsyncClient: ...
+
+
+def create_mcp_http_client(
+    headers: dict[str, str] | None = None,
+    timeout: httpx.Timeout | None = None,
+    auth: httpx.Auth | None = None,
+) -> httpx.AsyncClient:
+    """Create a standardized httpx AsyncClient with MCP defaults.
+
+    This function provides common defaults used throughout the MCP codebase:
+    - follow_redirects=True (always enabled)
+    - Default timeout of 30 seconds if not specified
+
+    Args:
+        headers: Optional headers to include with all requests.
+        timeout: Request timeout as httpx.Timeout object.
+            Defaults to 30 seconds if not specified.
+        auth: Optional authentication handler.
+
+    Returns:
+        Configured httpx.AsyncClient instance with MCP defaults.
+
+    Note:
+        The returned AsyncClient must be used as a context manager to ensure
+        proper cleanup of connections.
+
+    Examples:
+        # Basic usage with MCP defaults
+        async with create_mcp_http_client() as client:
+            response = await client.get("https://api.example.com")
+
+        # With custom headers
+        headers = {"Authorization": "Bearer token"}
+        async with create_mcp_http_client(headers) as client:
+            response = await client.get("/endpoint")
+
+        # With both custom headers and timeout
+        timeout = httpx.Timeout(60.0, read=300.0)
+        async with create_mcp_http_client(headers, timeout) as client:
+            response = await client.get("/long-request")
+
+        # With authentication
+        from httpx import BasicAuth
+        auth = BasicAuth(username="user", password="pass")
+        async with create_mcp_http_client(headers, timeout, auth) as client:
+            response = await client.get("/protected-endpoint")
+    """
+    # Set MCP defaults
+    kwargs: dict[str, Any] = {
+        "follow_redirects": True,
+    }
+
+    # Handle timeout
+    if timeout is None:
+        kwargs["timeout"] = httpx.Timeout(30.0)
+    else:
+        kwargs["timeout"] = timeout
+
+    # Handle headers
+    if headers is not None:
+        kwargs["headers"] = headers
+
+    # Handle authentication
+    if auth is not None:  # pragma: no cover
+        kwargs["auth"] = auth
+
+    return httpx.AsyncClient(**kwargs)

backend_service/venv/lib/python3.13/site-packages/mcp/shared/auth.py

@@ -0,0 +1,157 @@
+from typing import Any, Literal
+
+from pydantic import AnyHttpUrl, AnyUrl, BaseModel, Field, field_validator
+
+
+class OAuthToken(BaseModel):
+    """
+    See https://datatracker.ietf.org/doc/html/rfc6749#section-5.1
+    """
+
+    access_token: str
+    token_type: Literal["Bearer"] = "Bearer"
+    expires_in: int | None = None
+    scope: str | None = None
+    refresh_token: str | None = None
+
+    @field_validator("token_type", mode="before")
+    @classmethod
+    def normalize_token_type(cls, v: str | None) -> str | None:
+        if isinstance(v, str):
+            # Bearer is title-cased in the spec, so we normalize it
+            # https://datatracker.ietf.org/doc/html/rfc6750#section-4
+            return v.title()
+        return v  # pragma: no cover
+
+
+class InvalidScopeError(Exception):
+    def __init__(self, message: str):
+        self.message = message
+
+
+class InvalidRedirectUriError(Exception):
+    def __init__(self, message: str):
+        self.message = message
+
+
+class OAuthClientMetadata(BaseModel):
+    """
+    RFC 7591 OAuth 2.0 Dynamic Client Registration metadata.
+    See https://datatracker.ietf.org/doc/html/rfc7591#section-2
+    for the full specification.
+    """
+
+    redirect_uris: list[AnyUrl] | None = Field(..., min_length=1)
+    # supported auth methods for the token endpoint
+    token_endpoint_auth_method: Literal["none", "client_secret_post", "private_key_jwt"] = "client_secret_post"
+    # supported grant_types of this implementation
+    grant_types: list[
+        Literal["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:jwt-bearer"] | str
+    ] = [
+        "authorization_code",
+        "refresh_token",
+    ]
+    # The MCP spec requires the "code" response type, but OAuth
+    # servers may also return additional types they support
+    response_types: list[str] = ["code"]
+    scope: str | None = None
+
+    # these fields are currently unused, but we support & store them for potential
+    # future use
+    client_name: str | None = None
+    client_uri: AnyHttpUrl | None = None
+    logo_uri: AnyHttpUrl | None = None
+    contacts: list[str] | None = None
+    tos_uri: AnyHttpUrl | None = None
+    policy_uri: AnyHttpUrl | None = None
+    jwks_uri: AnyHttpUrl | None = None
+    jwks: Any | None = None
+    software_id: str | None = None
+    software_version: str | None = None
+
+    def validate_scope(self, requested_scope: str | None) -> list[str] | None:
+        if requested_scope is None:
+            return None
+        requested_scopes = requested_scope.split(" ")
+        allowed_scopes = [] if self.scope is None else self.scope.split(" ")
+        for scope in requested_scopes:
+            if scope not in allowed_scopes:  # pragma: no branch
+                raise InvalidScopeError(f"Client was not registered with scope {scope}")
+        return requested_scopes  # pragma: no cover
+
+    def validate_redirect_uri(self, redirect_uri: AnyUrl | None) -> AnyUrl:
+        if redirect_uri is not None:
+            # Validate redirect_uri against client's registered redirect URIs
+            if self.redirect_uris is None or redirect_uri not in self.redirect_uris:
+                raise InvalidRedirectUriError(f"Redirect URI '{redirect_uri}' not registered for client")
+            return redirect_uri
+        elif self.redirect_uris is not None and len(self.redirect_uris) == 1:
+            return self.redirect_uris[0]
+        else:
+            raise InvalidRedirectUriError("redirect_uri must be specified when client has multiple registered URIs")
+
+
+class OAuthClientInformationFull(OAuthClientMetadata):
+    """
+    RFC 7591 OAuth 2.0 Dynamic Client Registration full response
+    (client information plus metadata).
+    """
+
+    client_id: str | None = None
+    client_secret: str | None = None
+    client_id_issued_at: int | None = None
+    client_secret_expires_at: int | None = None
+
+
+class OAuthMetadata(BaseModel):
+    """
+    RFC 8414 OAuth 2.0 Authorization Server Metadata.
+    See https://datatracker.ietf.org/doc/html/rfc8414#section-2
+    """
+
+    issuer: AnyHttpUrl
+    authorization_endpoint: AnyHttpUrl
+    token_endpoint: AnyHttpUrl
+    registration_endpoint: AnyHttpUrl | None = None
+    scopes_supported: list[str] | None = None
+    response_types_supported: list[str] = ["code"]
+    response_modes_supported: list[str] | None = None
+    grant_types_supported: list[str] | None = None
+    token_endpoint_auth_methods_supported: list[str] | None = None
+    token_endpoint_auth_signing_alg_values_supported: list[str] | None = None
+    service_documentation: AnyHttpUrl | None = None
+    ui_locales_supported: list[str] | None = None
+    op_policy_uri: AnyHttpUrl | None = None
+    op_tos_uri: AnyHttpUrl | None = None
+    revocation_endpoint: AnyHttpUrl | None = None
+    revocation_endpoint_auth_methods_supported: list[str] | None = None
+    revocation_endpoint_auth_signing_alg_values_supported: list[str] | None = None
+    introspection_endpoint: AnyHttpUrl | None = None
+    introspection_endpoint_auth_methods_supported: list[str] | None = None
+    introspection_endpoint_auth_signing_alg_values_supported: list[str] | None = None
+    code_challenge_methods_supported: list[str] | None = None
+    client_id_metadata_document_supported: bool | None = None
+
+
+class ProtectedResourceMetadata(BaseModel):
+    """
+    RFC 9728 OAuth 2.0 Protected Resource Metadata.
+    See https://datatracker.ietf.org/doc/html/rfc9728#section-2
+    """
+
+    resource: AnyHttpUrl
+    authorization_servers: list[AnyHttpUrl] = Field(..., min_length=1)
+    jwks_uri: AnyHttpUrl | None = None
+    scopes_supported: list[str] | None = None
+    bearer_methods_supported: list[str] | None = Field(default=["header"])  # MCP only supports header method
+    resource_signing_alg_values_supported: list[str] | None = None
+    resource_name: str | None = None
+    resource_documentation: AnyHttpUrl | None = None
+    resource_policy_uri: AnyHttpUrl | None = None
+    resource_tos_uri: AnyHttpUrl | None = None
+    # tls_client_certificate_bound_access_tokens default is False, but ommited here for clarity
+    tls_client_certificate_bound_access_tokens: bool | None = None
+    authorization_details_types_supported: list[str] | None = None
+    dpop_signing_alg_values_supported: list[str] | None = None
+    # dpop_bound_access_tokens_required default is False, but ommited here for clarity
+    dpop_bound_access_tokens_required: bool | None = None

backend_service/venv/lib/python3.13/site-packages/mcp/shared/auth_utils.py

@@ -0,0 +1,85 @@
+"""Utilities for OAuth 2.0 Resource Indicators (RFC 8707) and PKCE (RFC 7636)."""
+
+import time
+from urllib.parse import urlparse, urlsplit, urlunsplit
+
+from pydantic import AnyUrl, HttpUrl
+
+
+def resource_url_from_server_url(url: str | HttpUrl | AnyUrl) -> str:
+    """Convert server URL to canonical resource URL per RFC 8707.
+
+    RFC 8707 section 2 states that resource URIs "MUST NOT include a fragment component".
+    Returns absolute URI with lowercase scheme/host for canonical form.
+
+    Args:
+        url: Server URL to convert
+
+    Returns:
+        Canonical resource URL string
+    """
+    # Convert to string if needed
+    url_str = str(url)
+
+    # Parse the URL and remove fragment, create canonical form
+    parsed = urlsplit(url_str)
+    canonical = urlunsplit(parsed._replace(scheme=parsed.scheme.lower(), netloc=parsed.netloc.lower(), fragment=""))
+
+    return canonical
+
+
+def check_resource_allowed(requested_resource: str, configured_resource: str) -> bool:
+    """Check if a requested resource URL matches a configured resource URL.
+
+    A requested resource matches if it has the same scheme, domain, port,
+    and its path starts with the configured resource's path. This allows
+    hierarchical matching where a token for a parent resource can be used
+    for child resources.
+
+    Args:
+        requested_resource: The resource URL being requested
+        configured_resource: The resource URL that has been configured
+
+    Returns:
+        True if the requested resource matches the configured resource
+    """
+    # Parse both URLs
+    requested = urlparse(requested_resource)
+    configured = urlparse(configured_resource)
+
+    # Compare scheme, host, and port (origin)
+    if requested.scheme.lower() != configured.scheme.lower() or requested.netloc.lower() != configured.netloc.lower():
+        return False
+
+    # Handle cases like requested=/foo and configured=/foo/
+    requested_path = requested.path
+    configured_path = configured.path
+
+    # If requested path is shorter, it cannot be a child
+    if len(requested_path) < len(configured_path):
+        return False
+
+    # Check if the requested path starts with the configured path
+    # Ensure both paths end with / for proper comparison
+    # This ensures that paths like "/api123" don't incorrectly match "/api"
+    if not requested_path.endswith("/"):
+        requested_path += "/"
+    if not configured_path.endswith("/"):
+        configured_path += "/"
+
+    return requested_path.startswith(configured_path)
+
+
+def calculate_token_expiry(expires_in: int | str | None) -> float | None:
+    """Calculate token expiry timestamp from expires_in seconds.
+
+    Args:
+        expires_in: Seconds until token expiration (may be string from some servers)
+
+    Returns:
+        Unix timestamp when token expires, or None if no expiry specified
+    """
+    if expires_in is None:
+        return None  # pragma: no cover
+    # Defensive: handle servers that return expires_in as string
+    return time.time() + int(expires_in)

backend_service/venv/lib/python3.13/site-packages/mcp/shared/context.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from typing import Any, Generic
+
+from typing_extensions import TypeVar
+
+from mcp.shared.session import BaseSession
+from mcp.types import RequestId, RequestParams
+
+SessionT = TypeVar("SessionT", bound=BaseSession[Any, Any, Any, Any, Any])
+LifespanContextT = TypeVar("LifespanContextT")
+RequestT = TypeVar("RequestT", default=Any)
+
+
+@dataclass
+class RequestContext(Generic[SessionT, LifespanContextT, RequestT]):
+    request_id: RequestId
+    meta: RequestParams.Meta | None
+    session: SessionT
+    lifespan_context: LifespanContextT
+    request: RequestT | None = None

backend_service/venv/lib/python3.13/site-packages/mcp/shared/exceptions.py

@@ -0,0 +1,14 @@
+from mcp.types import ErrorData
+
+
+class McpError(Exception):
+    """
+    Exception type raised when an error arrives over an MCP connection.
+    """
+
+    error: ErrorData
+
+    def __init__(self, error: ErrorData):
+        """Initialize McpError."""
+        super().__init__(error.message)
+        self.error = error

backend_service/venv/lib/python3.13/site-packages/mcp/shared/memory.py

@@ -0,0 +1,98 @@
+"""
+In-memory transports
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from datetime import timedelta
+from typing import Any
+
+import anyio
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+
+import mcp.types as types
+from mcp.client.session import ClientSession, ElicitationFnT, ListRootsFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
+from mcp.server import Server
+from mcp.server.fastmcp import FastMCP
+from mcp.shared.message import SessionMessage
+
+MessageStream = tuple[MemoryObjectReceiveStream[SessionMessage | Exception], MemoryObjectSendStream[SessionMessage]]
+
+
+@asynccontextmanager
+async def create_client_server_memory_streams() -> AsyncGenerator[tuple[MessageStream, MessageStream], None]:
+    """
+    Creates a pair of bidirectional memory streams for client-server communication.
+
+    Returns:
+        A tuple of (client_streams, server_streams) where each is a tuple of
+        (read_stream, write_stream)
+    """
+    # Create streams for both directions
+    server_to_client_send, server_to_client_receive = anyio.create_memory_object_stream[SessionMessage | Exception](1)
+    client_to_server_send, client_to_server_receive = anyio.create_memory_object_stream[SessionMessage | Exception](1)
+
+    client_streams = (server_to_client_receive, client_to_server_send)
+    server_streams = (client_to_server_receive, server_to_client_send)
+
+    async with (
+        server_to_client_receive,
+        client_to_server_send,
+        client_to_server_receive,
+        server_to_client_send,
+    ):
+        yield client_streams, server_streams
+
+
+@asynccontextmanager
+async def create_connected_server_and_client_session(
+    server: Server[Any] | FastMCP,
+    read_timeout_seconds: timedelta | None = None,
+    sampling_callback: SamplingFnT | None = None,
+    list_roots_callback: ListRootsFnT | None = None,
+    logging_callback: LoggingFnT | None = None,
+    message_handler: MessageHandlerFnT | None = None,
+    client_info: types.Implementation | None = None,
+    raise_exceptions: bool = False,
+    elicitation_callback: ElicitationFnT | None = None,
+) -> AsyncGenerator[ClientSession, None]:
+    """Creates a ClientSession that is connected to a running MCP server."""
+
+    # TODO(Marcelo): we should have a proper `Client` that can use this "in-memory transport",
+    # and we should expose a method in the `FastMCP` so we don't access a private attribute.
+    if isinstance(server, FastMCP):  # pragma: no cover
+        server = server._mcp_server  # type: ignore[reportPrivateUsage]
+
+    async with create_client_server_memory_streams() as (client_streams, server_streams):
+        client_read, client_write = client_streams
+        server_read, server_write = server_streams
+
+        # Create a cancel scope for the server task
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(
+                lambda: server.run(
+                    server_read,
+                    server_write,
+                    server.create_initialization_options(),
+                    raise_exceptions=raise_exceptions,
+                )
+            )
+
+            try:
+                async with ClientSession(
+                    read_stream=client_read,
+                    write_stream=client_write,
+                    read_timeout_seconds=read_timeout_seconds,
+                    sampling_callback=sampling_callback,
+                    list_roots_callback=list_roots_callback,
+                    logging_callback=logging_callback,
+                    message_handler=message_handler,
+                    client_info=client_info,
+                    elicitation_callback=elicitation_callback,
+                ) as client_session:
+                    await client_session.initialize()
+                    yield client_session
+            finally:  # pragma: no cover
+                tg.cancel_scope.cancel()

backend_service/venv/lib/python3.13/site-packages/mcp/shared/message.py

@@ -0,0 +1,43 @@
+"""
+Message wrapper with metadata support.
+
+This module defines a wrapper type that combines JSONRPCMessage with metadata
+to support transport-specific features like resumability.
+"""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from mcp.types import JSONRPCMessage, RequestId
+
+ResumptionToken = str
+
+ResumptionTokenUpdateCallback = Callable[[ResumptionToken], Awaitable[None]]
+
+
+@dataclass
+class ClientMessageMetadata:
+    """Metadata specific to client messages."""
+
+    resumption_token: ResumptionToken | None = None
+    on_resumption_token_update: Callable[[ResumptionToken], Awaitable[None]] | None = None
+
+
+@dataclass
+class ServerMessageMetadata:
+    """Metadata specific to server messages."""
+
+    related_request_id: RequestId | None = None
+    # Request-specific context (e.g., headers, auth info)
+    request_context: object | None = None
+
+
+MessageMetadata = ClientMessageMetadata | ServerMessageMetadata | None
+
+
+@dataclass
+class SessionMessage:
+    """A message with specific metadata for transport-specific features."""
+
+    message: JSONRPCMessage
+    metadata: MessageMetadata = None

backend_service/venv/lib/python3.13/site-packages/mcp/shared/metadata_utils.py

@@ -0,0 +1,45 @@
+"""Utility functions for working with metadata in MCP types.
+
+These utilities are primarily intended for client-side usage to properly display
+human-readable names in user interfaces in a spec compliant way.
+"""
+
+from mcp.types import Implementation, Prompt, Resource, ResourceTemplate, Tool
+
+
+def get_display_name(obj: Tool | Resource | Prompt | ResourceTemplate | Implementation) -> str:
+    """
+    Get the display name for an MCP object with proper precedence.
+
+    This is a client-side utility function designed to help MCP clients display
+    human-readable names in their user interfaces. When servers provide a 'title'
+    field, it should be preferred over the programmatic 'name' field for display.
+
+    For tools: title > annotations.title > name
+    For other objects: title > name
+
+    Example:
+        # In a client displaying available tools
+        tools = await session.list_tools()
+        for tool in tools.tools:
+            display_name = get_display_name(tool)
+            print(f"Available tool: {display_name}")
+
+    Args:
+        obj: An MCP object with name and optional title fields
+
+    Returns:
+        The display name to use for UI presentation
+    """
+    if isinstance(obj, Tool):
+        # Tools have special precedence: title > annotations.title > name
+        if hasattr(obj, "title") and obj.title is not None:
+            return obj.title
+        if obj.annotations and hasattr(obj.annotations, "title") and obj.annotations.title is not None:
+            return obj.annotations.title
+        return obj.name
+    else:
+        # All other objects: title > name
+        if hasattr(obj, "title") and obj.title is not None:
+            return obj.title
+        return obj.name

backend_service/venv/lib/python3.13/site-packages/mcp/shared/progress.py

@@ -0,0 +1,58 @@
+from collections.abc import Generator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Generic
+
+from pydantic import BaseModel
+
+from mcp.shared.context import LifespanContextT, RequestContext
+from mcp.shared.session import (
+    BaseSession,
+    ReceiveNotificationT,
+    ReceiveRequestT,
+    SendNotificationT,
+    SendRequestT,
+    SendResultT,
+)
+from mcp.types import ProgressToken
+
+
+class Progress(BaseModel):
+    progress: float
+    total: float | None
+
+
+@dataclass
+class ProgressContext(Generic[SendRequestT, SendNotificationT, SendResultT, ReceiveRequestT, ReceiveNotificationT]):
+    session: BaseSession[SendRequestT, SendNotificationT, SendResultT, ReceiveRequestT, ReceiveNotificationT]
+    progress_token: ProgressToken
+    total: float | None
+    current: float = field(default=0.0, init=False)
+
+    async def progress(self, amount: float, message: str | None = None) -> None:
+        self.current += amount
+
+        await self.session.send_progress_notification(
+            self.progress_token, self.current, total=self.total, message=message
+        )
+
+
+@contextmanager
+def progress(
+    ctx: RequestContext[
+        BaseSession[SendRequestT, SendNotificationT, SendResultT, ReceiveRequestT, ReceiveNotificationT],
+        LifespanContextT,
+    ],
+    total: float | None = None,
+) -> Generator[
+    ProgressContext[SendRequestT, SendNotificationT, SendResultT, ReceiveRequestT, ReceiveNotificationT],
+    None,
+]:
+    if ctx.meta is None or ctx.meta.progressToken is None:  # pragma: no cover
+        raise ValueError("No progress token provided")
+
+    progress_ctx = ProgressContext(ctx.session, ctx.meta.progressToken, total)
+    try:
+        yield progress_ctx
+    finally:
+        pass

backend_service/venv/lib/python3.13/site-packages/mcp/shared/session.py

@@ -0,0 +1,478 @@
+import logging
+from collections.abc import Callable
+from contextlib import AsyncExitStack
+from datetime import timedelta
+from types import TracebackType
+from typing import Any, Generic, Protocol, TypeVar
+
+import anyio
+import httpx
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from pydantic import BaseModel
+from typing_extensions import Self
+
+from mcp.shared.exceptions import McpError
+from mcp.shared.message import MessageMetadata, ServerMessageMetadata, SessionMessage
+from mcp.types import (
+    CONNECTION_CLOSED,
+    INVALID_PARAMS,
+    CancelledNotification,
+    ClientNotification,
+    ClientRequest,
+    ClientResult,
+    ErrorData,
+    JSONRPCError,
+    JSONRPCMessage,
+    JSONRPCNotification,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    ProgressNotification,
+    RequestParams,
+    ServerNotification,
+    ServerRequest,
+    ServerResult,
+)
+
+SendRequestT = TypeVar("SendRequestT", ClientRequest, ServerRequest)
+SendResultT = TypeVar("SendResultT", ClientResult, ServerResult)
+SendNotificationT = TypeVar("SendNotificationT", ClientNotification, ServerNotification)
+ReceiveRequestT = TypeVar("ReceiveRequestT", ClientRequest, ServerRequest)
+ReceiveResultT = TypeVar("ReceiveResultT", bound=BaseModel)
+ReceiveNotificationT = TypeVar("ReceiveNotificationT", ClientNotification, ServerNotification)
+
+RequestId = str | int
+
+
+class ProgressFnT(Protocol):
+    """Protocol for progress notification callbacks."""
+
+    async def __call__(
+        self, progress: float, total: float | None, message: str | None
+    ) -> None: ...  # pragma: no branch
+
+
+class RequestResponder(Generic[ReceiveRequestT, SendResultT]):
+    """Handles responding to MCP requests and manages request lifecycle.
+
+    This class MUST be used as a context manager to ensure proper cleanup and
+    cancellation handling:
+
+    Example:
+        with request_responder as resp:
+            await resp.respond(result)
+
+    The context manager ensures:
+    1. Proper cancellation scope setup and cleanup
+    2. Request completion tracking
+    3. Cleanup of in-flight requests
+    """
+
+    def __init__(
+        self,
+        request_id: RequestId,
+        request_meta: RequestParams.Meta | None,
+        request: ReceiveRequestT,
+        session: """BaseSession[
+            SendRequestT,
+            SendNotificationT,
+            SendResultT,
+            ReceiveRequestT,
+            ReceiveNotificationT
+        ]""",
+        on_complete: Callable[["RequestResponder[ReceiveRequestT, SendResultT]"], Any],
+        message_metadata: MessageMetadata = None,
+    ) -> None:
+        self.request_id = request_id
+        self.request_meta = request_meta
+        self.request = request
+        self.message_metadata = message_metadata
+        self._session = session
+        self._completed = False
+        self._cancel_scope = anyio.CancelScope()
+        self._on_complete = on_complete
+        self._entered = False  # Track if we're in a context manager
+
+    def __enter__(self) -> "RequestResponder[ReceiveRequestT, SendResultT]":
+        """Enter the context manager, enabling request cancellation tracking."""
+        self._entered = True
+        self._cancel_scope = anyio.CancelScope()
+        self._cancel_scope.__enter__()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit the context manager, performing cleanup and notifying completion."""
+        try:
+            if self._completed:  # pragma: no branch
+                self._on_complete(self)
+        finally:
+            self._entered = False
+            if not self._cancel_scope:  # pragma: no cover
+                raise RuntimeError("No active cancel scope")
+            self._cancel_scope.__exit__(exc_type, exc_val, exc_tb)
+
+    async def respond(self, response: SendResultT | ErrorData) -> None:
+        """Send a response for this request.
+
+        Must be called within a context manager block.
+        Raises:
+            RuntimeError: If not used within a context manager
+            AssertionError: If request was already responded to
+        """
+        if not self._entered:  # pragma: no cover
+            raise RuntimeError("RequestResponder must be used as a context manager")
+        assert not self._completed, "Request already responded to"
+
+        if not self.cancelled:  # pragma: no branch
+            self._completed = True
+
+            await self._session._send_response(  # type: ignore[reportPrivateUsage]
+                request_id=self.request_id, response=response
+            )
+
+    async def cancel(self) -> None:
+        """Cancel this request and mark it as completed."""
+        if not self._entered:  # pragma: no cover
+            raise RuntimeError("RequestResponder must be used as a context manager")
+        if not self._cancel_scope:  # pragma: no cover
+            raise RuntimeError("No active cancel scope")
+
+        self._cancel_scope.cancel()
+        self._completed = True  # Mark as completed so it's removed from in_flight
+        # Send an error response to indicate cancellation
+        await self._session._send_response(  # type: ignore[reportPrivateUsage]
+            request_id=self.request_id,
+            response=ErrorData(code=0, message="Request cancelled", data=None),
+        )
+
+    @property
+    def in_flight(self) -> bool:  # pragma: no cover
+        return not self._completed and not self.cancelled
+
+    @property
+    def cancelled(self) -> bool:  # pragma: no cover
+        return self._cancel_scope.cancel_called
+
+
+class BaseSession(
+    Generic[
+        SendRequestT,
+        SendNotificationT,
+        SendResultT,
+        ReceiveRequestT,
+        ReceiveNotificationT,
+    ],
+):
+    """
+    Implements an MCP "session" on top of read/write streams, including features
+    like request/response linking, notifications, and progress.
+
+    This class is an async context manager that automatically starts processing
+    messages when entered.
+    """
+
+    _response_streams: dict[RequestId, MemoryObjectSendStream[JSONRPCResponse | JSONRPCError]]
+    _request_id: int
+    _in_flight: dict[RequestId, RequestResponder[ReceiveRequestT, SendResultT]]
+    _progress_callbacks: dict[RequestId, ProgressFnT]
+
+    def __init__(
+        self,
+        read_stream: MemoryObjectReceiveStream[SessionMessage | Exception],
+        write_stream: MemoryObjectSendStream[SessionMessage],
+        receive_request_type: type[ReceiveRequestT],
+        receive_notification_type: type[ReceiveNotificationT],
+        # If none, reading will never time out
+        read_timeout_seconds: timedelta | None = None,
+    ) -> None:
+        self._read_stream = read_stream
+        self._write_stream = write_stream
+        self._response_streams = {}
+        self._request_id = 0
+        self._receive_request_type = receive_request_type
+        self._receive_notification_type = receive_notification_type
+        self._session_read_timeout_seconds = read_timeout_seconds
+        self._in_flight = {}
+        self._progress_callbacks = {}
+        self._exit_stack = AsyncExitStack()
+
+    async def __aenter__(self) -> Self:
+        self._task_group = anyio.create_task_group()
+        await self._task_group.__aenter__()
+        self._task_group.start_soon(self._receive_loop)
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool | None:
+        await self._exit_stack.aclose()
+        # Using BaseSession as a context manager should not block on exit (this
+        # would be very surprising behavior), so make sure to cancel the tasks
+        # in the task group.
+        self._task_group.cancel_scope.cancel()
+        return await self._task_group.__aexit__(exc_type, exc_val, exc_tb)
+
+    async def send_request(
+        self,
+        request: SendRequestT,
+        result_type: type[ReceiveResultT],
+        request_read_timeout_seconds: timedelta | None = None,
+        metadata: MessageMetadata = None,
+        progress_callback: ProgressFnT | None = None,
+    ) -> ReceiveResultT:
+        """
+        Sends a request and wait for a response. Raises an McpError if the
+        response contains an error. If a request read timeout is provided, it
+        will take precedence over the session read timeout.
+
+        Do not use this method to emit notifications! Use send_notification()
+        instead.
+        """
+        request_id = self._request_id
+        self._request_id = request_id + 1
+
+        response_stream, response_stream_reader = anyio.create_memory_object_stream[JSONRPCResponse | JSONRPCError](1)
+        self._response_streams[request_id] = response_stream
+
+        # Set up progress token if progress callback is provided
+        request_data = request.model_dump(by_alias=True, mode="json", exclude_none=True)
+        if progress_callback is not None:  # pragma: no cover
+            # Use request_id as progress token
+            if "params" not in request_data:
+                request_data["params"] = {}
+            if "_meta" not in request_data["params"]:  # pragma: no branch
+                request_data["params"]["_meta"] = {}
+            request_data["params"]["_meta"]["progressToken"] = request_id
+            # Store the callback for this request
+            self._progress_callbacks[request_id] = progress_callback
+
+        try:
+            jsonrpc_request = JSONRPCRequest(
+                jsonrpc="2.0",
+                id=request_id,
+                **request_data,
+            )
+
+            await self._write_stream.send(SessionMessage(message=JSONRPCMessage(jsonrpc_request), metadata=metadata))
+
+            # request read timeout takes precedence over session read timeout
+            timeout = None
+            if request_read_timeout_seconds is not None:  # pragma: no cover
+                timeout = request_read_timeout_seconds.total_seconds()
+            elif self._session_read_timeout_seconds is not None:  # pragma: no cover
+                timeout = self._session_read_timeout_seconds.total_seconds()
+
+            try:
+                with anyio.fail_after(timeout):
+                    response_or_error = await response_stream_reader.receive()
+            except TimeoutError:
+                raise McpError(
+                    ErrorData(
+                        code=httpx.codes.REQUEST_TIMEOUT,
+                        message=(
+                            f"Timed out while waiting for response to "
+                            f"{request.__class__.__name__}. Waited "
+                            f"{timeout} seconds."
+                        ),
+                    )
+                )
+
+            if isinstance(response_or_error, JSONRPCError):
+                raise McpError(response_or_error.error)
+            else:
+                return result_type.model_validate(response_or_error.result)
+
+        finally:
+            self._response_streams.pop(request_id, None)
+            self._progress_callbacks.pop(request_id, None)
+            await response_stream.aclose()
+            await response_stream_reader.aclose()
+
+    async def send_notification(
+        self,
+        notification: SendNotificationT,
+        related_request_id: RequestId | None = None,
+    ) -> None:
+        """
+        Emits a notification, which is a one-way message that does not expect
+        a response.
+        """
+        # Some transport implementations may need to set the related_request_id
+        # to attribute to the notifications to the request that triggered them.
+        jsonrpc_notification = JSONRPCNotification(
+            jsonrpc="2.0",
+            **notification.model_dump(by_alias=True, mode="json", exclude_none=True),
+        )
+        session_message = SessionMessage(  # pragma: no cover
+            message=JSONRPCMessage(jsonrpc_notification),
+            metadata=ServerMessageMetadata(related_request_id=related_request_id) if related_request_id else None,
+        )
+        await self._write_stream.send(session_message)
+
+    async def _send_response(self, request_id: RequestId, response: SendResultT | ErrorData) -> None:
+        if isinstance(response, ErrorData):
+            jsonrpc_error = JSONRPCError(jsonrpc="2.0", id=request_id, error=response)
+            session_message = SessionMessage(message=JSONRPCMessage(jsonrpc_error))
+            await self._write_stream.send(session_message)
+        else:
+            jsonrpc_response = JSONRPCResponse(
+                jsonrpc="2.0",
+                id=request_id,
+                result=response.model_dump(by_alias=True, mode="json", exclude_none=True),
+            )
+            session_message = SessionMessage(message=JSONRPCMessage(jsonrpc_response))
+            await self._write_stream.send(session_message)
+
+    async def _receive_loop(self) -> None:
+        async with (
+            self._read_stream,
+            self._write_stream,
+        ):
+            try:
+                async for message in self._read_stream:
+                    if isinstance(message, Exception):  # pragma: no cover
+                        await self._handle_incoming(message)
+                    elif isinstance(message.message.root, JSONRPCRequest):
+                        try:
+                            validated_request = self._receive_request_type.model_validate(
+                                message.message.root.model_dump(by_alias=True, mode="json", exclude_none=True)
+                            )
+                            responder = RequestResponder(
+                                request_id=message.message.root.id,
+                                request_meta=validated_request.root.params.meta
+                                if validated_request.root.params
+                                else None,
+                                request=validated_request,
+                                session=self,
+                                on_complete=lambda r: self._in_flight.pop(r.request_id, None),
+                                message_metadata=message.metadata,
+                            )
+                            self._in_flight[responder.request_id] = responder
+                            await self._received_request(responder)
+
+                            if not responder._completed:  # type: ignore[reportPrivateUsage]
+                                await self._handle_incoming(responder)
+                        except Exception as e:
+                            # For request validation errors, send a proper JSON-RPC error
+                            # response instead of crashing the server
+                            logging.warning(f"Failed to validate request: {e}")
+                            logging.debug(f"Message that failed validation: {message.message.root}")
+                            error_response = JSONRPCError(
+                                jsonrpc="2.0",
+                                id=message.message.root.id,
+                                error=ErrorData(
+                                    code=INVALID_PARAMS,
+                                    message="Invalid request parameters",
+                                    data="",
+                                ),
+                            )
+                            session_message = SessionMessage(message=JSONRPCMessage(error_response))
+                            await self._write_stream.send(session_message)
+
+                    elif isinstance(message.message.root, JSONRPCNotification):
+                        try:
+                            notification = self._receive_notification_type.model_validate(
+                                message.message.root.model_dump(by_alias=True, mode="json", exclude_none=True)
+                            )
+                            # Handle cancellation notifications
+                            if isinstance(notification.root, CancelledNotification):
+                                cancelled_id = notification.root.params.requestId
+                                if cancelled_id in self._in_flight:  # pragma: no branch
+                                    await self._in_flight[cancelled_id].cancel()
+                            else:
+                                # Handle progress notifications callback
+                                if isinstance(notification.root, ProgressNotification):  # pragma: no cover
+                                    progress_token = notification.root.params.progressToken
+                                    # If there is a progress callback for this token,
+                                    # call it with the progress information
+                                    if progress_token in self._progress_callbacks:
+                                        callback = self._progress_callbacks[progress_token]
+                                        try:
+                                            await callback(
+                                                notification.root.params.progress,
+                                                notification.root.params.total,
+                                                notification.root.params.message,
+                                            )
+                                        except Exception as e:
+                                            logging.error(
+                                                "Progress callback raised an exception: %s",
+                                                e,
+                                            )
+                                await self._received_notification(notification)
+                                await self._handle_incoming(notification)
+                        except Exception as e:  # pragma: no cover
+                            # For other validation errors, log and continue
+                            logging.warning(
+                                f"Failed to validate notification: {e}. Message was: {message.message.root}"
+                            )
+                    else:  # Response or error
+                        stream = self._response_streams.pop(message.message.root.id, None)
+                        if stream:  # pragma: no cover
+                            await stream.send(message.message.root)
+                        else:  # pragma: no cover
+                            await self._handle_incoming(
+                                RuntimeError(f"Received response with an unknown request ID: {message}")
+                            )
+
+            except anyio.ClosedResourceError:
+                # This is expected when the client disconnects abruptly.
+                # Without this handler, the exception would propagate up and
+                # crash the server's task group.
+                logging.debug("Read stream closed by client")  # pragma: no cover
+            except Exception as e:  # pragma: no cover
+                # Other exceptions are not expected and should be logged. We purposefully
+                # catch all exceptions here to avoid crashing the server.
+                logging.exception(f"Unhandled exception in receive loop: {e}")
+            finally:
+                # after the read stream is closed, we need to send errors
+                # to any pending requests
+                for id, stream in self._response_streams.items():
+                    error = ErrorData(code=CONNECTION_CLOSED, message="Connection closed")
+                    try:
+                        await stream.send(JSONRPCError(jsonrpc="2.0", id=id, error=error))
+                        await stream.aclose()
+                    except Exception:  # pragma: no cover
+                        # Stream might already be closed
+                        pass
+                self._response_streams.clear()
+
+    async def _received_request(self, responder: RequestResponder[ReceiveRequestT, SendResultT]) -> None:
+        """
+        Can be overridden by subclasses to handle a request without needing to
+        listen on the message stream.
+
+        If the request is responded to within this method, it will not be
+        forwarded on to the message stream.
+        """
+
+    async def _received_notification(self, notification: ReceiveNotificationT) -> None:
+        """
+        Can be overridden by subclasses to handle a notification without needing
+        to listen on the message stream.
+        """
+
+    async def send_progress_notification(
+        self,
+        progress_token: str | int,
+        progress: float,
+        total: float | None = None,
+        message: str | None = None,
+    ) -> None:
+        """
+        Sends a progress notification for a request that is currently being
+        processed.
+        """
+
+    async def _handle_incoming(
+        self,
+        req: RequestResponder[ReceiveRequestT, SendResultT] | ReceiveNotificationT | Exception,
+    ) -> None:
+        """A generic handler for incoming messages. Overwritten by subclasses."""
+        pass  # pragma: no cover

backend_service/venv/lib/python3.13/site-packages/mcp/shared/version.py

@@ -0,0 +1,3 @@
+from mcp.types import LATEST_PROTOCOL_VERSION
+
+SUPPORTED_PROTOCOL_VERSIONS: list[str] = ["2024-11-05", "2025-03-26", LATEST_PROTOCOL_VERSION]