From 2450227153dca30bb9d5698b2fc384d7a15f3efc Mon Sep 17 00:00:00 2001 From: Marcelo Trylesinski Date: Fri, 23 Jan 2026 22:46:26 +0100 Subject: [PATCH] refactor: improve type docstrings and remove internal type exports Improve docstring formatting across MCP types for better consistency and readability. Remove internal TypeVars (MethodT, RequestParamsT, NotificationParamsT) and the Cursor alias from public exports as they are implementation details not intended for external use. Breaking changes documented in migration.md. --- docs/migration.md | 7 +++- src/mcp/client/session.py | 4 +-- src/mcp/types/__init__.py | 14 +++----- src/mcp/types/_types.py | 72 ++++++++++++++++++++++++--------------- 4 files changed, 56 insertions(+), 41 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index 3f92fe0bf..794700857 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -60,17 +60,22 @@ The following deprecated type aliases and classes have been removed from `mcp.ty |---------|-------------| | `Content` | `ContentBlock` | | `ResourceReference` | `ResourceTemplateReference` | +| `Cursor` | Use `str` directly | +| `MethodT` | Internal TypeVar, not intended for public use | +| `RequestParamsT` | Internal TypeVar, not intended for public use | +| `NotificationParamsT` | Internal TypeVar, not intended for public use | **Before (v1):** ```python -from mcp.types import Content, ResourceReference +from mcp.types import Content, ResourceReference, Cursor ``` **After (v2):** ```python from mcp.types import ContentBlock, ResourceTemplateReference +# Use `str` instead of `Cursor` for pagination cursors ``` ### `args` parameter removed from `ClientSessionGroup.call_tool()` diff --git a/src/mcp/client/session.py b/src/mcp/client/session.py index 7098132b0..5080e5385 100644 --- a/src/mcp/client/session.py +++ b/src/mcp/client/session.py @@ -365,9 +365,7 @@ async def get_prompt( ) -> types.GetPromptResult: """Send a prompts/get request.""" return await self.send_request( - types.GetPromptRequest( - params=types.GetPromptRequestParams(name=name, arguments=arguments, _meta=meta), - ), + types.GetPromptRequest(params=types.GetPromptRequestParams(name=name, arguments=arguments, _meta=meta)), types.GetPromptResult, ) diff --git a/src/mcp/types/__init__.py b/src/mcp/types/__init__.py index 00bf83992..666defaa2 100644 --- a/src/mcp/types/__init__.py +++ b/src/mcp/types/__init__.py @@ -1,4 +1,8 @@ -"""MCP types package.""" +"""This module defines the types for the MCP protocol. + +Check the latest schema at: +https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-11-25/schema.json +""" # Re-export everything from _types for backward compatibility from mcp.types._types import ( @@ -43,7 +47,6 @@ CreateMessageResult, CreateMessageResultWithTools, CreateTaskResult, - Cursor, ElicitationCapability, ElicitationRequiredErrorData, ElicitCompleteNotification, @@ -90,12 +93,10 @@ LoggingLevel, LoggingMessageNotification, LoggingMessageNotificationParams, - MethodT, ModelHint, ModelPreferences, Notification, NotificationParams, - NotificationParamsT, PaginatedRequest, PaginatedRequestParams, PaginatedResult, @@ -116,7 +117,6 @@ Request, RequestParams, RequestParamsMeta, - RequestParamsT, Resource, ResourceContents, ResourceLink, @@ -219,15 +219,11 @@ "TASK_STATUS_WORKING", # Type aliases and variables "ContentBlock", - "Cursor", "ElicitRequestedSchema", "ElicitRequestParams", "IncludeContext", "LoggingLevel", - "MethodT", - "NotificationParamsT", "ProgressToken", - "RequestParamsT", "Role", "SamplingContent", "SamplingMessageContentBlock", diff --git a/src/mcp/types/_types.py b/src/mcp/types/_types.py index a4f225f65..277277b9c 100644 --- a/src/mcp/types/_types.py +++ b/src/mcp/types/_types.py @@ -10,17 +10,22 @@ from mcp.types.jsonrpc import RequestId LATEST_PROTOCOL_VERSION = "2025-11-25" +"""The latest version of the Model Context Protocol. +You can find the latest specification at https://modelcontextprotocol.io/specification/latest. """ -The default negotiated version of the Model Context Protocol when no version is specified. -We need this to satisfy the MCP specification, which requires the server to assume a -specific version if none is provided by the client. See section "Protocol Version Header" at -https://modelcontextprotocol.io/specification -""" + DEFAULT_NEGOTIATED_VERSION = "2025-03-26" +"""The default negotiated version of the Model Context Protocol when no version is specified. + +We need this to satisfy the MCP specification, which requires the server to assume a specific version if none is +provided by the client. + +See the "Protocol Version Header" at +https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header). +""" ProgressToken = str | int -Cursor = str Role = Literal["user", "assistant"] TaskExecutionMode = Literal["forbidden", "optional", "required"] @@ -50,6 +55,7 @@ class RequestParamsMeta(TypedDict, extra_items=Any): class TaskMetadata(MCPModel): """Metadata for augmenting a request with task execution. + Include this in the `task` field of the request parameters. """ @@ -72,9 +78,9 @@ class RequestParams(MCPModel): class PaginatedRequestParams(RequestParams): - cursor: Cursor | None = None - """ - An opaque token representing the current pagination position. + cursor: str | None = None + """An opaque token representing the current pagination position. + If provided, the server should return results starting after this cursor. """ @@ -124,7 +130,7 @@ class Result(MCPModel): class PaginatedResult(Result): - next_cursor: Cursor | None = None + next_cursor: str | None = None """ An opaque token representing the pagination position after the last returned result. If present, there may be more results available. @@ -369,16 +375,22 @@ class ServerCapabilities(MCPModel): experimental: dict[str, dict[str, Any]] | None = None """Experimental, non-standard capabilities that the server supports.""" + logging: LoggingCapability | None = None """Present if the server supports sending log messages to the client.""" + prompts: PromptsCapability | None = None """Present if the server offers any prompt templates.""" + resources: ResourcesCapability | None = None """Present if the server offers any resources to read.""" + tools: ToolsCapability | None = None """Present if the server offers any tools to call.""" + completions: CompletionsCapability | None = None """Present if the server offers autocompletion suggestions for prompts and resources.""" + tasks: ServerTasksCapability | None = None """Present if the server supports task-augmented requests.""" @@ -413,8 +425,8 @@ class Task(MCPModel): """Current task state.""" status_message: str | None = None - """ - Optional human-readable message describing the current task state. + """Optional human-readable message describing the current task state. + This can provide context for any status, including: - Reasons for "cancelled" status - Summaries for "completed" status @@ -583,16 +595,14 @@ class ProgressNotificationParams(NotificationParams): total: float | None = None """Total number of items to process (or total progress required), if known.""" message: str | None = None - """ - Message related to progress. This should provide relevant human readable - progress information. + """Message related to progress. + + This should provide relevant human readable progress information. """ class ProgressNotification(Notification[ProgressNotificationParams, Literal["notifications/progress"]]): - """An out-of-band notification used to inform the receiver of a progress update for a - long-running request. - """ + """An out-of-band notification used to inform the receiver of a progress update for a long-running request.""" method: Literal["notifications/progress"] = "notifications/progress" params: ProgressNotificationParams @@ -614,20 +624,24 @@ class Resource(BaseMetadata): uri: str """The URI of this resource.""" + description: str | None = None """A description of what this resource represents.""" + mime_type: str | None = None """The MIME type of this resource, if known.""" + size: int | None = None - """ - The size of the raw resource content, in bytes (i.e., before base64 encoding - or any tokenization), if known. + """The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known. This can be used by Hosts to display file sizes and estimate context window usage. """ + icons: list[Icon] | None = None """An optional list of icons for this resource.""" + annotations: Annotations | None = None + meta: Meta | None = Field(alias="_meta", default=None) """ See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields) @@ -639,20 +653,22 @@ class ResourceTemplate(BaseMetadata): """A template description for resources available on the server.""" uri_template: str - """ - A URI template (according to RFC 6570) that can be used to construct resource - URIs. - """ + """A URI template (according to RFC 6570) that can be used to construct resource URIs.""" + description: str | None = None """A human-readable description of what this template is for.""" + mime_type: str | None = None + """The MIME type for all resources that match this template. + + This should only be included if all resources matching this template have the same type. """ - The MIME type for all resources that match this template. This should only be - included if all resources matching this template have the same type. - """ + icons: list[Icon] | None = None """An optional list of icons for this resource template.""" + annotations: Annotations | None = None + meta: Meta | None = Field(alias="_meta", default=None) """ See [MCP specification](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/47339c03c143bb4ec01a26e721a1b8fe66634ebe/docs/specification/draft/basic/index.mdx#general-fields)