modelcontextprotocol/python-sdk
Watch
1
0
Fork
You've already forked python-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

chore: add D212 lint rule to enforce Google-style docstrings (#1892)

Browse source
This commit is contained in:
Felix Weinberger 2026-01-16 16:10:52 +00:00 • committed by GitHub
commit d41d0c0128
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
29 changed files with 452 additions and 925 deletions
Download patch file Download diff file Expand all files Collapse all files

4
src/mcp/server/auth/__init__.py
View file

@ -1,3 +1 @@
"""
MCP OAuth server authorization components.
"""
"""MCP OAuth server authorization components."""

4
src/mcp/server/auth/handlers/__init__.py
View file

@ -1,3 +1 @@
"""
Request handlers for MCP authorization endpoints.
"""
"""Request handlers for MCP authorization endpoints."""

8
src/mcp/server/auth/handlers/revoke.py
View file

@ -15,9 +15,7 @@ from mcp.server.auth.provider import AccessToken, OAuthAuthorizationServerProvid
class RevocationRequest(BaseModel):
"""
# See https://datatracker.ietf.org/doc/html/rfc7009#section-2.1
"""
"""# See https://datatracker.ietf.org/doc/html/rfc7009#section-2.1"""
token: str
token_type_hint: Literal["access_token", "refresh_token"] | None = None
@ -36,9 +34,7 @@ class RevocationHandler:
client_authenticator: ClientAuthenticator
async def handle(self, request: Request) -> Response:
"""
Handler for the OAuth 2.0 Token Revocation endpoint.
"""
"""Handler for the OAuth 2.0 Token Revocation endpoint."""
try:
client = await self.client_authenticator.authenticate_request(request)
except AuthenticationError as e: # pragma: no cover

4
src/mcp/server/auth/handlers/token.py
View file

@ -55,9 +55,7 @@ class TokenRequest(
class TokenErrorResponse(BaseModel):
"""
See https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
"""
"""See https://datatracker.ietf.org/doc/html/rfc6749#section-5.2"""
error: TokenErrorCode
error_description: str | None = None

4
src/mcp/server/auth/middleware/__init__.py
View file

@ -1,3 +1 @@
"""
Middleware for MCP authorization.
"""
"""Middleware for MCP authorization."""

6
src/mcp/server/auth/middleware/auth_context.py
View file

@ -11,8 +11,7 @@ auth_context_var = contextvars.ContextVar[AuthenticatedUser | None]("auth_contex
def get_access_token() -> AccessToken | None:
"""
Get the access token from the current context.
"""Get the access token from the current context.
Returns:
The access token if an authenticated user is available, None otherwise.
@ -22,8 +21,7 @@ def get_access_token() -> AccessToken | None:
class AuthContextMiddleware:
"""
Middleware that extracts the authenticated user from the request
"""Middleware that extracts the authenticated user from the request
and sets it in a contextvar for easy access throughout the request lifecycle.
This middleware should be added after the AuthenticationMiddleware in the

10
src/mcp/server/auth/middleware/bearer_auth.py
View file

@ -20,9 +20,7 @@ class AuthenticatedUser(SimpleUser):
class BearerAuthBackend(AuthenticationBackend):
"""
Authentication backend that validates Bearer tokens using a TokenVerifier.
"""
"""Authentication backend that validates Bearer tokens using a TokenVerifier."""
def __init__(self, token_verifier: TokenVerifier):
self.token_verifier = token_verifier
@ -50,8 +48,7 @@ class BearerAuthBackend(AuthenticationBackend):
class RequireAuthMiddleware:
"""
Middleware that requires a valid Bearer token in the Authorization header.
"""Middleware that requires a valid Bearer token in the Authorization header.
This will validate the token with the auth provider and store the resulting
auth info in the request state.
@ -63,8 +60,7 @@ class RequireAuthMiddleware:
required_scopes: list[str],
resource_metadata_url: AnyHttpUrl | None = None,
):
"""
Initialize the middleware.
"""Initialize the middleware.
Args:
app: ASGI application

9
src/mcp/server/auth/middleware/client_auth.py
View file

@ -17,8 +17,7 @@ class AuthenticationError(Exception):
class ClientAuthenticator:
"""
ClientAuthenticator is a callable which validates requests from a client
"""ClientAuthenticator is a callable which validates requests from a client
application, used to verify /token calls.
If, during registration, the client requested to be issued a secret, the
authenticator asserts that /token calls must be authenticated with
@ -28,8 +27,7 @@ class ClientAuthenticator:
"""
def __init__(self, provider: OAuthAuthorizationServerProvider[Any, Any, Any]):
"""
Initialize the dependency.
"""Initialize the dependency.
Args:
provider: Provider to look up client information
@ -37,8 +35,7 @@ class ClientAuthenticator:
self.provider = provider
async def authenticate_request(self, request: Request) -> OAuthClientInformationFull:
"""
Authenticate a client from an HTTP request.
"""Authenticate a client from an HTTP request.
Extracts client credentials from the appropriate location based on the
client's registered authentication method and validates them.

27
src/mcp/server/auth/provider.py
View file

@ -105,8 +105,7 @@ AccessTokenT = TypeVar("AccessTokenT", bound=AccessToken)
class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, RefreshTokenT, AccessTokenT]):
async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
"""
Retrieves client information by client ID.
"""Retrieves client information by client ID.
Implementors MAY raise NotImplementedError if dynamic client registration is
disabled in ClientRegistrationOptions.
@ -119,8 +118,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
"""
async def register_client(self, client_info: OAuthClientInformationFull) -> None:
"""
Saves client information as part of registering it.
"""Saves client information as part of registering it.
Implementors MAY raise NotImplementedError if dynamic client registration is
disabled in ClientRegistrationOptions.
@ -133,8 +131,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
"""
async def authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str:
"""
Called as part of the /authorize endpoint, and returns a URL that the client
"""Called as part of the /authorize endpoint, and returns a URL that the client
will be redirected to.
Many MCP implementations will redirect to a third-party provider to perform
a second OAuth exchange with that provider. In this sort of setup, the client
@ -178,8 +175,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
async def load_authorization_code(
self, client: OAuthClientInformationFull, authorization_code: str
) -> AuthorizationCodeT | None:
"""
Loads an AuthorizationCode by its code.
"""Loads an AuthorizationCode by its code.
Args:
client: The client that requested the authorization code.
@ -193,8 +189,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
async def exchange_authorization_code(
self, client: OAuthClientInformationFull, authorization_code: AuthorizationCodeT
) -> OAuthToken:
"""
Exchanges an authorization code for an access token and refresh token.
"""Exchanges an authorization code for an access token and refresh token.
Args:
client: The client exchanging the authorization code.
@ -209,8 +204,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
...
async def load_refresh_token(self, client: OAuthClientInformationFull, refresh_token: str) -> RefreshTokenT | None:
"""
Loads a RefreshToken by its token string.
"""Loads a RefreshToken by its token string.
Args:
client: The client that is requesting to load the refresh token.
@ -227,8 +221,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
refresh_token: RefreshTokenT,
scopes: list[str],
) -> OAuthToken:
"""
Exchanges a refresh token for an access token and refresh token.
"""Exchanges a refresh token for an access token and refresh token.
Implementations SHOULD rotate both the access token and refresh token.
@ -246,8 +239,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
...
async def load_access_token(self, token: str) -> AccessTokenT | None:
"""
Loads an access token by its token.
"""Loads an access token by its token.
Args:
token: The access token to verify.
@ -260,8 +252,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
self,
token: AccessTokenT | RefreshTokenT,
) -> None:
"""
Revokes an access or refresh token.
"""Revokes an access or refresh token.
If the given token is invalid or already revoked, this method should do nothing.

9
src/mcp/server/auth/routes.py
View file

@ -22,8 +22,7 @@ from mcp.shared.auth import OAuthMetadata, ProtectedResourceMetadata
def validate_issuer_url(url: AnyHttpUrl):
"""
Validate that the issuer URL meets OAuth 2.0 requirements.
"""Validate that the issuer URL meets OAuth 2.0 requirements.
Args:
url: The issuer URL to validate
@ -188,8 +187,7 @@ def build_metadata(
def build_resource_metadata_url(resource_server_url: AnyHttpUrl) -> AnyHttpUrl:
"""
Build RFC 9728 compliant protected resource metadata URL.
"""Build RFC 9728 compliant protected resource metadata URL.
Inserts /.well-known/oauth-protected-resource between host and resource path
as specified in RFC 9728 §3.1.
@ -213,8 +211,7 @@ def create_protected_resource_routes(
resource_name: str | None = None,
resource_documentation: AnyHttpUrl | None = None,
) -> list[Route]:
"""
Create routes for OAuth 2.0 Protected Resource Metadata (RFC 9728).
"""Create routes for OAuth 2.0 Protected Resource Metadata (RFC 9728).
Args:
resource_url: The URL of this resource server

3
src/mcp/server/experimental/__init__.py
View file

@ -1,5 +1,4 @@
"""
Server-side experimental features.
"""Server-side experimental features.
WARNING: These APIs are experimental and may change without notice.

18
src/mcp/server/experimental/request_context.py
View file

@ -1,5 +1,4 @@
"""
Experimental request context features.
"""Experimental request context features.
This module provides the Experimental class which gives access to experimental
features within a request context, such as task-augmented request handling.
@ -32,8 +31,7 @@ from mcp.types import (
@dataclass
class Experimental:
"""
Experimental features context for task-augmented requests.
"""Experimental features context for task-augmented requests.
Provides helpers for validating task execution compatibility and
running tasks with automatic lifecycle management.
@ -64,8 +62,7 @@ class Experimental:
*,
raise_error: bool = True,
) -> ErrorData | None:
"""
Validate that the request is compatible with the tool's task execution mode.
"""Validate that the request is compatible with the tool's task execution mode.
Per MCP spec:
- "required": Clients MUST invoke as task. Server returns -32601 if not.
@ -110,8 +107,7 @@ class Experimental:
*,
raise_error: bool = True,
) -> ErrorData | None:
"""
Validate that the request is compatible with the given tool.
"""Validate that the request is compatible with the given tool.
Convenience wrapper around validate_task_mode that extracts the mode from a Tool.
@ -126,8 +122,7 @@ class Experimental:
return self.validate_task_mode(mode, raise_error=raise_error)
def can_use_tool(self, tool_task_mode: TaskExecutionMode | None) -> bool:
"""
Check if this client can use a tool with the given task mode.
"""Check if this client can use a tool with the given task mode.
Useful for filtering tool lists or providing warnings.
Returns False if tool requires "required" but client doesn't support tasks.
@ -150,8 +145,7 @@ class Experimental:
task_id: str | None = None,
model_immediate_response: str | None = None,
) -> CreateTaskResult:
"""
Create a task, spawn background work, and return CreateTaskResult immediately.
"""Create a task, spawn background work, and return CreateTaskResult immediately.
This is the recommended way to handle task-augmented tool calls. It:
1. Creates a task in the store

21
src/mcp/server/experimental/session_features.py
View file

@ -1,5 +1,4 @@
"""
Experimental server session features for server→client task operations.
"""Experimental server session features for server→client task operations.
This module provides the server-side equivalent of ExperimentalClientFeatures,
allowing the server to send task-augmented requests to the client and poll for results.
@ -25,8 +24,7 @@ ResultT = TypeVar("ResultT", bound=types.Result)
class ExperimentalServerSessionFeatures:
"""
Experimental server session features for server→client task operations.
"""Experimental server session features for server→client task operations.
This provides the server-side equivalent of ExperimentalClientFeatures,
allowing the server to send task-augmented requests to the client and
@ -42,8 +40,7 @@ class ExperimentalServerSessionFeatures:
self._session = session
async def get_task(self, task_id: str) -> types.GetTaskResult:
"""
Send tasks/get to the client to get task status.
"""Send tasks/get to the client to get task status.
Args:
task_id: The task identifier
@ -61,8 +58,7 @@ class ExperimentalServerSessionFeatures:
task_id: str,
result_type: type[ResultT],
) -> ResultT:
"""
Send tasks/result to the client to retrieve the final result.
"""Send tasks/result to the client to retrieve the final result.
Args:
task_id: The task identifier
@ -77,8 +73,7 @@ class ExperimentalServerSessionFeatures:
)
async def poll_task(self, task_id: str) -> AsyncIterator[types.GetTaskResult]:
"""
Poll a client task until it reaches terminal status.
"""Poll a client task until it reaches terminal status.
Yields GetTaskResult for each poll, allowing the caller to react to
status changes. Exits when task reaches a terminal status.
@ -101,8 +96,7 @@ class ExperimentalServerSessionFeatures:
*,
ttl: int = 60000,
) -> types.ElicitResult:
"""
Send a task-augmented elicitation to the client and poll until complete.
"""Send a task-augmented elicitation to the client and poll until complete.
The client will create a local task, process the elicitation asynchronously,
and return the result when ready. This method handles the full flow:
@ -160,8 +154,7 @@ class ExperimentalServerSessionFeatures:
tools: list[types.Tool] | None = None,
tool_choice: types.ToolChoice | None = None,
) -> types.CreateMessageResult:
"""
Send a task-augmented sampling request and poll until complete.
"""Send a task-augmented sampling request and poll until complete.
The client will create a local task, process the sampling request
asynchronously, and return the result when ready.

33
src/mcp/server/experimental/task_context.py
View file

@ -1,5 +1,4 @@
"""
ServerTaskContext - Server-integrated task context with elicitation and sampling.
"""ServerTaskContext - Server-integrated task context with elicitation and sampling.
This wraps the pure TaskContext and adds server-specific functionality:
- Elicitation (task.elicit())
@ -51,8 +50,7 @@ from mcp.types import (
class ServerTaskContext:
"""
Server-integrated task context with elicitation and sampling.
"""Server-integrated task context with elicitation and sampling.
This wraps a pure TaskContext and adds server-specific functionality:
- elicit() for sending elicitation requests to the client
@ -83,8 +81,7 @@ class ServerTaskContext:
queue: TaskMessageQueue,
handler: TaskResultHandler | None = None,
):
"""
Create a ServerTaskContext.
"""Create a ServerTaskContext.
Args:
task: The Task object
@ -123,8 +120,7 @@ class ServerTaskContext:
# Enhanced methods with notifications
async def update_status(self, message: str, *, notify: bool = True) -> None:
"""
Update the task's status message.
"""Update the task's status message.
Args:
message: The new status message
@ -135,8 +131,7 @@ class ServerTaskContext:
await self._send_notification()
async def complete(self, result: Result, *, notify: bool = True) -> None:
"""
Mark the task as completed with the given result.
"""Mark the task as completed with the given result.
Args:
result: The task result
@ -147,8 +142,7 @@ class ServerTaskContext:
await self._send_notification()
async def fail(self, error: str, *, notify: bool = True) -> None:
"""
Mark the task as failed with an error message.
"""Mark the task as failed with an error message.
Args:
error: The error message
@ -204,8 +198,7 @@ class ServerTaskContext:
message: str,
requested_schema: ElicitRequestedSchema,
) -> ElicitResult:
"""
Send an elicitation request via the task message queue.
"""Send an elicitation request via the task message queue.
This method:
1. Checks client capability
@ -270,8 +263,7 @@ class ServerTaskContext:
url: str,
elicitation_id: str,
) -> ElicitResult:
"""
Send a URL mode elicitation request via the task message queue.
"""Send a URL mode elicitation request via the task message queue.
This directs the user to an external URL for out-of-band interactions
like OAuth flows, credential collection, or payment processing.
@ -347,8 +339,7 @@ class ServerTaskContext:
tools: list[Tool] | None = None,
tool_choice: ToolChoice | None = None,
) -> CreateMessageResult:
"""
Send a sampling request via the task message queue.
"""Send a sampling request via the task message queue.
This method:
1. Checks client capability
@ -434,8 +425,7 @@ class ServerTaskContext:
*,
ttl: int = 60000,
) -> ElicitResult:
"""
Send a task-augmented elicitation via the queue, then poll client.
"""Send a task-augmented elicitation via the queue, then poll client.
This is for use inside a task-augmented tool call when you want the client
to handle the elicitation as its own task. The elicitation request is queued
@ -520,8 +510,7 @@ class ServerTaskContext:
tools: list[Tool] | None = None,
tool_choice: ToolChoice | None = None,
) -> CreateMessageResult:
"""
Send a task-augmented sampling request via the queue, then poll client.
"""Send a task-augmented sampling request via the queue, then poll client.
This is for use inside a task-augmented tool call when you want the client
to handle the sampling as its own task. The request is queued and delivered

24
src/mcp/server/experimental/task_result_handler.py
View file

@ -1,5 +1,4 @@
"""
TaskResultHandler - Integrated handler for tasks/result endpoint.
"""TaskResultHandler - Integrated handler for tasks/result endpoint.
This implements the dequeue-send-wait pattern from the MCP Tasks spec:
1. Dequeue all pending messages for the task
@ -36,8 +35,7 @@ logger = logging.getLogger(__name__)
class TaskResultHandler:
"""
Handler for tasks/result that implements the message queue pattern.
"""Handler for tasks/result that implements the message queue pattern.
This handler:
1. Dequeues pending messages (elicitations, notifications) for the task
@ -75,8 +73,7 @@ class TaskResultHandler:
session: ServerSession,
message: SessionMessage,
) -> None:
"""
Send a message via the session.
"""Send a message via the session.
This is a helper for delivering queued task messages.
"""
@ -88,8 +85,7 @@ class TaskResultHandler:
session: ServerSession,
request_id: RequestId,
) -> GetTaskPayloadResult:
"""
Handle a tasks/result request.
"""Handle a tasks/result request.
This implements the dequeue-send-wait loop:
1. Dequeue all pending messages
@ -144,8 +140,7 @@ class TaskResultHandler:
session: ServerSession,
request_id: RequestId,
) -> None:
"""
Dequeue and send all pending messages for a task.
"""Dequeue and send all pending messages for a task.
Each message is sent via the session's write stream with
relatedRequestId set so responses route back to this stream.
@ -172,8 +167,7 @@ class TaskResultHandler:
await self.send_message(session, session_message)
async def _wait_for_task_update(self, task_id: str) -> None:
"""
Wait for task to be updated (status change or new message).
"""Wait for task to be updated (status change or new message).
Races between store update and queue message - first one wins.
"""
@ -199,8 +193,7 @@ class TaskResultHandler:
tg.start_soon(wait_for_queue)
def route_response(self, request_id: RequestId, response: dict[str, Any]) -> bool:
"""
Route a response back to the waiting resolver.
"""Route a response back to the waiting resolver.
This is called when a response arrives for a queued request.
@ -218,8 +211,7 @@ class TaskResultHandler:
return False
def route_error(self, request_id: RequestId, error: ErrorData) -> bool:
"""
Route an error back to the waiting resolver.
"""Route an error back to the waiting resolver.
Args:
request_id: The request ID from the error response

15
src/mcp/server/experimental/task_support.py
View file

@ -1,5 +1,4 @@
"""
TaskSupport - Configuration for experimental task support.
"""TaskSupport - Configuration for experimental task support.
This module provides the TaskSupport class which encapsulates all the
infrastructure needed for task-augmented requests: store, queue, and handler.
@ -21,8 +20,7 @@ from mcp.shared.experimental.tasks.store import TaskStore
@dataclass
class TaskSupport:
"""
Configuration for experimental task support.
"""Configuration for experimental task support.
Encapsulates the task store, message queue, result handler, and task group
for spawning background work.
@ -65,8 +63,7 @@ class TaskSupport:
@asynccontextmanager
async def run(self) -> AsyncIterator[None]:
"""
Run the task support lifecycle.
"""Run the task support lifecycle.
This creates a task group for spawning background task work.
Called automatically by Server.run().
@ -84,8 +81,7 @@ class TaskSupport:
self._task_group = None
def configure_session(self, session: ServerSession) -> None:
"""
Configure a session for task support.
"""Configure a session for task support.
This registers the result handler as a response router so that
responses to queued requests (elicitation, sampling) are routed
@ -100,8 +96,7 @@ class TaskSupport:
@classmethod
def in_memory(cls) -> "TaskSupport":
"""
Create in-memory task support.
"""Create in-memory task support.
Suitable for development, testing, and single-process servers.
For distributed systems, provide custom store and queue implementations.

10
src/mcp/server/fastmcp/server.py
View file

@ -304,8 +304,7 @@ class FastMCP(Generic[LifespanResultT]):
]
def get_context(self) -> Context[ServerSession, LifespanResultT, Request]:
"""
Returns a Context object. Note that the context will only be valid
"""Returns a Context object. Note that the context will only be valid
during a request; outside a request, most methods will error.
"""
try:
@ -683,8 +682,7 @@ class FastMCP(Generic[LifespanResultT]):
name: str | None = None,
include_in_schema: bool = True,
):
"""
Decorator to register a custom HTTP route on the FastMCP server.
"""Decorator to register a custom HTTP route on the FastMCP server.
Allows adding arbitrary HTTP endpoints outside the standard MCP protocol,
which can be useful for OAuth callbacks, health checks, or admin APIs.
@ -1074,9 +1072,7 @@ class FastMCP(Generic[LifespanResultT]):
class StreamableHTTPASGIApp:
"""
ASGI application for Streamable HTTP server transport.
"""
"""ASGI application for Streamable HTTP server transport."""
def __init__(self, session_manager: StreamableHTTPSessionManager):
self.session_manager = session_manager

