refactor: improve type docstrings and remove internal type exports (#1950)
This commit is contained in:
Marcelo Trylesinski
GitHub
parent
a7ddfdae07
commit
ce75b2d7d2
4 changed files with 56 additions and 41 deletions
|
|
@ -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()`
|
||||
|
|
|
|||
|
|
@ -365,9 +365,7 @@ class ClientSession(
|
|||
) -> 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,
|
||||
)
|
||||
|
||||
|
|
|
|||
|
|
@ -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 @@ from mcp.types._types import (
|
|||
CreateMessageResult,
|
||||
CreateMessageResultWithTools,
|
||||
CreateTaskResult,
|
||||
Cursor,
|
||||
ElicitationCapability,
|
||||
ElicitationRequiredErrorData,
|
||||
ElicitCompleteNotification,
|
||||
|
|
@ -90,12 +93,10 @@ from mcp.types._types import (
|
|||
LoggingLevel,
|
||||
LoggingMessageNotification,
|
||||
LoggingMessageNotificationParams,
|
||||
MethodT,
|
||||
ModelHint,
|
||||
ModelPreferences,
|
||||
Notification,
|
||||
NotificationParams,
|
||||
NotificationParamsT,
|
||||
PaginatedRequest,
|
||||
PaginatedRequestParams,
|
||||
PaginatedResult,
|
||||
|
|
@ -116,7 +117,6 @@ from mcp.types._types import (
|
|||
Request,
|
||||
RequestParams,
|
||||
RequestParamsMeta,
|
||||
RequestParamsT,
|
||||
Resource,
|
||||
ResourceContents,
|
||||
ResourceLink,
|
||||
|
|
@ -219,15 +219,11 @@ __all__ = [
|
|||
"TASK_STATUS_WORKING",
|
||||
# Type aliases and variables
|
||||
"ContentBlock",
|
||||
"Cursor",
|
||||
"ElicitRequestedSchema",
|
||||
"ElicitRequestParams",
|
||||
"IncludeContext",
|
||||
"LoggingLevel",
|
||||
"MethodT",
|
||||
"NotificationParamsT",
|
||||
"ProgressToken",
|
||||
"RequestParamsT",
|
||||
"Role",
|
||||
"SamplingContent",
|
||||
"SamplingMessageContentBlock",
|
||||
|
|
|
|||
|
|
@ -10,17 +10,22 @@ from typing_extensions import NotRequired, TypedDict
|
|||
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)
|
||||
|
|
|
|||
Loading…
Reference in a new issue