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

refactor: replace lowlevel Server decorators with on_* constructor kwargs (#1985)

Browse source
This commit is contained in:
Max Isbey 2026-02-12 15:55:54 +00:00 • committed by GitHub
commit 0a22a9dc33
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
71 changed files with 3563 additions and 5481 deletions
Download patch file Download diff file Expand all files Collapse all files

314
README.v2.md
View file

@ -1642,12 +1642,11 @@ uv run examples/snippets/servers/lowlevel/lifespan.py
from collections.abc import AsyncIterator from collections.abc import AsyncIterator
from contextlib import asynccontextmanager from contextlib import asynccontextmanager
from typing import Any from typing import TypedDict
import mcp.server.stdio import mcp.server.stdio
from mcp import types from mcp import types
from mcp.server.lowlevel import NotificationOptions, Server from mcp.server import Server, ServerRequestContext
from mcp.server.models import InitializationOptions
# Mock database class for example # Mock database class for example
@ -1670,52 +1669,58 @@ class Database:
return [{"id": "1", "name": "Example", "query": query_str}] return [{"id": "1", "name": "Example", "query": query_str}]
class AppContext(TypedDict):
db: Database
@asynccontextmanager @asynccontextmanager
async def server_lifespan(_server: Server) -> AsyncIterator[dict[str, Any]]: async def server_lifespan(_server: Server[AppContext]) -> AsyncIterator[AppContext]:
"""Manage server startup and shutdown lifecycle.""" """Manage server startup and shutdown lifecycle."""
# Initialize resources on startup
db = await Database.connect() db = await Database.connect()
try: try:
yield {"db": db} yield {"db": db}
finally: finally:
# Clean up on shutdown
await db.disconnect() await db.disconnect()
# Pass lifespan to server async def handle_list_tools(
server = Server("example-server", lifespan=server_lifespan) ctx: ServerRequestContext[AppContext], params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
"""List available tools.""" """List available tools."""
return [ return types.ListToolsResult(
types.Tool( tools=[
name="query_db", types.Tool(
description="Query the database", name="query_db",
input_schema={ description="Query the database",
"type": "object", input_schema={
"properties": {"query": {"type": "string", "description": "SQL query to execute"}}, "type": "object",
"required": ["query"], "properties": {"query": {"type": "string", "description": "SQL query to execute"}},
}, "required": ["query"],
) },
] )
]
)
@server.call_tool() async def handle_call_tool(
async def query_db(name: str, arguments: dict[str, Any]) -> list[types.TextContent]: ctx: ServerRequestContext[AppContext], params: types.CallToolRequestParams
) -> types.CallToolResult:
"""Handle database query tool call.""" """Handle database query tool call."""
if name != "query_db": if params.name != "query_db":
raise ValueError(f"Unknown tool: {name}") raise ValueError(f"Unknown tool: {params.name}")
# Access lifespan context
ctx = server.request_context
db = ctx.lifespan_context["db"] db = ctx.lifespan_context["db"]
results = await db.query((params.arguments or {})["query"])
# Execute query return types.CallToolResult(content=[types.TextContent(type="text", text=f"Query results: {results}")])
results = await db.query(arguments["query"])
return [types.TextContent(type="text", text=f"Query results: {results}")]
server = Server(
"example-server",
lifespan=server_lifespan,
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
async def run(): async def run():
@ -1724,14 +1729,7 @@ async def run():
await server.run( await server.run(
read_stream, read_stream,
write_stream, write_stream,
InitializationOptions( server.create_initialization_options(),
server_name="example-server",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
) )
@ -1760,32 +1758,30 @@ import asyncio
import mcp.server.stdio import mcp.server.stdio
from mcp import types from mcp import types
from mcp.server.lowlevel import NotificationOptions, Server from mcp.server import Server, ServerRequestContext
from mcp.server.models import InitializationOptions
# Create a server instance
server = Server("example-server")
@server.list_prompts() async def handle_list_prompts(
async def handle_list_prompts() -> list[types.Prompt]: ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListPromptsResult:
"""List available prompts.""" """List available prompts."""
return [ return types.ListPromptsResult(
types.Prompt( prompts=[
name="example-prompt", types.Prompt(
description="An example prompt template", name="example-prompt",
arguments=[types.PromptArgument(name="arg1", description="Example argument", required=True)], description="An example prompt template",
) arguments=[types.PromptArgument(name="arg1", description="Example argument", required=True)],
] )
]
)
@server.get_prompt() async def handle_get_prompt(ctx: ServerRequestContext, params: types.GetPromptRequestParams) -> types.GetPromptResult:
async def handle_get_prompt(name: str, arguments: dict[str, str] | None) -> types.GetPromptResult:
"""Get a specific prompt by name.""" """Get a specific prompt by name."""
if name != "example-prompt": if params.name != "example-prompt":
raise ValueError(f"Unknown prompt: {name}") raise ValueError(f"Unknown prompt: {params.name}")
arg1_value = (arguments or {}).get("arg1", "default") arg1_value = (params.arguments or {}).get("arg1", "default")
return types.GetPromptResult( return types.GetPromptResult(
description="Example prompt", description="Example prompt",
@ -1798,20 +1794,20 @@ async def handle_get_prompt(name: str, arguments: dict[str, str] | None) -> type
) )
server = Server(
"example-server",
on_list_prompts=handle_list_prompts,
on_get_prompt=handle_get_prompt,
)
async def run(): async def run():
"""Run the basic low-level server.""" """Run the basic low-level server."""
async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
await server.run( await server.run(
read_stream, read_stream,
write_stream, write_stream,
InitializationOptions( server.create_initialization_options(),
server_name="example",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
) )
@ -1835,62 +1831,67 @@ uv run examples/snippets/servers/lowlevel/structured_output.py
""" """
import asyncio import asyncio
from typing import Any import json
import mcp.server.stdio import mcp.server.stdio
from mcp import types from mcp import types
from mcp.server.lowlevel import NotificationOptions, Server from mcp.server import Server, ServerRequestContext
from mcp.server.models import InitializationOptions
server = Server("example-server")
@server.list_tools() async def handle_list_tools(
async def list_tools() -> list[types.Tool]: ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
"""List available tools with structured output schemas.""" """List available tools with structured output schemas."""
return [ return types.ListToolsResult(
types.Tool( tools=[
name="get_weather", types.Tool(
description="Get current weather for a city", name="get_weather",
input_schema={ description="Get current weather for a city",
"type": "object", input_schema={
"properties": {"city": {"type": "string", "description": "City name"}}, "type": "object",
"required": ["city"], "properties": {"city": {"type": "string", "description": "City name"}},
}, "required": ["city"],
output_schema={
"type": "object",
"properties": {
"temperature": {"type": "number", "description": "Temperature in Celsius"},
"condition": {"type": "string", "description": "Weather condition"},
"humidity": {"type": "number", "description": "Humidity percentage"},
"city": {"type": "string", "description": "City name"},
}, },
"required": ["temperature", "condition", "humidity", "city"], output_schema={
}, "type": "object",
) "properties": {
] "temperature": {"type": "number", "description": "Temperature in Celsius"},
"condition": {"type": "string", "description": "Weather condition"},
"humidity": {"type": "number", "description": "Humidity percentage"},
"city": {"type": "string", "description": "City name"},
},
"required": ["temperature", "condition", "humidity", "city"],
},
)
]
)
@server.call_tool() async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
async def call_tool(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
"""Handle tool calls with structured output.""" """Handle tool calls with structured output."""
if name == "get_weather": if params.name == "get_weather":
city = arguments["city"] city = (params.arguments or {})["city"]
# Simulated weather data - in production, call a weather API
weather_data = { weather_data = {
"temperature": 22.5, "temperature": 22.5,
"condition": "partly cloudy", "condition": "partly cloudy",
"humidity": 65, "humidity": 65,
"city": city, # Include the requested city "city": city,
} }
# low-level server will validate structured output against the tool's return types.CallToolResult(
# output schema, and additionally serialize it into a TextContent block content=[types.TextContent(type="text", text=json.dumps(weather_data, indent=2))],
# for backwards compatibility with pre-2025-06-18 clients. structured_content=weather_data,
return weather_data )
else:
raise ValueError(f"Unknown tool: {name}") raise ValueError(f"Unknown tool: {params.name}")
server = Server(
"example-server",
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
async def run(): async def run():
@ -1899,14 +1900,7 @@ async def run():
await server.run( await server.run(
read_stream, read_stream,
write_stream, write_stream,
InitializationOptions( server.create_initialization_options(),
server_name="structured-output-example",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
) )
@ -1917,18 +1911,11 @@ if __name__ == "__main__":
_Full example: [examples/snippets/servers/lowlevel/structured_output.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/lowlevel/structured_output.py)_ _Full example: [examples/snippets/servers/lowlevel/structured_output.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/lowlevel/structured_output.py)_
<!-- /snippet-source --> <!-- /snippet-source -->
Tools can return data in four ways: With the low-level server, handlers always return `CallToolResult` directly. You construct both the human-readable `content` and the machine-readable `structured_content` yourself, giving you full control over the response.
1. **Content only**: Return a list of content blocks (default behavior before spec revision 2025-06-18) ##### Returning CallToolResult with `_meta`
2. **Structured data only**: Return a dictionary that will be serialized to JSON (Introduced in spec revision 2025-06-18)
3. **Both**: Return a tuple of (content, structured_data) preferred option to use for backwards compatibility
4. **Direct CallToolResult**: Return `CallToolResult` directly for full control (including `_meta` field)
When an `outputSchema` is defined, the server automatically validates the structured output against the schema. This ensures type safety and helps catch errors early. For passing data to client applications without exposing it to the model, use the `_meta` field on `CallToolResult`:
##### Returning CallToolResult Directly
For full control over the response including the `_meta` field (for passing data to client applications without exposing it to the model), return `CallToolResult` directly:
<!-- snippet-source examples/snippets/servers/lowlevel/direct_call_tool_result.py --> <!-- snippet-source examples/snippets/servers/lowlevel/direct_call_tool_result.py -->
```python ```python
@ -1937,44 +1924,49 @@ uv run examples/snippets/servers/lowlevel/direct_call_tool_result.py
""" """
import asyncio import asyncio
from typing import Any
import mcp.server.stdio import mcp.server.stdio
from mcp import types from mcp import types
from mcp.server.lowlevel import NotificationOptions, Server from mcp.server import Server, ServerRequestContext
from mcp.server.models import InitializationOptions
server = Server("example-server")
@server.list_tools() async def handle_list_tools(
async def list_tools() -> list[types.Tool]: ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
"""List available tools.""" """List available tools."""
return [ return types.ListToolsResult(
types.Tool( tools=[
name="advanced_tool", types.Tool(
description="Tool with full control including _meta field", name="advanced_tool",
input_schema={ description="Tool with full control including _meta field",
"type": "object", input_schema={
"properties": {"message": {"type": "string"}}, "type": "object",
"required": ["message"], "properties": {"message": {"type": "string"}},
}, "required": ["message"],
) },
] )
]
)
@server.call_tool() async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
async def handle_call_tool(name: str, arguments: dict[str, Any]) -> types.CallToolResult:
"""Handle tool calls by returning CallToolResult directly.""" """Handle tool calls by returning CallToolResult directly."""
if name == "advanced_tool": if params.name == "advanced_tool":
message = str(arguments.get("message", "")) message = (params.arguments or {}).get("message", "")
return types.CallToolResult( return types.CallToolResult(
content=[types.TextContent(type="text", text=f"Processed: {message}")], content=[types.TextContent(type="text", text=f"Processed: {message}")],
structured_content={"result": "success", "message": message}, structured_content={"result": "success", "message": message},
_meta={"hidden": "data for client applications only"}, _meta={"hidden": "data for client applications only"},
) )
raise ValueError(f"Unknown tool: {name}") raise ValueError(f"Unknown tool: {params.name}")
server = Server(
"example-server",
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
async def run(): async def run():
@ -1983,14 +1975,7 @@ async def run():
await server.run( await server.run(
read_stream, read_stream,
write_stream, write_stream,
InitializationOptions( server.create_initialization_options(),
server_name="example",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
) )
@ -2001,8 +1986,6 @@ if __name__ == "__main__":
_Full example: [examples/snippets/servers/lowlevel/direct_call_tool_result.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/lowlevel/direct_call_tool_result.py)_ _Full example: [examples/snippets/servers/lowlevel/direct_call_tool_result.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/lowlevel/direct_call_tool_result.py)_
<!-- /snippet-source --> <!-- /snippet-source -->
**Note:** When returning `CallToolResult`, you bypass the automatic content/structured conversion. You must construct the complete response yourself.
### Pagination (Advanced) ### Pagination (Advanced)
For servers that need to handle large datasets, the low-level server provides paginated versions of list operations. This is an optional optimization - most servers won't need pagination unless they're dealing with hundreds or thousands of items. For servers that need to handle large datasets, the low-level server provides paginated versions of list operations. This is an optional optimization - most servers won't need pagination unless they're dealing with hundreds or thousands of items.
@ -2011,25 +1994,23 @@ For servers that need to handle large datasets, the low-level server provides pa
<!-- snippet-source examples/snippets/servers/pagination_example.py --> <!-- snippet-source examples/snippets/servers/pagination_example.py -->
```python ```python
"""Example of implementing pagination with MCP server decorators.""" """Example of implementing pagination with the low-level MCP server."""
from mcp import types from mcp import types
from mcp.server.lowlevel import Server from mcp.server import Server, ServerRequestContext
# Initialize the server
server = Server("paginated-server")
# Sample data to paginate # Sample data to paginate
ITEMS = [f"Item {i}" for i in range(1, 101)] # 100 items ITEMS = [f"Item {i}" for i in range(1, 101)] # 100 items
@server.list_resources() async def handle_list_resources(
async def list_resources_paginated(request: types.ListResourcesRequest) -> types.ListResourcesResult: ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListResourcesResult:
"""List resources with pagination support.""" """List resources with pagination support."""
page_size = 10 page_size = 10
# Extract cursor from request params # Extract cursor from request params
cursor = request.params.cursor if request.params is not None else None cursor = params.cursor if params is not None else None
# Parse cursor to get offset # Parse cursor to get offset
start = 0 if cursor is None else int(cursor) start = 0 if cursor is None else int(cursor)
@ -2045,6 +2026,9 @@ async def list_resources_paginated(request: types.ListResourcesRequest) -> types
next_cursor = str(end) if end < len(ITEMS) else None next_cursor = str(end) if end < len(ITEMS) else None
return types.ListResourcesResult(resources=page_items, next_cursor=next_cursor) return types.ListResourcesResult(resources=page_items, next_cursor=next_cursor)
server = Server("paginated-server", on_list_resources=handle_list_resources)
``` ```
_Full example: [examples/snippets/servers/pagination_example.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/pagination_example.py)_ _Full example: [examples/snippets/servers/pagination_example.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/pagination_example.py)_

7
docs/experimental/index.md
View file

@ -27,10 +27,9 @@ Tasks are useful for:
Experimental features are accessed via the `.experimental` property: Experimental features are accessed via the `.experimental` property:
```python ```python
# Server-side # Server-side: enable task support (auto-registers default handlers)
@server.experimental.get_task() server = Server(name="my-server")
async def handle_get_task(request: GetTaskRequest) -> GetTaskResult: server.experimental.enable_tasks()
...
# Client-side # Client-side
result = await session.experimental.call_tool_as_task("tool_name", {"arg": "value"}) result = await session.experimental.call_tool_as_task("tool_name", {"arg": "value"})

302
docs/migration.md
View file

@ -351,7 +351,6 @@ The nested `RequestParams.Meta` Pydantic model class has been replaced with a to
- `RequestParams.Meta` (Pydantic model) → `RequestParamsMeta` (TypedDict) - `RequestParams.Meta` (Pydantic model) → `RequestParamsMeta` (TypedDict)
- Attribute access (`meta.progress_token`) → Dictionary access (`meta.get("progress_token")`) - Attribute access (`meta.progress_token`) → Dictionary access (`meta.get("progress_token")`)
- `progress_token` field changed from `ProgressToken | None = None` to `NotRequired[ProgressToken]` - `progress_token` field changed from `ProgressToken | None = None` to `NotRequired[ProgressToken]`
`
**In request context handlers:** **In request context handlers:**
@ -364,11 +363,12 @@ async def handle_tool(name: str, arguments: dict) -> list[TextContent]:
await ctx.session.send_progress_notification(ctx.meta.progress_token, 0.5, 100) await ctx.session.send_progress_notification(ctx.meta.progress_token, 0.5, 100)
# After (v2) # After (v2)
@server.call_tool() async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
async def handle_tool(name: str, arguments: dict) -> list[TextContent]:
ctx = server.request_context
if ctx.meta and "progress_token" in ctx.meta: if ctx.meta and "progress_token" in ctx.meta:
await ctx.session.send_progress_notification(ctx.meta["progress_token"], 0.5, 100) await ctx.session.send_progress_notification(ctx.meta["progress_token"], 0.5, 100)
...
server = Server("my-server", on_call_tool=handle_call_tool)
``` ```
### `RequestContext` and `ProgressContext` type parameters simplified ### `RequestContext` and `ProgressContext` type parameters simplified
@ -471,12 +471,292 @@ await client.read_resource("test://resource")
await client.read_resource(str(my_any_url)) await client.read_resource(str(my_any_url))
``` ```
### Lowlevel `Server`: constructor parameters are now keyword-only
All parameters after `name` are now keyword-only. If you were passing `version` or other parameters positionally, use keyword arguments instead:
```python
# Before (v1)
server = Server("my-server", "1.0")
# After (v2)
server = Server("my-server", version="1.0")
```
### Lowlevel `Server`: type parameter reduced from 2 to 1
The `Server` class previously had two type parameters: `Server[LifespanResultT, RequestT]`. The `RequestT` parameter has been removed — handlers now receive typed params directly rather than a generic request type.
```python
# Before (v1)
from typing import Any
from mcp.server.lowlevel.server import Server
server: Server[dict[str, Any], Any] = Server(...)
# After (v2)
from typing import Any
from mcp.server import Server
server: Server[dict[str, Any]] = Server(...)
```
### Lowlevel `Server`: `request_handlers` and `notification_handlers` attributes removed
The public `server.request_handlers` and `server.notification_handlers` dictionaries have been removed. Handler registration is now done exclusively through constructor `on_*` keyword arguments. There is no public API to register handlers after construction.
```python
# Before (v1) — direct dict access
from mcp.types import ListToolsRequest
if ListToolsRequest in server.request_handlers:
...
# After (v2) — no public access to handler dicts
# Use the on_* constructor params to register handlers
server = Server("my-server", on_list_tools=handle_list_tools)
```
### Lowlevel `Server`: decorator-based handlers replaced with constructor `on_*` params
The lowlevel `Server` class no longer uses decorator methods for handler registration. Instead, handlers are passed as `on_*` keyword arguments to the constructor.
**Before (v1):**
```python
from mcp.server.lowlevel.server import Server
server = Server("my-server")
@server.list_tools()
async def handle_list_tools():
return [types.Tool(name="my_tool", description="A tool", inputSchema={})]
@server.call_tool()
async def handle_call_tool(name: str, arguments: dict):
return [types.TextContent(type="text", text=f"Called {name}")]
```
**After (v2):**
```python
from mcp.server import Server, ServerRequestContext
from mcp.types import (
CallToolRequestParams,
CallToolResult,
ListToolsResult,
PaginatedRequestParams,
TextContent,
Tool,
)
async def handle_list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
return ListToolsResult(tools=[Tool(name="my_tool", description="A tool", input_schema={})])
async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
return CallToolResult(
content=[TextContent(type="text", text=f"Called {params.name}")],
is_error=False,
)
server = Server("my-server", on_list_tools=handle_list_tools, on_call_tool=handle_call_tool)
```
**Key differences:**
- Handlers receive `(ctx, params)` instead of the full request object or unpacked arguments. `ctx` is a `ServerRequestContext` with `session`, `lifespan_context`, and `experimental` fields (plus `request_id`, `meta`, etc. for request handlers). `params` is the typed request params object.
- Handlers return the full result type (e.g. `ListToolsResult`) rather than unwrapped values (e.g. `list[Tool]`).
- The automatic `jsonschema` input/output validation that the old `call_tool()` decorator performed has been removed. There is no built-in replacement — if you relied on schema validation in the lowlevel server, you will need to validate inputs yourself in your handler.
**Notification handlers:**
```python
from mcp.server import Server, ServerRequestContext
from mcp.types import ProgressNotificationParams
async def handle_progress(ctx: ServerRequestContext, params: ProgressNotificationParams) -> None:
print(f"Progress: {params.progress}/{params.total}")
server = Server("my-server", on_progress=handle_progress)
```
### Lowlevel `Server`: automatic return value wrapping removed
The old decorator-based handlers performed significant automatic wrapping of return values. This magic has been removed — handlers now return fully constructed result types. If you want these conveniences, use `MCPServer` (previously `FastMCP`) instead of the lowlevel `Server`.
**`call_tool()` — structured output wrapping removed:**
The old decorator accepted several return types and auto-wrapped them into `CallToolResult`:
```python
# Before (v1) — returning a dict auto-wrapped into structured_content + JSON TextContent
@server.call_tool()
async def handle(name: str, arguments: dict) -> dict:
return {"temperature": 22.5, "city": "London"}
# Before (v1) — returning a list auto-wrapped into CallToolResult.content
@server.call_tool()
async def handle(name: str, arguments: dict) -> list[TextContent]:
return [TextContent(type="text", text="Done")]
```
```python
# After (v2) — construct the full result yourself
import json
async def handle(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
data = {"temperature": 22.5, "city": "London"}
return CallToolResult(
content=[TextContent(type="text", text=json.dumps(data, indent=2))],
structured_content=data,
)
```
Note: `params.arguments` can be `None` (the old decorator defaulted it to `{}`). Use `params.arguments or {}` to preserve the old behavior.
**`read_resource()` — content type wrapping removed:**
The old decorator auto-wrapped `str` into `TextResourceContents` and `bytes` into `BlobResourceContents` (with base64 encoding), and applied a default mime type of `text/plain`:
```python
# Before (v1) — str/bytes auto-wrapped with mime type defaulting
@server.read_resource()
async def handle(uri: str) -> str:
return "file contents"
@server.read_resource()
async def handle(uri: str) -> bytes:
return b"\x89PNG..."
```
```python
# After (v2) — construct TextResourceContents or BlobResourceContents yourself
import base64
async def handle_read(ctx: ServerRequestContext, params: ReadResourceRequestParams) -> ReadResourceResult:
# Text content
return ReadResourceResult(
contents=[TextResourceContents(uri=str(params.uri), text="file contents", mime_type="text/plain")]
)
async def handle_read(ctx: ServerRequestContext, params: ReadResourceRequestParams) -> ReadResourceResult:
# Binary content — you must base64-encode it yourself
return ReadResourceResult(
contents=[BlobResourceContents(
uri=str(params.uri),
blob=base64.b64encode(b"\x89PNG...").decode("utf-8"),
mime_type="image/png",
)]
)
```
**`list_tools()`, `list_resources()`, `list_prompts()` — list wrapping removed:**
The old decorators accepted bare lists and wrapped them into the result type:
```python
# Before (v1)
@server.list_tools()
async def handle() -> list[Tool]:
return [Tool(name="my_tool", ...)]
# After (v2)
async def handle(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
return ListToolsResult(tools=[Tool(name="my_tool", ...)])
```
**Using `MCPServer` instead:**
If you prefer the convenience of automatic wrapping, use `MCPServer` which still provides these features through its `@mcp.tool()`, `@mcp.resource()`, and `@mcp.prompt()` decorators. The lowlevel `Server` is intentionally minimal — it provides no magic and gives you full control over the MCP protocol types.
### Lowlevel `Server`: `request_context` property removed
The `server.request_context` property has been removed. Request context is now passed directly to handlers as the first argument (`ctx`). The `request_ctx` module-level contextvar is now an internal implementation detail and should not be relied upon.
**Before (v1):**
```python
from mcp.server.lowlevel.server import request_ctx
@server.call_tool()
async def handle_call_tool(name: str, arguments: dict):
ctx = server.request_context # or request_ctx.get()
await ctx.session.send_log_message(level="info", data="Processing...")
return [types.TextContent(type="text", text="Done")]
```
**After (v2):**
```python
from mcp.server import ServerRequestContext
from mcp.types import CallToolRequestParams, CallToolResult, TextContent
async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
await ctx.session.send_log_message(level="info", data="Processing...")
return CallToolResult(
content=[TextContent(type="text", text="Done")],
is_error=False,
)
```
### `RequestContext`: request-specific fields are now optional
The `RequestContext` class now uses optional fields for request-specific data (`request_id`, `meta`, etc.) so it can be used for both request and notification handlers. In notification handlers, these fields are `None`.
```python
from mcp.server import ServerRequestContext
# request_id, meta, etc. are available in request handlers
# but None in notification handlers
```
### Experimental: task handler decorators removed
The experimental decorator methods on `ExperimentalHandlers` (`@server.experimental.list_tasks()`, `@server.experimental.get_task()`, etc.) have been removed.
Default task handlers are still registered automatically via `server.experimental.enable_tasks()`. Custom handlers can be passed as `on_*` kwargs to override specific defaults.
**Before (v1):**
```python
server = Server("my-server")
server.experimental.enable_tasks()
@server.experimental.get_task()
async def custom_get_task(request: GetTaskRequest) -> GetTaskResult:
...
```
**After (v2):**
```python
from mcp.server import Server, ServerRequestContext
from mcp.types import GetTaskRequestParams, GetTaskResult
async def custom_get_task(ctx: ServerRequestContext, params: GetTaskRequestParams) -> GetTaskResult:
...
server = Server("my-server")
server.experimental.enable_tasks(on_get_task=custom_get_task)
```
## Deprecations ## Deprecations
<!-- Add deprecations below --> <!-- Add deprecations below -->
## Bug Fixes ## Bug Fixes
### Lowlevel `Server`: `subscribe` capability now correctly reported
Previously, the lowlevel `Server` hardcoded `subscribe=False` in resource capabilities even when a `subscribe_resource()` handler was registered. The `subscribe` capability is now dynamically set to `True` when an `on_subscribe_resource` handler is provided. Clients that previously didn't see `subscribe: true` in capabilities will now see it when a handler is registered, which may change client behavior.
### Extra fields no longer allowed on top-level MCP types ### Extra fields no longer allowed on top-level MCP types
MCP protocol types no longer accept arbitrary extra fields at the top level. This matches the MCP specification which only allows extra fields within `_meta` objects, not on the types themselves. MCP protocol types no longer accept arbitrary extra fields at the top level. This matches the MCP specification which only allows extra fields within `_meta` objects, not on the types themselves.
@ -506,16 +786,16 @@ params = CallToolRequestParams(
The `streamable_http_app()` method is now available directly on the lowlevel `Server` class, not just `MCPServer`. This allows using the streamable HTTP transport without the MCPServer wrapper. The `streamable_http_app()` method is now available directly on the lowlevel `Server` class, not just `MCPServer`. This allows using the streamable HTTP transport without the MCPServer wrapper.
```python ```python
from mcp.server.lowlevel.server import Server from mcp.server import Server, ServerRequestContext
from mcp.types import ListToolsResult, PaginatedRequestParams
server = Server("my-server")
# Register handlers... async def handle_list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
@server.list_tools() return ListToolsResult(tools=[...])
async def list_tools():
return [...]
server = Server("my-server", on_list_tools=handle_list_tools)
# Create a Starlette app for streamable HTTP
app = server.streamable_http_app( app = server.streamable_http_app(
streamable_http_path="/mcp", streamable_http_path="/mcp",
json_response=False, json_response=False,

32
examples/servers/everything-server/mcp_everything_server/server.py
View file

@ -10,6 +10,7 @@ import json
import logging import logging
import click import click
from mcp.server import ServerRequestContext
from mcp.server.mcpserver import Context, MCPServer from mcp.server.mcpserver import Context, MCPServer
from mcp.server.mcpserver.prompts.base import UserMessage from mcp.server.mcpserver.prompts.base import UserMessage
from mcp.server.session import ServerSession from mcp.server.session import ServerSession
@ -20,13 +21,17 @@ from mcp.types import (
CompletionArgument, CompletionArgument,
CompletionContext, CompletionContext,
EmbeddedResource, EmbeddedResource,
EmptyResult,
ImageContent, ImageContent,
JSONRPCMessage, JSONRPCMessage,
PromptReference, PromptReference,
ResourceTemplateReference, ResourceTemplateReference,
SamplingMessage, SamplingMessage,
SetLevelRequestParams,
SubscribeRequestParams,
TextContent, TextContent,
TextResourceContents, TextResourceContents,
UnsubscribeRequestParams,
) )
from pydantic import BaseModel, Field from pydantic import BaseModel, Field
@ -393,28 +398,29 @@ def test_prompt_with_image() -> list[UserMessage]:
# Custom request handlers # Custom request handlers
# TODO(felix): Add public APIs to MCPServer for subscribe_resource, unsubscribe_resource, # TODO(felix): Add public APIs to MCPServer for subscribe_resource, unsubscribe_resource,
# and set_logging_level to avoid accessing protected _lowlevel_server attribute. # and set_logging_level to avoid accessing protected _lowlevel_server attribute.
@mcp._lowlevel_server.set_logging_level() # pyright: ignore[reportPrivateUsage] async def handle_set_logging_level(ctx: ServerRequestContext, params: SetLevelRequestParams) -> EmptyResult:
async def handle_set_logging_level(level: str) -> None:
"""Handle logging level changes""" """Handle logging level changes"""
logger.info(f"Log level set to: {level}") logger.info(f"Log level set to: {params.level}")
# In a real implementation, you would adjust the logging level here return EmptyResult()
# For conformance testing, we just acknowledge the request
async def handle_subscribe(uri: str) -> None: async def handle_subscribe(ctx: ServerRequestContext, params: SubscribeRequestParams) -> EmptyResult:
"""Handle resource subscription""" """Handle resource subscription"""
resource_subscriptions.add(str(uri)) resource_subscriptions.add(str(params.uri))
logger.info(f"Subscribed to resource: {uri}") logger.info(f"Subscribed to resource: {params.uri}")
return EmptyResult()
async def handle_unsubscribe(uri: str) -> None: async def handle_unsubscribe(ctx: ServerRequestContext, params: UnsubscribeRequestParams) -> EmptyResult:
"""Handle resource unsubscription""" """Handle resource unsubscription"""
resource_subscriptions.discard(str(uri)) resource_subscriptions.discard(str(params.uri))
logger.info(f"Unsubscribed from resource: {uri}") logger.info(f"Unsubscribed from resource: {params.uri}")
return EmptyResult()
mcp._lowlevel_server.subscribe_resource()(handle_subscribe) # pyright: ignore[reportPrivateUsage] mcp._lowlevel_server._add_request_handler("logging/setLevel", handle_set_logging_level) # pyright: ignore[reportPrivateUsage]
mcp._lowlevel_server.unsubscribe_resource()(handle_unsubscribe) # pyright: ignore[reportPrivateUsage] mcp._lowlevel_server._add_request_handler("resources/subscribe", handle_subscribe) # pyright: ignore[reportPrivateUsage]
mcp._lowlevel_server._add_request_handler("resources/unsubscribe", handle_unsubscribe) # pyright: ignore[reportPrivateUsage]
@mcp.completion() @mcp.completion()

251
examples/servers/simple-pagination/mcp_simple_pagination/server.py
View file

@ -1,17 +1,19 @@
"""Simple MCP server demonstrating pagination for tools, resources, and prompts. """Simple MCP server demonstrating pagination for tools, resources, and prompts.
This example shows how to use the paginated decorators to handle large lists This example shows how to implement pagination with the low-level server API
of items that need to be split across multiple pages. to handle large lists of items that need to be split across multiple pages.
""" """
from typing import Any from typing import TypeVar
import anyio import anyio
import click import click
from mcp import types from mcp import types
from mcp.server.lowlevel import Server from mcp.server import Server, ServerRequestContext
from starlette.requests import Request from starlette.requests import Request
T = TypeVar("T")
# Sample data - in real scenarios, this might come from a database # Sample data - in real scenarios, this might come from a database
SAMPLE_TOOLS = [ SAMPLE_TOOLS = [
types.Tool( types.Tool(
@ -44,6 +46,102 @@ SAMPLE_PROMPTS = [
] ]
def _paginate(cursor: str | None, items: list[T], page_size: int) -> tuple[list[T], str | None]:
"""Helper to paginate a list of items given a cursor."""
if cursor is not None:
try:
start_idx = int(cursor)
except (ValueError, TypeError):
return [], None
else:
start_idx = 0
page = items[start_idx : start_idx + page_size]
next_cursor = str(start_idx + page_size) if start_idx + page_size < len(items) else None
return page, next_cursor
# Paginated list_tools - returns 5 tools per page
async def handle_list_tools(
ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
cursor = params.cursor if params is not None else None
page, next_cursor = _paginate(cursor, SAMPLE_TOOLS, page_size=5)
return types.ListToolsResult(tools=page, next_cursor=next_cursor)
# Paginated list_resources - returns 10 resources per page
async def handle_list_resources(
ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListResourcesResult:
cursor = params.cursor if params is not None else None
page, next_cursor = _paginate(cursor, SAMPLE_RESOURCES, page_size=10)
return types.ListResourcesResult(resources=page, next_cursor=next_cursor)
# Paginated list_prompts - returns 7 prompts per page
async def handle_list_prompts(
ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListPromptsResult:
cursor = params.cursor if params is not None else None
page, next_cursor = _paginate(cursor, SAMPLE_PROMPTS, page_size=7)
return types.ListPromptsResult(prompts=page, next_cursor=next_cursor)
async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
# Find the tool in our sample data
tool = next((t for t in SAMPLE_TOOLS if t.name == params.name), None)
if not tool:
raise ValueError(f"Unknown tool: {params.name}")
return types.CallToolResult(
content=[
types.TextContent(
type="text",
text=f"Called tool '{params.name}' with arguments: {params.arguments}",
)
]
)
async def handle_read_resource(
ctx: ServerRequestContext, params: types.ReadResourceRequestParams
) -> types.ReadResourceResult:
resource = next((r for r in SAMPLE_RESOURCES if r.uri == str(params.uri)), None)
if not resource:
raise ValueError(f"Unknown resource: {params.uri}")
return types.ReadResourceResult(
contents=[
types.TextResourceContents(
uri=str(params.uri),
text=f"Content of {resource.name}: This is sample content for the resource.",
mime_type="text/plain",
)
]
)
async def handle_get_prompt(ctx: ServerRequestContext, params: types.GetPromptRequestParams) -> types.GetPromptResult:
prompt = next((p for p in SAMPLE_PROMPTS if p.name == params.name), None)
if not prompt:
raise ValueError(f"Unknown prompt: {params.name}")
message_text = f"This is the prompt '{params.name}'"
if params.arguments:
message_text += f" with arguments: {params.arguments}"
return types.GetPromptResult(
description=prompt.description,
messages=[
types.PromptMessage(
role="user",
content=types.TextContent(type="text", text=message_text),
)
],
)
@click.command() @click.command()
@click.option("--port", default=8000, help="Port to listen on for SSE") @click.option("--port", default=8000, help="Port to listen on for SSE")
@click.option( @click.option(
@ -53,142 +151,15 @@ SAMPLE_PROMPTS = [
help="Transport type", help="Transport type",
) )
def main(port: int, transport: str) -> int: def main(port: int, transport: str) -> int:
app = Server("mcp-simple-pagination") app = Server(
"mcp-simple-pagination",
# Paginated list_tools - returns 5 tools per page on_list_tools=handle_list_tools,
@app.list_tools() on_list_resources=handle_list_resources,
async def list_tools_paginated(request: types.ListToolsRequest) -> types.ListToolsResult: on_list_prompts=handle_list_prompts,
page_size = 5 on_call_tool=handle_call_tool,
on_read_resource=handle_read_resource,
cursor = request.params.cursor if request.params is not None else None on_get_prompt=handle_get_prompt,
if cursor is None: )
# First page
start_idx = 0
else:
# Parse cursor to get the start index
try:
start_idx = int(cursor)
except (ValueError, TypeError):
# Invalid cursor, return empty
return types.ListToolsResult(tools=[], next_cursor=None)
# Get the page of tools
page_tools = SAMPLE_TOOLS[start_idx : start_idx + page_size]
# Determine if there are more pages
next_cursor = None
if start_idx + page_size < len(SAMPLE_TOOLS):
next_cursor = str(start_idx + page_size)
return types.ListToolsResult(tools=page_tools, next_cursor=next_cursor)
# Paginated list_resources - returns 10 resources per page
@app.list_resources()
async def list_resources_paginated(
request: types.ListResourcesRequest,
) -> types.ListResourcesResult:
page_size = 10
cursor = request.params.cursor if request.params is not None else None
if cursor is None:
# First page
start_idx = 0
else:
# Parse cursor to get the start index
try:
start_idx = int(cursor)
except (ValueError, TypeError):
# Invalid cursor, return empty
return types.ListResourcesResult(resources=[], next_cursor=None)
# Get the page of resources
page_resources = SAMPLE_RESOURCES[start_idx : start_idx + page_size]
# Determine if there are more pages
next_cursor = None
if start_idx + page_size < len(SAMPLE_RESOURCES):
next_cursor = str(start_idx + page_size)
return types.ListResourcesResult(resources=page_resources, next_cursor=next_cursor)
# Paginated list_prompts - returns 7 prompts per page
@app.list_prompts()
async def list_prompts_paginated(
request: types.ListPromptsRequest,
) -> types.ListPromptsResult:
page_size = 7
cursor = request.params.cursor if request.params is not None else None
if cursor is None:
# First page
start_idx = 0
else:
# Parse cursor to get the start index
try:
start_idx = int(cursor)
except (ValueError, TypeError):
# Invalid cursor, return empty
return types.ListPromptsResult(prompts=[], next_cursor=None)
# Get the page of prompts
page_prompts = SAMPLE_PROMPTS[start_idx : start_idx + page_size]
# Determine if there are more pages
next_cursor = None
if start_idx + page_size < len(SAMPLE_PROMPTS):
next_cursor = str(start_idx + page_size)
return types.ListPromptsResult(prompts=page_prompts, next_cursor=next_cursor)
# Implement call_tool handler
@app.call_tool()
async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.ContentBlock]:
# Find the tool in our sample data
tool = next((t for t in SAMPLE_TOOLS if t.name == name), None)
if not tool:
raise ValueError(f"Unknown tool: {name}")
# Simple mock response
return [
types.TextContent(
type="text",
text=f"Called tool '{name}' with arguments: {arguments}",
)
]
# Implement read_resource handler
@app.read_resource()
async def read_resource(uri: str) -> str:
# Find the resource in our sample data
resource = next((r for r in SAMPLE_RESOURCES if r.uri == uri), None)
if not resource:
raise ValueError(f"Unknown resource: {uri}")
# Return a simple string - the decorator will convert it to TextResourceContents
return f"Content of {resource.name}: This is sample content for the resource."
# Implement get_prompt handler
@app.get_prompt()
async def get_prompt(name: str, arguments: dict[str, str] | None) -> types.GetPromptResult:
# Find the prompt in our sample data
prompt = next((p for p in SAMPLE_PROMPTS if p.name == name), None)
if not prompt:
raise ValueError(f"Unknown prompt: {name}")
# Simple mock response
message_text = f"This is the prompt '{name}'"
if arguments:
message_text += f" with arguments: {arguments}"
return types.GetPromptResult(
description=prompt.description,
messages=[
types.PromptMessage(
role="user",
content=types.TextContent(type="text", text=message_text),
)
],
)
if transport == "sse": if transport == "sse":
from mcp.server.sse import SseServerTransport from mcp.server.sse import SseServerTransport

57
examples/servers/simple-prompt/mcp_simple_prompt/server.py
View file

@ -1,7 +1,7 @@
import anyio import anyio
import click import click
from mcp import types from mcp import types
from mcp.server.lowlevel import Server from mcp.server import Server, ServerRequestContext
from starlette.requests import Request from starlette.requests import Request
@ -30,20 +30,11 @@ def create_messages(context: str | None = None, topic: str | None = None) -> lis
return messages return messages
@click.command() async def handle_list_prompts(
@click.option("--port", default=8000, help="Port to listen on for SSE") ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
@click.option( ) -> types.ListPromptsResult:
"--transport", return types.ListPromptsResult(
type=click.Choice(["stdio", "sse"]), prompts=[
default="stdio",
help="Transport type",
)
def main(port: int, transport: str) -> int:
app = Server("mcp-simple-prompt")
@app.list_prompts()
async def list_prompts() -> list[types.Prompt]:
return [
types.Prompt( types.Prompt(
name="simple", name="simple",
title="Simple Assistant Prompt", title="Simple Assistant Prompt",
@ -62,19 +53,35 @@ def main(port: int, transport: str) -> int:
], ],
) )
] ]
)
@app.get_prompt()
async def get_prompt(name: str, arguments: dict[str, str] | None = None) -> types.GetPromptResult:
if name != "simple":
raise ValueError(f"Unknown prompt: {name}")
if arguments is None: async def handle_get_prompt(ctx: ServerRequestContext, params: types.GetPromptRequestParams) -> types.GetPromptResult:
arguments = {} if params.name != "simple":
raise ValueError(f"Unknown prompt: {params.name}")
return types.GetPromptResult( arguments = params.arguments or {}
messages=create_messages(context=arguments.get("context"), topic=arguments.get("topic")),
description="A simple prompt with optional context and topic arguments", return types.GetPromptResult(
) messages=create_messages(context=arguments.get("context"), topic=arguments.get("topic")),
description="A simple prompt with optional context and topic arguments",
)
@click.command()
@click.option("--port", default=8000, help="Port to listen on for SSE")
@click.option(
"--transport",
type=click.Choice(["stdio", "sse"]),
default="stdio",
help="Transport type",
)
def main(port: int, transport: str) -> int:
app = Server(
"mcp-simple-prompt",
on_list_prompts=handle_list_prompts,
on_get_prompt=handle_get_prompt,
)
if transport == "sse": if transport == "sse":
from mcp.server.sse import SseServerTransport from mcp.server.sse import SseServerTransport

69
examples/servers/simple-resource/mcp_simple_resource/server.py
View file

@ -1,8 +1,9 @@
from urllib.parse import urlparse
import anyio import anyio
import click import click
from mcp import types from mcp import types
from mcp.server.lowlevel import Server from mcp.server import Server, ServerRequestContext
from mcp.server.lowlevel.helper_types import ReadResourceContents
from starlette.requests import Request from starlette.requests import Request
SAMPLE_RESOURCES = { SAMPLE_RESOURCES = {
@ -21,20 +22,11 @@ SAMPLE_RESOURCES = {
} }
@click.command() async def handle_list_resources(
@click.option("--port", default=8000, help="Port to listen on for SSE") ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
@click.option( ) -> types.ListResourcesResult:
"--transport", return types.ListResourcesResult(
type=click.Choice(["stdio", "sse"]), resources=[
default="stdio",
help="Transport type",
)
def main(port: int, transport: str) -> int:
app = Server("mcp-simple-resource")
@app.list_resources()
async def list_resources() -> list[types.Resource]:
return [
types.Resource( types.Resource(
uri=f"file:///{name}.txt", uri=f"file:///{name}.txt",
name=name, name=name,
@ -44,20 +36,45 @@ def main(port: int, transport: str) -> int:
) )
for name in SAMPLE_RESOURCES.keys() for name in SAMPLE_RESOURCES.keys()
] ]
)
@app.read_resource()
async def read_resource(uri: str):
from urllib.parse import urlparse
parsed = urlparse(uri) async def handle_read_resource(
if not parsed.path: ctx: ServerRequestContext, params: types.ReadResourceRequestParams
raise ValueError(f"Invalid resource path: {uri}") ) -> types.ReadResourceResult:
name = parsed.path.replace(".txt", "").lstrip("/") parsed = urlparse(str(params.uri))
if not parsed.path:
raise ValueError(f"Invalid resource path: {params.uri}")
name = parsed.path.replace(".txt", "").lstrip("/")
if name not in SAMPLE_RESOURCES: if name not in SAMPLE_RESOURCES:
raise ValueError(f"Unknown resource: {uri}") raise ValueError(f"Unknown resource: {params.uri}")
return [ReadResourceContents(content=SAMPLE_RESOURCES[name]["content"], mime_type="text/plain")] return types.ReadResourceResult(
contents=[
types.TextResourceContents(
uri=str(params.uri),
text=SAMPLE_RESOURCES[name]["content"],
mime_type="text/plain",
)
]
)
@click.command()
@click.option("--port", default=8000, help="Port to listen on for SSE")
@click.option(
"--transport",
type=click.Choice(["stdio", "sse"]),
default="stdio",
help="Transport type",
)
def main(port: int, transport: str) -> int:
app = Server(
"mcp-simple-resource",
on_list_resources=handle_list_resources,
on_read_resource=handle_read_resource,
)
if transport == "sse": if transport == "sse":
from mcp.server.sse import SseServerTransport from mcp.server.sse import SseServerTransport

119
examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/server.py
View file

@ -1,13 +1,12 @@
import contextlib import contextlib
import logging import logging
from collections.abc import AsyncIterator from collections.abc import AsyncIterator
from typing import Any
import anyio import anyio
import click import click
import uvicorn import uvicorn
from mcp import types from mcp import types
from mcp.server.lowlevel import Server from mcp.server import Server, ServerRequestContext
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
from starlette.applications import Starlette from starlette.applications import Starlette
from starlette.middleware.cors import CORSMiddleware from starlette.middleware.cors import CORSMiddleware
@ -17,6 +16,64 @@ from starlette.types import Receive, Scope, Send
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
async def handle_list_tools(
ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
return types.ListToolsResult(
tools=[
types.Tool(
name="start-notification-stream",
description=("Sends a stream of notifications with configurable count and interval"),
input_schema={
"type": "object",
"required": ["interval", "count", "caller"],
"properties": {
"interval": {
"type": "number",
"description": "Interval between notifications in seconds",
},
"count": {
"type": "number",
"description": "Number of notifications to send",
},
"caller": {
"type": "string",
"description": ("Identifier of the caller to include in notifications"),
},
},
},
)
]
)
async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
arguments = params.arguments or {}
interval = arguments.get("interval", 1.0)
count = arguments.get("count", 5)
caller = arguments.get("caller", "unknown")
# Send the specified number of notifications with the given interval
for i in range(count):
await ctx.session.send_log_message(
level="info",
data=f"Notification {i + 1}/{count} from caller: {caller}",
logger="notification_stream",
related_request_id=ctx.request_id,
)
if i < count - 1: # Don't wait after the last notification
await anyio.sleep(interval)
return types.CallToolResult(
content=[
types.TextContent(
type="text",
text=(f"Sent {count} notifications with {interval}s interval for caller: {caller}"),
)
]
)
@click.command() @click.command()
@click.option("--port", default=3000, help="Port to listen on for HTTP") @click.option("--port", default=3000, help="Port to listen on for HTTP")
@click.option( @click.option(
@ -41,59 +98,11 @@ def main(
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
) )
app = Server("mcp-streamable-http-stateless-demo") app = Server(
"mcp-streamable-http-stateless-demo",
@app.call_tool() on_list_tools=handle_list_tools,
async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.ContentBlock]: on_call_tool=handle_call_tool,
ctx = app.request_context )
interval = arguments.get("interval", 1.0)
count = arguments.get("count", 5)
caller = arguments.get("caller", "unknown")
# Send the specified number of notifications with the given interval
for i in range(count):
await ctx.session.send_log_message(
level="info",
data=f"Notification {i + 1}/{count} from caller: {caller}",
logger="notification_stream",
related_request_id=ctx.request_id,
)
if i < count - 1: # Don't wait after the last notification
await anyio.sleep(interval)
return [
types.TextContent(
type="text",
text=(f"Sent {count} notifications with {interval}s interval for caller: {caller}"),
)
]
@app.list_tools()
async def list_tools() -> list[types.Tool]:
return [
types.Tool(
name="start-notification-stream",
description=("Sends a stream of notifications with configurable count and interval"),
input_schema={
"type": "object",
"required": ["interval", "count", "caller"],
"properties": {
"interval": {
"type": "number",
"description": "Interval between notifications in seconds",
},
"count": {
"type": "number",
"description": "Number of notifications to send",
},
"caller": {
"type": "string",
"description": ("Identifier of the caller to include in notifications"),
},
},
},
)
]
# Create the session manager with true stateless mode # Create the session manager with true stateless mode
session_manager = StreamableHTTPSessionManager( session_manager = StreamableHTTPSessionManager(

141
examples/servers/simple-streamablehttp/mcp_simple_streamablehttp/server.py
View file

@ -1,12 +1,11 @@
import contextlib import contextlib
import logging import logging
from collections.abc import AsyncIterator from collections.abc import AsyncIterator
from typing import Any
import anyio import anyio
import click import click
from mcp import types from mcp import types
from mcp.server.lowlevel import Server from mcp.server import Server, ServerRequestContext
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
from starlette.applications import Starlette from starlette.applications import Starlette
from starlette.middleware.cors import CORSMiddleware from starlette.middleware.cors import CORSMiddleware
@ -19,6 +18,75 @@ from .event_store import InMemoryEventStore
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
async def handle_list_tools(
ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
return types.ListToolsResult(
tools=[
types.Tool(
name="start-notification-stream",
description="Sends a stream of notifications with configurable count and interval",
input_schema={
"type": "object",
"required": ["interval", "count", "caller"],
"properties": {
"interval": {
"type": "number",
"description": "Interval between notifications in seconds",
},
"count": {
"type": "number",
"description": "Number of notifications to send",
},
"caller": {
"type": "string",
"description": "Identifier of the caller to include in notifications",
},
},
},
)
]
)
async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
arguments = params.arguments or {}
interval = arguments.get("interval", 1.0)
count = arguments.get("count", 5)
caller = arguments.get("caller", "unknown")
# Send the specified number of notifications with the given interval
for i in range(count):
# Include more detailed message for resumability demonstration
notification_msg = f"[{i + 1}/{count}] Event from '{caller}' - Use Last-Event-ID to resume if disconnected"
await ctx.session.send_log_message(
level="info",
data=notification_msg,
logger="notification_stream",
# Associates this notification with the original request
# Ensures notifications are sent to the correct response stream
# Without this, notifications will either go to:
# - a standalone SSE stream (if GET request is supported)
# - nowhere (if GET request isn't supported)
related_request_id=ctx.request_id,
)
logger.debug(f"Sent notification {i + 1}/{count} for caller: {caller}")
if i < count - 1: # Don't wait after the last notification
await anyio.sleep(interval)
# This will send a resource notification through standalone SSE
# established by GET request
await ctx.session.send_resource_updated(uri="http:///test_resource")
return types.CallToolResult(
content=[
types.TextContent(
type="text",
text=(f"Sent {count} notifications with {interval}s interval for caller: {caller}"),
)
]
)
@click.command() @click.command()
@click.option("--port", default=3000, help="Port to listen on for HTTP") @click.option("--port", default=3000, help="Port to listen on for HTTP")
@click.option( @click.option(
@ -43,70 +111,11 @@ def main(
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
) )
app = Server("mcp-streamable-http-demo") app = Server(
"mcp-streamable-http-demo",
@app.call_tool() on_list_tools=handle_list_tools,
async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.ContentBlock]: on_call_tool=handle_call_tool,
ctx = app.request_context )
interval = arguments.get("interval", 1.0)
count = arguments.get("count", 5)
caller = arguments.get("caller", "unknown")
# Send the specified number of notifications with the given interval
for i in range(count):
# Include more detailed message for resumability demonstration
notification_msg = f"[{i + 1}/{count}] Event from '{caller}' - Use Last-Event-ID to resume if disconnected"
await ctx.session.send_log_message(
level="info",
data=notification_msg,
logger="notification_stream",
# Associates this notification with the original request
# Ensures notifications are sent to the correct response stream
# Without this, notifications will either go to:
# - a standalone SSE stream (if GET request is supported)
# - nowhere (if GET request isn't supported)
related_request_id=ctx.request_id,
)
logger.debug(f"Sent notification {i + 1}/{count} for caller: {caller}")
if i < count - 1: # Don't wait after the last notification
await anyio.sleep(interval)
# This will send a resource notificaiton though standalone SSE
# established by GET request
await ctx.session.send_resource_updated(uri="http:///test_resource")
return [
types.TextContent(
type="text",
text=(f"Sent {count} notifications with {interval}s interval for caller: {caller}"),
)
]
@app.list_tools()
async def list_tools() -> list[types.Tool]:
return [
types.Tool(
name="start-notification-stream",
description=("Sends a stream of notifications with configurable count and interval"),
input_schema={
"type": "object",
"required": ["interval", "count", "caller"],
"properties": {
"interval": {
"type": "number",
"description": "Interval between notifications in seconds",
},
"count": {
"type": "number",
"description": "Number of notifications to send",
},
"caller": {
"type": "string",
"description": ("Identifier of the caller to include in notifications"),
},
},
},
)
]
# Create event store for resumability # Create event store for resumability
# The InMemoryEventStore enables resumability support for StreamableHTTP transport. # The InMemoryEventStore enables resumability support for StreamableHTTP transport.

89
examples/servers/simple-task-interactive/mcp_simple_task_interactive/server.py
View file

@ -13,42 +13,39 @@ from typing import Any
import click import click
import uvicorn import uvicorn
from mcp import types from mcp import types
from mcp.server import Server, ServerRequestContext
from mcp.server.experimental.task_context import ServerTaskContext from mcp.server.experimental.task_context import ServerTaskContext
from mcp.server.lowlevel import Server
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
from starlette.applications import Starlette from starlette.applications import Starlette
from starlette.routing import Mount from starlette.routing import Mount
server = Server("simple-task-interactive")
# Enable task support - this auto-registers all handlers async def handle_list_tools(
server.experimental.enable_tasks() ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
return types.ListToolsResult(
tools=[
types.Tool(
name="confirm_delete",
description="Asks for confirmation before deleting (demonstrates elicitation)",
input_schema={
"type": "object",
"properties": {"filename": {"type": "string"}},
},
execution=types.ToolExecution(task_support=types.TASK_REQUIRED),
),
types.Tool(
name="write_haiku",
description="Asks LLM to write a haiku (demonstrates sampling)",
input_schema={"type": "object", "properties": {"topic": {"type": "string"}}},
execution=types.ToolExecution(task_support=types.TASK_REQUIRED),
),
]
)
@server.list_tools() async def handle_confirm_delete(ctx: ServerRequestContext, arguments: dict[str, Any]) -> types.CreateTaskResult:
async def list_tools() -> list[types.Tool]:
return [
types.Tool(
name="confirm_delete",
description="Asks for confirmation before deleting (demonstrates elicitation)",
input_schema={
"type": "object",
"properties": {"filename": {"type": "string"}},
},
execution=types.ToolExecution(task_support=types.TASK_REQUIRED),
),
types.Tool(
name="write_haiku",
description="Asks LLM to write a haiku (demonstrates sampling)",
input_schema={"type": "object", "properties": {"topic": {"type": "string"}}},
execution=types.ToolExecution(task_support=types.TASK_REQUIRED),
),
]
async def handle_confirm_delete(arguments: dict[str, Any]) -> types.CreateTaskResult:
"""Handle the confirm_delete tool - demonstrates elicitation.""" """Handle the confirm_delete tool - demonstrates elicitation."""
ctx = server.request_context
ctx.experimental.validate_task_mode(types.TASK_REQUIRED) ctx.experimental.validate_task_mode(types.TASK_REQUIRED)
filename = arguments.get("filename", "unknown.txt") filename = arguments.get("filename", "unknown.txt")
@ -80,9 +77,8 @@ async def handle_confirm_delete(arguments: dict[str, Any]) -> types.CreateTaskRe
return await ctx.experimental.run_task(work) return await ctx.experimental.run_task(work)
async def handle_write_haiku(arguments: dict[str, Any]) -> types.CreateTaskResult: async def handle_write_haiku(ctx: ServerRequestContext, arguments: dict[str, Any]) -> types.CreateTaskResult:
"""Handle the write_haiku tool - demonstrates sampling.""" """Handle the write_haiku tool - demonstrates sampling."""
ctx = server.request_context
ctx.experimental.validate_task_mode(types.TASK_REQUIRED) ctx.experimental.validate_task_mode(types.TASK_REQUIRED)
topic = arguments.get("topic", "nature") topic = arguments.get("topic", "nature")
@ -111,18 +107,31 @@ async def handle_write_haiku(arguments: dict[str, Any]) -> types.CreateTaskResul
return await ctx.experimental.run_task(work) return await ctx.experimental.run_task(work)
@server.call_tool() async def handle_call_tool(
async def handle_call_tool(name: str, arguments: dict[str, Any]) -> types.CallToolResult | types.CreateTaskResult: ctx: ServerRequestContext, params: types.CallToolRequestParams
) -> types.CallToolResult | types.CreateTaskResult:
"""Dispatch tool calls to their handlers.""" """Dispatch tool calls to their handlers."""
if name == "confirm_delete": arguments = params.arguments or {}
return await handle_confirm_delete(arguments)
elif name == "write_haiku": if params.name == "confirm_delete":
return await handle_write_haiku(arguments) return await handle_confirm_delete(ctx, arguments)
else: elif params.name == "write_haiku":
return types.CallToolResult( return await handle_write_haiku(ctx, arguments)
content=[types.TextContent(type="text", text=f"Unknown tool: {name}")],
is_error=True, return types.CallToolResult(
) content=[types.TextContent(type="text", text=f"Unknown tool: {params.name}")],
is_error=True,
)
server = Server(
"simple-task-interactive",
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
# Enable task support - this auto-registers all handlers
server.experimental.enable_tasks()
def create_app(session_manager: StreamableHTTPSessionManager) -> Starlette: def create_app(session_manager: StreamableHTTPSessionManager) -> Starlette:

96
examples/servers/simple-task/mcp_simple_task/server.py
View file

@ -2,68 +2,70 @@
from collections.abc import AsyncIterator from collections.abc import AsyncIterator
from contextlib import asynccontextmanager from contextlib import asynccontextmanager
from typing import Any
import anyio import anyio
import click import click
import uvicorn import uvicorn
from mcp import types from mcp import types
from mcp.server import Server, ServerRequestContext
from mcp.server.experimental.task_context import ServerTaskContext from mcp.server.experimental.task_context import ServerTaskContext
from mcp.server.lowlevel import Server
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
from starlette.applications import Starlette from starlette.applications import Starlette
from starlette.routing import Mount from starlette.routing import Mount
server = Server("simple-task-server")
async def handle_list_tools(
ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
return types.ListToolsResult(
tools=[
types.Tool(
name="long_running_task",
description="A task that takes a few seconds to complete with status updates",
input_schema={"type": "object", "properties": {}},
execution=types.ToolExecution(task_support=types.TASK_REQUIRED),
)
]
)
async def handle_call_tool(
ctx: ServerRequestContext, params: types.CallToolRequestParams
) -> types.CallToolResult | types.CreateTaskResult:
"""Dispatch tool calls to their handlers."""
if params.name == "long_running_task":
ctx.experimental.validate_task_mode(types.TASK_REQUIRED)
async def work(task: ServerTaskContext) -> types.CallToolResult:
await task.update_status("Starting work...")
await anyio.sleep(1)
await task.update_status("Processing step 1...")
await anyio.sleep(1)
await task.update_status("Processing step 2...")
await anyio.sleep(1)
return types.CallToolResult(content=[types.TextContent(type="text", text="Task completed!")])
return await ctx.experimental.run_task(work)
return types.CallToolResult(
content=[types.TextContent(type="text", text=f"Unknown tool: {params.name}")],
is_error=True,
)
server = Server(
"simple-task-server",
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
# One-line setup: auto-registers get_task, get_task_result, list_tasks, cancel_task # One-line setup: auto-registers get_task, get_task_result, list_tasks, cancel_task
server.experimental.enable_tasks() server.experimental.enable_tasks()
@server.list_tools()
async def list_tools() -> list[types.Tool]:
return [
types.Tool(
name="long_running_task",
description="A task that takes a few seconds to complete with status updates",
input_schema={"type": "object", "properties": {}},
execution=types.ToolExecution(task_support=types.TASK_REQUIRED),
)
]
async def handle_long_running_task(arguments: dict[str, Any]) -> types.CreateTaskResult:
"""Handle the long_running_task tool - demonstrates status updates."""
ctx = server.request_context
ctx.experimental.validate_task_mode(types.TASK_REQUIRED)
async def work(task: ServerTaskContext) -> types.CallToolResult:
await task.update_status("Starting work...")
await anyio.sleep(1)
await task.update_status("Processing step 1...")
await anyio.sleep(1)
await task.update_status("Processing step 2...")
await anyio.sleep(1)
return types.CallToolResult(content=[types.TextContent(type="text", text="Task completed!")])
return await ctx.experimental.run_task(work)
@server.call_tool()
async def handle_call_tool(name: str, arguments: dict[str, Any]) -> types.CallToolResult | types.CreateTaskResult:
"""Dispatch tool calls to their handlers."""
if name == "long_running_task":
return await handle_long_running_task(arguments)
else:
return types.CallToolResult(
content=[types.TextContent(type="text", text=f"Unknown tool: {name}")],
is_error=True,
)
@click.command() @click.command()
@click.option("--port", default=8000, help="Port to listen on") @click.option("--port", default=8000, help="Port to listen on")
def main(port: int) -> int: def main(port: int) -> int:

58
examples/servers/simple-tool/mcp_simple_tool/server.py
View file

@ -1,9 +1,7 @@
from typing import Any
import anyio import anyio
import click import click
from mcp import types from mcp import types
from mcp.server.lowlevel import Server from mcp.server import Server, ServerRequestContext
from mcp.shared._httpx_utils import create_mcp_http_client from mcp.shared._httpx_utils import create_mcp_http_client
from starlette.requests import Request from starlette.requests import Request
@ -18,28 +16,11 @@ async def fetch_website(
return [types.TextContent(type="text", text=response.text)] return [types.TextContent(type="text", text=response.text)]
@click.command() async def handle_list_tools(
@click.option("--port", default=8000, help="Port to listen on for SSE") ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
@click.option( ) -> types.ListToolsResult:
"--transport", return types.ListToolsResult(
type=click.Choice(["stdio", "sse"]), tools=[
default="stdio",
help="Transport type",
)
def main(port: int, transport: str) -> int:
app = Server("mcp-website-fetcher")
@app.call_tool()
async def fetch_tool(name: str, arguments: dict[str, Any]) -> list[types.ContentBlock]:
if name != "fetch":
raise ValueError(f"Unknown tool: {name}")
if "url" not in arguments:
raise ValueError("Missing required argument 'url'")
return await fetch_website(arguments["url"])
@app.list_tools()
async def list_tools() -> list[types.Tool]:
return [
types.Tool( types.Tool(
name="fetch", name="fetch",
title="Website Fetcher", title="Website Fetcher",
@ -56,6 +37,33 @@ def main(port: int, transport: str) -> int:
}, },
) )
] ]
)
async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
if params.name != "fetch":
raise ValueError(f"Unknown tool: {params.name}")
arguments = params.arguments or {}
if "url" not in arguments:
raise ValueError("Missing required argument 'url'")
content = await fetch_website(arguments["url"])
return types.CallToolResult(content=content)
@click.command()
@click.option("--port", default=8000, help="Port to listen on for SSE")
@click.option(
"--transport",
type=click.Choice(["stdio", "sse"]),
default="stdio",
help="Transport type",
)
def main(port: int, transport: str) -> int:
app = Server(
"mcp-website-fetcher",
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
if transport == "sse": if transport == "sse":
from mcp.server.sse import SseServerTransport from mcp.server.sse import SseServerTransport

180
examples/servers/sse-polling-demo/mcp_sse_polling_demo/server.py
View file

@ -15,12 +15,11 @@ Run with:
import contextlib import contextlib
import logging import logging
from collections.abc import AsyncIterator from collections.abc import AsyncIterator
from typing import Any
import anyio import anyio
import click import click
from mcp import types from mcp import types
from mcp.server.lowlevel import Server from mcp.server import Server, ServerRequestContext
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
from starlette.applications import Starlette from starlette.applications import Starlette
from starlette.routing import Mount from starlette.routing import Mount
@ -31,88 +30,12 @@ from .event_store import InMemoryEventStore
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
@click.command() async def handle_list_tools(
@click.option("--port", default=3000, help="Port to listen on") ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
@click.option( ) -> types.ListToolsResult:
"--log-level", """List available tools."""
default="INFO", return types.ListToolsResult(
help="Logging level (DEBUG, INFO, WARNING, ERROR)", tools=[
)
@click.option(
"--retry-interval",
default=100,
help="SSE retry interval in milliseconds (sent to client)",
)
def main(port: int, log_level: str, retry_interval: int) -> int:
"""Run the SSE Polling Demo server."""
logging.basicConfig(
level=getattr(logging, log_level.upper()),
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)
# Create the lowlevel server
app = Server("sse-polling-demo")
@app.call_tool()
async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.ContentBlock]:
"""Handle tool calls."""
ctx = app.request_context
if name == "process_batch":
items = arguments.get("items", 10)
checkpoint_every = arguments.get("checkpoint_every", 3)
if items < 1 or items > 100:
return [types.TextContent(type="text", text="Error: items must be between 1 and 100")]
if checkpoint_every < 1 or checkpoint_every > 20:
return [types.TextContent(type="text", text="Error: checkpoint_every must be between 1 and 20")]
await ctx.session.send_log_message(
level="info",
data=f"Starting batch processing of {items} items...",
logger="process_batch",
related_request_id=ctx.request_id,
)
for i in range(1, items + 1):
# Simulate work
await anyio.sleep(0.5)
# Report progress
await ctx.session.send_log_message(
level="info",
data=f"[{i}/{items}] Processing item {i}",
logger="process_batch",
related_request_id=ctx.request_id,
)
# Checkpoint: close stream to trigger client reconnect
if i % checkpoint_every == 0 and i < items:
await ctx.session.send_log_message(
level="info",
data=f"Checkpoint at item {i} - closing SSE stream for polling",
logger="process_batch",
related_request_id=ctx.request_id,
)
if ctx.close_sse_stream:
logger.info(f"Closing SSE stream at checkpoint {i}")
await ctx.close_sse_stream()
# Wait for client to reconnect (must be > retry_interval of 100ms)
await anyio.sleep(0.2)
return [
types.TextContent(
type="text",
text=f"Successfully processed {items} items with checkpoints every {checkpoint_every} items",
)
]
return [types.TextContent(type="text", text=f"Unknown tool: {name}")]
@app.list_tools()
async def list_tools() -> list[types.Tool]:
"""List available tools."""
return [
types.Tool( types.Tool(
name="process_batch", name="process_batch",
description=( description=(
@ -136,6 +59,95 @@ def main(port: int, log_level: str, retry_interval: int) -> int:
}, },
) )
] ]
)
async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
"""Handle tool calls."""
arguments = params.arguments or {}
if params.name == "process_batch":
items = arguments.get("items", 10)
checkpoint_every = arguments.get("checkpoint_every", 3)
if items < 1 or items > 100:
return types.CallToolResult(
content=[types.TextContent(type="text", text="Error: items must be between 1 and 100")]
)
if checkpoint_every < 1 or checkpoint_every > 20:
return types.CallToolResult(
content=[types.TextContent(type="text", text="Error: checkpoint_every must be between 1 and 20")]
)
await ctx.session.send_log_message(
level="info",
data=f"Starting batch processing of {items} items...",
logger="process_batch",
related_request_id=ctx.request_id,
)
for i in range(1, items + 1):
# Simulate work
await anyio.sleep(0.5)
# Report progress
await ctx.session.send_log_message(
level="info",
data=f"[{i}/{items}] Processing item {i}",
logger="process_batch",
related_request_id=ctx.request_id,
)
# Checkpoint: close stream to trigger client reconnect
if i % checkpoint_every == 0 and i < items:
await ctx.session.send_log_message(
level="info",
data=f"Checkpoint at item {i} - closing SSE stream for polling",
logger="process_batch",
related_request_id=ctx.request_id,
)
if ctx.close_sse_stream:
logger.info(f"Closing SSE stream at checkpoint {i}")
await ctx.close_sse_stream()
# Wait for client to reconnect (must be > retry_interval of 100ms)
await anyio.sleep(0.2)
return types.CallToolResult(
content=[
types.TextContent(
type="text",
text=f"Successfully processed {items} items with checkpoints every {checkpoint_every} items",
)
]
)
return types.CallToolResult(content=[types.TextContent(type="text", text=f"Unknown tool: {params.name}")])
@click.command()
@click.option("--port", default=3000, help="Port to listen on")
@click.option(
"--log-level",
default="INFO",
help="Logging level (DEBUG, INFO, WARNING, ERROR)",
)
@click.option(
"--retry-interval",
default=100,
help="SSE retry interval in milliseconds (sent to client)",
)
def main(port: int, log_level: str, retry_interval: int) -> int:
"""Run the SSE Polling Demo server."""
logging.basicConfig(
level=getattr(logging, log_level.upper()),
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)
app = Server(
"sse-polling-demo",
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
# Create event store for resumability # Create event store for resumability
event_store = InMemoryEventStore() event_store = InMemoryEventStore()

96
examples/servers/structured-output-lowlevel/mcp_structured_output_lowlevel/__main__.py
View file

@ -2,60 +2,54 @@
"""Example low-level MCP server demonstrating structured output support. """Example low-level MCP server demonstrating structured output support.
This example shows how to use the low-level server API to return This example shows how to use the low-level server API to return
structured data from tools, with automatic validation against output structured data from tools.
schemas.
""" """
import asyncio import asyncio
import json
import random
from datetime import datetime from datetime import datetime
from typing import Any
import mcp.server.stdio import mcp.server.stdio
from mcp import types from mcp import types
from mcp.server.lowlevel import NotificationOptions, Server from mcp.server import Server, ServerRequestContext
from mcp.server.models import InitializationOptions
# Create low-level server instance
server = Server("structured-output-lowlevel-example")
@server.list_tools() async def handle_list_tools(
async def list_tools() -> list[types.Tool]: ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
"""List available tools with their schemas.""" """List available tools with their schemas."""
return [ return types.ListToolsResult(
types.Tool( tools=[
name="get_weather", types.Tool(
description="Get weather information (simulated)", name="get_weather",
input_schema={ description="Get weather information (simulated)",
"type": "object", input_schema={
"properties": {"city": {"type": "string", "description": "City name"}}, "type": "object",
"required": ["city"], "properties": {"city": {"type": "string", "description": "City name"}},
}, "required": ["city"],
output_schema={
"type": "object",
"properties": {
"temperature": {"type": "number"},
"conditions": {"type": "string"},
"humidity": {"type": "integer", "minimum": 0, "maximum": 100},
"wind_speed": {"type": "number"},
"timestamp": {"type": "string", "format": "date-time"},
}, },
"required": ["temperature", "conditions", "humidity", "wind_speed", "timestamp"], output_schema={
}, "type": "object",
), "properties": {
] "temperature": {"type": "number"},
"conditions": {"type": "string"},
"humidity": {"type": "integer", "minimum": 0, "maximum": 100},
"wind_speed": {"type": "number"},
"timestamp": {"type": "string", "format": "date-time"},
},
"required": ["temperature", "conditions", "humidity", "wind_speed", "timestamp"],
},
),
]
)
@server.call_tool() async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
"""Handle tool call with structured output.""" """Handle tool call with structured output."""
if name == "get_weather": if params.name == "get_weather":
# city = arguments["city"] # Would be used with real weather API
# Simulate weather data (in production, call a real weather API) # Simulate weather data (in production, call a real weather API)
import random
weather_conditions = ["sunny", "cloudy", "rainy", "partly cloudy", "foggy"] weather_conditions = ["sunny", "cloudy", "rainy", "partly cloudy", "foggy"]
weather_data = { weather_data = {
@ -66,12 +60,19 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
"timestamp": datetime.now().isoformat(), "timestamp": datetime.now().isoformat(),
} }
# Return structured data only return types.CallToolResult(
# The low-level server will serialize this to JSON content automatically content=[types.TextContent(type="text", text=json.dumps(weather_data, indent=2))],
return weather_data structured_content=weather_data,
)
else: raise ValueError(f"Unknown tool: {params.name}")
raise ValueError(f"Unknown tool: {name}")
server = Server(
"structured-output-lowlevel-example",
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
async def run(): async def run():
@ -80,14 +81,7 @@ async def run():
await server.run( await server.run(
read_stream, read_stream,
write_stream, write_stream,
InitializationOptions( server.create_initialization_options(),
server_name="structured-output-lowlevel-example",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
) )

52
examples/snippets/servers/lowlevel/basic.py
View file

@ -6,32 +6,30 @@ import asyncio
import mcp.server.stdio import mcp.server.stdio
from mcp import types from mcp import types
from mcp.server.lowlevel import NotificationOptions, Server from mcp.server import Server, ServerRequestContext
from mcp.server.models import InitializationOptions
# Create a server instance
server = Server("example-server")
@server.list_prompts() async def handle_list_prompts(
async def handle_list_prompts() -> list[types.Prompt]: ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListPromptsResult:
"""List available prompts.""" """List available prompts."""
return [ return types.ListPromptsResult(
types.Prompt( prompts=[
name="example-prompt", types.Prompt(
description="An example prompt template", name="example-prompt",
arguments=[types.PromptArgument(name="arg1", description="Example argument", required=True)], description="An example prompt template",
) arguments=[types.PromptArgument(name="arg1", description="Example argument", required=True)],
] )
]
)
@server.get_prompt() async def handle_get_prompt(ctx: ServerRequestContext, params: types.GetPromptRequestParams) -> types.GetPromptResult:
async def handle_get_prompt(name: str, arguments: dict[str, str] | None) -> types.GetPromptResult:
"""Get a specific prompt by name.""" """Get a specific prompt by name."""
if name != "example-prompt": if params.name != "example-prompt":
raise ValueError(f"Unknown prompt: {name}") raise ValueError(f"Unknown prompt: {params.name}")
arg1_value = (arguments or {}).get("arg1", "default") arg1_value = (params.arguments or {}).get("arg1", "default")
return types.GetPromptResult( return types.GetPromptResult(
description="Example prompt", description="Example prompt",
@ -44,20 +42,20 @@ async def handle_get_prompt(name: str, arguments: dict[str, str] | None) -> type
) )
server = Server(
"example-server",
on_list_prompts=handle_list_prompts,
on_get_prompt=handle_get_prompt,
)
async def run(): async def run():
"""Run the basic low-level server.""" """Run the basic low-level server."""
async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
await server.run( await server.run(
read_stream, read_stream,
write_stream, write_stream,
InitializationOptions( server.create_initialization_options(),
server_name="example",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
) )

60
examples/snippets/servers/lowlevel/direct_call_tool_result.py
View file

@ -3,44 +3,49 @@ uv run examples/snippets/servers/lowlevel/direct_call_tool_result.py
""" """
import asyncio import asyncio
from typing import Any
import mcp.server.stdio import mcp.server.stdio
from mcp import types from mcp import types
from mcp.server.lowlevel import NotificationOptions, Server from mcp.server import Server, ServerRequestContext
from mcp.server.models import InitializationOptions
server = Server("example-server")
@server.list_tools() async def handle_list_tools(
async def list_tools() -> list[types.Tool]: ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
"""List available tools.""" """List available tools."""
return [ return types.ListToolsResult(
types.Tool( tools=[
name="advanced_tool", types.Tool(
description="Tool with full control including _meta field", name="advanced_tool",
input_schema={ description="Tool with full control including _meta field",
"type": "object", input_schema={
"properties": {"message": {"type": "string"}}, "type": "object",
"required": ["message"], "properties": {"message": {"type": "string"}},
}, "required": ["message"],
) },
] )
]
)
@server.call_tool() async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
async def handle_call_tool(name: str, arguments: dict[str, Any]) -> types.CallToolResult:
"""Handle tool calls by returning CallToolResult directly.""" """Handle tool calls by returning CallToolResult directly."""
if name == "advanced_tool": if params.name == "advanced_tool":
message = str(arguments.get("message", "")) message = (params.arguments or {}).get("message", "")
return types.CallToolResult( return types.CallToolResult(
content=[types.TextContent(type="text", text=f"Processed: {message}")], content=[types.TextContent(type="text", text=f"Processed: {message}")],
structured_content={"result": "success", "message": message}, structured_content={"result": "success", "message": message},
_meta={"hidden": "data for client applications only"}, _meta={"hidden": "data for client applications only"},
) )
raise ValueError(f"Unknown tool: {name}") raise ValueError(f"Unknown tool: {params.name}")
server = Server(
"example-server",
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
async def run(): async def run():
@ -49,14 +54,7 @@ async def run():
await server.run( await server.run(
read_stream, read_stream,
write_stream, write_stream,
InitializationOptions( server.create_initialization_options(),
server_name="example",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
) )

78
examples/snippets/servers/lowlevel/lifespan.py
View file

@ -4,12 +4,11 @@ uv run examples/snippets/servers/lowlevel/lifespan.py
from collections.abc import AsyncIterator from collections.abc import AsyncIterator
from contextlib import asynccontextmanager from contextlib import asynccontextmanager
from typing import Any from typing import TypedDict
import mcp.server.stdio import mcp.server.stdio
from mcp import types from mcp import types
from mcp.server.lowlevel import NotificationOptions, Server from mcp.server import Server, ServerRequestContext
from mcp.server.models import InitializationOptions
# Mock database class for example # Mock database class for example
@ -32,52 +31,58 @@ class Database:
return [{"id": "1", "name": "Example", "query": query_str}] return [{"id": "1", "name": "Example", "query": query_str}]
class AppContext(TypedDict):
db: Database
@asynccontextmanager @asynccontextmanager
async def server_lifespan(_server: Server) -> AsyncIterator[dict[str, Any]]: async def server_lifespan(_server: Server[AppContext]) -> AsyncIterator[AppContext]:
"""Manage server startup and shutdown lifecycle.""" """Manage server startup and shutdown lifecycle."""
# Initialize resources on startup
db = await Database.connect() db = await Database.connect()
try: try:
yield {"db": db} yield {"db": db}
finally: finally:
# Clean up on shutdown
await db.disconnect() await db.disconnect()
# Pass lifespan to server async def handle_list_tools(
server = Server("example-server", lifespan=server_lifespan) ctx: ServerRequestContext[AppContext], params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
"""List available tools.""" """List available tools."""
return [ return types.ListToolsResult(
types.Tool( tools=[
name="query_db", types.Tool(
description="Query the database", name="query_db",
input_schema={ description="Query the database",
"type": "object", input_schema={
"properties": {"query": {"type": "string", "description": "SQL query to execute"}}, "type": "object",
"required": ["query"], "properties": {"query": {"type": "string", "description": "SQL query to execute"}},
}, "required": ["query"],
) },
] )
]
)
@server.call_tool() async def handle_call_tool(
async def query_db(name: str, arguments: dict[str, Any]) -> list[types.TextContent]: ctx: ServerRequestContext[AppContext], params: types.CallToolRequestParams
) -> types.CallToolResult:
"""Handle database query tool call.""" """Handle database query tool call."""
if name != "query_db": if params.name != "query_db":
raise ValueError(f"Unknown tool: {name}") raise ValueError(f"Unknown tool: {params.name}")
# Access lifespan context
ctx = server.request_context
db = ctx.lifespan_context["db"] db = ctx.lifespan_context["db"]
results = await db.query((params.arguments or {})["query"])
# Execute query return types.CallToolResult(content=[types.TextContent(type="text", text=f"Query results: {results}")])
results = await db.query(arguments["query"])
return [types.TextContent(type="text", text=f"Query results: {results}")]
server = Server(
"example-server",
lifespan=server_lifespan,
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
async def run(): async def run():
@ -86,14 +91,7 @@ async def run():
await server.run( await server.run(
read_stream, read_stream,
write_stream, write_stream,
InitializationOptions( server.create_initialization_options(),
server_name="example-server",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
) )

92
examples/snippets/servers/lowlevel/structured_output.py
View file

@ -3,62 +3,67 @@ uv run examples/snippets/servers/lowlevel/structured_output.py
""" """
import asyncio import asyncio
from typing import Any import json
import mcp.server.stdio import mcp.server.stdio
from mcp import types from mcp import types
from mcp.server.lowlevel import NotificationOptions, Server from mcp.server import Server, ServerRequestContext
from mcp.server.models import InitializationOptions
server = Server("example-server")
@server.list_tools() async def handle_list_tools(
async def list_tools() -> list[types.Tool]: ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
"""List available tools with structured output schemas.""" """List available tools with structured output schemas."""
return [ return types.ListToolsResult(
types.Tool( tools=[
name="get_weather", types.Tool(
description="Get current weather for a city", name="get_weather",
input_schema={ description="Get current weather for a city",
"type": "object", input_schema={
"properties": {"city": {"type": "string", "description": "City name"}}, "type": "object",
"required": ["city"], "properties": {"city": {"type": "string", "description": "City name"}},
}, "required": ["city"],
output_schema={
"type": "object",
"properties": {
"temperature": {"type": "number", "description": "Temperature in Celsius"},
"condition": {"type": "string", "description": "Weather condition"},
"humidity": {"type": "number", "description": "Humidity percentage"},
"city": {"type": "string", "description": "City name"},
}, },
"required": ["temperature", "condition", "humidity", "city"], output_schema={
}, "type": "object",
) "properties": {
] "temperature": {"type": "number", "description": "Temperature in Celsius"},
"condition": {"type": "string", "description": "Weather condition"},
"humidity": {"type": "number", "description": "Humidity percentage"},
"city": {"type": "string", "description": "City name"},
},
"required": ["temperature", "condition", "humidity", "city"],
},
)
]
)
@server.call_tool() async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
async def call_tool(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
"""Handle tool calls with structured output.""" """Handle tool calls with structured output."""
if name == "get_weather": if params.name == "get_weather":
city = arguments["city"] city = (params.arguments or {})["city"]
# Simulated weather data - in production, call a weather API
weather_data = { weather_data = {
"temperature": 22.5, "temperature": 22.5,
"condition": "partly cloudy", "condition": "partly cloudy",
"humidity": 65, "humidity": 65,
"city": city, # Include the requested city "city": city,
} }
# low-level server will validate structured output against the tool's return types.CallToolResult(
# output schema, and additionally serialize it into a TextContent block content=[types.TextContent(type="text", text=json.dumps(weather_data, indent=2))],
# for backwards compatibility with pre-2025-06-18 clients. structured_content=weather_data,
return weather_data )
else:
raise ValueError(f"Unknown tool: {name}") raise ValueError(f"Unknown tool: {params.name}")
server = Server(
"example-server",
on_list_tools=handle_list_tools,
on_call_tool=handle_call_tool,
)
async def run(): async def run():
@ -67,14 +72,7 @@ async def run():
await server.run( await server.run(
read_stream, read_stream,
write_stream, write_stream,
InitializationOptions( server.create_initialization_options(),
server_name="structured-output-example",
server_version="0.1.0",
capabilities=server.get_capabilities(
notification_options=NotificationOptions(),
experimental_capabilities={},
),
),
) )

17
examples/snippets/servers/pagination_example.py
View file

@ -1,22 +1,20 @@
"""Example of implementing pagination with MCP server decorators.""" """Example of implementing pagination with the low-level MCP server."""
from mcp import types from mcp import types
from mcp.server.lowlevel import Server from mcp.server import Server, ServerRequestContext
# Initialize the server
server = Server("paginated-server")
# Sample data to paginate # Sample data to paginate
ITEMS = [f"Item {i}" for i in range(1, 101)] # 100 items ITEMS = [f"Item {i}" for i in range(1, 101)] # 100 items
@server.list_resources() async def handle_list_resources(
async def list_resources_paginated(request: types.ListResourcesRequest) -> types.ListResourcesResult: ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
) -> types.ListResourcesResult:
"""List resources with pagination support.""" """List resources with pagination support."""
page_size = 10 page_size = 10
# Extract cursor from request params # Extract cursor from request params
cursor = request.params.cursor if request.params is not None else None cursor = params.cursor if params is not None else None
# Parse cursor to get offset # Parse cursor to get offset
start = 0 if cursor is None else int(cursor) start = 0 if cursor is None else int(cursor)
@ -32,3 +30,6 @@ async def list_resources_paginated(request: types.ListResourcesRequest) -> types
next_cursor = str(end) if end < len(ITEMS) else None next_cursor = str(end) if end < len(ITEMS) else None
return types.ListResourcesResult(resources=page_items, next_cursor=next_cursor) return types.ListResourcesResult(resources=page_items, next_cursor=next_cursor)
server = Server("paginated-server", on_list_resources=handle_list_resources)

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

@ -1,5 +1,6 @@
from .context import ServerRequestContext
from .lowlevel import NotificationOptions, Server from .lowlevel import NotificationOptions, Server
from .mcpserver import MCPServer from .mcpserver import MCPServer
from .models import InitializationOptions from .models import InitializationOptions
__all__ = ["Server", "MCPServer", "NotificationOptions", "InitializationOptions"] __all__ = ["Server", "ServerRequestContext", "MCPServer", "NotificationOptions", "InitializationOptions"]

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