6
src/mcp/server/fastmcp/utilities/func_metadata.py
View file

@ -95,8 +95,7 @@ class FuncMetadata(BaseModel):
return fn(**arguments_parsed_dict)
def convert_result(self, result: Any) -> Any:
"""
Convert the result of a function call to the appropriate format for
"""Convert the result of a function call to the appropriate format for
the lowlevel server tool call handler:
- If output_model is None, return the unstructured content directly.
@ -499,8 +498,7 @@ def _create_dict_model(func_name: str, dict_annotation: Any) -> type[BaseModel]:
def _convert_to_content(
result: Any,
) -> Sequence[ContentBlock]:
"""
Convert a result to a sequence of content objects.
"""Convert a result to a sequence of content objects.
Note: This conversion logic comes from previous versions of FastMCP and is being
retained for purposes of backwards compatibility. It produces different unstructured

3
src/mcp/server/lowlevel/experimental.py
View file

@ -88,8 +88,7 @@ class ExperimentalHandlers:
store: TaskStore | None = None,
queue: TaskMessageQueue | None = None,
) -> TaskSupport:
"""
Enable experimental task support.
"""Enable experimental task support.
This sets up the task infrastructure and auto-registers default handlers
for tasks/get, tasks/result, tasks/list, and tasks/cancel.

3
src/mcp/server/lowlevel/func_inspection.py
View file

@ -7,8 +7,7 @@ R = TypeVar("R")
def create_call_wrapper(func: Callable[..., R], request_type: type[T]) -> Callable[[T], R]:
"""
Create a wrapper function that knows how to call func with the request object.
"""Create a wrapper function that knows how to call func with the request object.
Returns a wrapper function that takes the request and calls func appropriately.

Some files were not shown because too many files have changed in this diff Show more