Merge branch 'main' into drop-streamablehttp-client

Author: Kludex

examples/clients/simple-auth-client/README.md

@@ -12,63 +12,87 @@ A demonstration of how to use the MCP Python SDK with OAuth authentication over
 
 ```bash
 cd examples/clients/simple-auth-client
-uv sync --reinstall 
+uv sync --reinstall
 ```
 
 ## Usage
 
 ### 1. Start an MCP server with OAuth support
 
+The simple-auth server example provides three server configurations. See [examples/servers/simple-auth/README.md](../../servers/simple-auth/README.md) for full details.
+
+#### Option A: New Architecture (Recommended)
+
+Separate Authorization Server and Resource Server:
+
+```bash
+# Terminal 1: Start Authorization Server on port 9000
+cd examples/servers/simple-auth
+uv run mcp-simple-auth-as --port=9000
+
+# Terminal 2: Start Resource Server on port 8001
+cd examples/servers/simple-auth
+uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http
+```
+
+#### Option B: Legacy Server (Backwards Compatibility)
+
 ```bash
-# Example with mcp-simple-auth
-cd path/to/mcp-simple-auth
-uv run mcp-simple-auth --transport streamable-http --port 3001
+# Single server that acts as both AS and RS (port 8000)
+cd examples/servers/simple-auth
+uv run mcp-simple-auth-legacy --port=8000 --transport=streamable-http
 ```
 
 ### 2. Run the client
 
 ```bash
-uv run mcp-simple-auth-client
+# Connect to Resource Server (new architecture, default port 8001)
+MCP_SERVER_PORT=8001 uv run mcp-simple-auth-client
 
-# Or with custom server URL
-MCP_SERVER_PORT=3001 uv run mcp-simple-auth-client
+# Connect to Legacy Server (port 8000)
+uv run mcp-simple-auth-client
 
 # Use SSE transport
-MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client
+MCP_SERVER_PORT=8001 MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client
 ```
 
 ### 3. Complete OAuth flow
 
 The client will open your browser for authentication. After completing OAuth, you can use commands:
 
 - `list` - List available tools
-- `call <tool_name> [args]` - Call a tool with optional JSON arguments  
+- `call <tool_name> [args]` - Call a tool with optional JSON arguments
 - `quit` - Exit
 
 ## Example
 
 ```markdown
-🔐 Simple MCP Auth Client
-Connecting to: http://localhost:3001
+🚀 Simple MCP Auth Client
+Connecting to: http://localhost:8001/mcp
+Transport type: streamable-http
 
-Please visit the following URL to authorize the application:
-http://localhost:3001/authorize?response_type=code&client_id=...
+🔗 Attempting to connect to http://localhost:8001/mcp...
+📡 Opening StreamableHTTP transport connection with auth...
+Opening browser for authorization: http://localhost:9000/authorize?...
 
-✅ Connected to MCP server at http://localhost:3001
+✅ Connected to MCP server at http://localhost:8001/mcp
 
 mcp> list
 📋 Available tools:
-1. echo - Echo back the input text
+1. get_time
+   Description: Get the current server time.
 
-mcp> call echo {"text": "Hello, world!"}
-🔧 Tool 'echo' result:
-Hello, world!
+mcp> call get_time
+🔧 Tool 'get_time' result:
+{"current_time": "2024-01-15T10:30:00", "timezone": "UTC", ...}
 
 mcp> quit
-👋 Goodbye!
 ```
 
 ## Configuration
 
-- `MCP_SERVER_PORT` - Server URL (default: 8000)
-- `MCP_TRANSPORT_TYPE` - Transport type: `streamable-http` (default) or `sse`
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `MCP_SERVER_PORT` | Port number of the MCP server | `8000` |
+| `MCP_TRANSPORT_TYPE` | Transport type: `streamable-http` or `sse` | `streamable-http` |
+| `MCP_CLIENT_METADATA_URL` | Optional URL for client metadata (CIMD) | None |

examples/servers/simple-auth/README.md

@@ -31,10 +31,10 @@ uv run mcp-simple-auth-as --port=9000
 cd examples/servers/simple-auth
 
 # Start Resource Server on port 8001, connected to Authorization Server
-uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000  --transport=streamable-http
+uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http
 
 # With RFC 8707 strict resource validation (recommended for production)
-uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000  --transport=streamable-http --oauth-strict
+uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http --oauth-strict
 
 ```
 
@@ -84,8 +84,9 @@ For backwards compatibility with older MCP implementations, a legacy server is p
 ### Running the Legacy Server
 
 ```bash
-# Start legacy authorization server on port 8002
-uv run mcp-simple-auth-legacy --port=8002
+# Start legacy server on port 8000 (the default)
+cd examples/servers/simple-auth
+uv run mcp-simple-auth-legacy --port=8000 --transport=streamable-http
 ```
 
 **Differences from the new architecture:**
@@ -101,7 +102,7 @@ uv run mcp-simple-auth-legacy --port=8002
 ```bash
 # Test with client (will automatically fall back to legacy discovery)
 cd examples/clients/simple-auth-client
-MCP_SERVER_PORT=8002 MCP_TRANSPORT_TYPE=streamable-http uv run mcp-simple-auth-client
+MCP_SERVER_PORT=8000 MCP_TRANSPORT_TYPE=streamable-http uv run mcp-simple-auth-client
 ```
 
 The client will:

src/mcp/server/fastmcp/resources/base.py

@@ -1,7 +1,7 @@
 """Base classes and interfaces for FastMCP resources."""
 
 import abc
-from typing import Annotated
+from typing import Annotated, Any
 
 from pydantic import (
     AnyUrl,
@@ -32,6 +32,7 @@ class Resource(BaseModel, abc.ABC):
     )
     icons: list[Icon] | None = Field(default=None, description="Optional list of icons for this resource")
     annotations: Annotations | None = Field(default=None, description="Optional annotations for the resource")
+    meta: dict[str, Any] | None = Field(default=None, description="Optional metadata for this resource")
 
     @field_validator("name", mode="before")
     @classmethod

src/mcp/server/fastmcp/resources/resource_manager.py

@@ -64,6 +64,7 @@ def add_template(
         mime_type: str | None = None,
         icons: list[Icon] | None = None,
         annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> ResourceTemplate:
         """Add a template from a function."""
         template = ResourceTemplate.from_function(
@@ -75,6 +76,7 @@ def add_template(
             mime_type=mime_type,
             icons=icons,
             annotations=annotations,
+            meta=meta,
         )
         self._templates[template.uri_template] = template
         return template

src/mcp/server/fastmcp/resources/templates.py

@@ -30,6 +30,7 @@ class ResourceTemplate(BaseModel):
     mime_type: str = Field(default="text/plain", description="MIME type of the resource content")
     icons: list[Icon] | None = Field(default=None, description="Optional list of icons for the resource template")
     annotations: Annotations | None = Field(default=None, description="Optional annotations for the resource template")
+    meta: dict[str, Any] | None = Field(default=None, description="Optional metadata for this resource template")
     fn: Callable[..., Any] = Field(exclude=True)
     parameters: dict[str, Any] = Field(description="JSON schema for function parameters")
     context_kwarg: str | None = Field(None, description="Name of the kwarg that should receive context")
@@ -45,6 +46,7 @@ def from_function(
         mime_type: str | None = None,
         icons: list[Icon] | None = None,
         annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
         context_kwarg: str | None = None,
     ) -> ResourceTemplate:
         """Create a template from a function."""
@@ -74,6 +76,7 @@ def from_function(
             mime_type=mime_type or "text/plain",
             icons=icons,
             annotations=annotations,
+            meta=meta,
             fn=fn,
             parameters=parameters,
             context_kwarg=context_kwarg,
@@ -112,6 +115,7 @@ async def create_resource(
                 mime_type=self.mime_type,
                 icons=self.icons,
                 annotations=self.annotations,
+                meta=self.meta,
                 fn=lambda: result,  # Capture result in closure
             )
         except Exception as e:

src/mcp/server/fastmcp/resources/types.py

@@ -83,6 +83,7 @@ def from_function(
         mime_type: str | None = None,
         icons: list[Icon] | None = None,
         annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> "FunctionResource":
         """Create a FunctionResource from a function."""
         func_name = name or fn.__name__
@@ -101,6 +102,7 @@ def from_function(
             fn=fn,
             icons=icons,
             annotations=annotations,
+            meta=meta,
         )
 
 

src/mcp/server/fastmcp/server.py

@@ -376,6 +376,7 @@ async def list_resources(self) -> list[MCPResource]:
                 mimeType=resource.mime_type,
                 icons=resource.icons,
                 annotations=resource.annotations,
+                _meta=resource.meta,
             )
             for resource in resources
         ]
@@ -391,6 +392,7 @@ async def list_resource_templates(self) -> list[MCPResourceTemplate]:
                 mimeType=template.mime_type,
                 icons=template.icons,
                 annotations=template.annotations,
+                _meta=template.meta,
             )
             for template in templates
         ]
@@ -405,7 +407,7 @@ async def read_resource(self, uri: AnyUrl | str) -> Iterable[ReadResourceContent
 
         try:
             content = await resource.read()
-            return [ReadResourceContents(content=content, mime_type=resource.mime_type)]
+            return [ReadResourceContents(content=content, mime_type=resource.mime_type, meta=resource.meta)]
         except Exception as e:  # pragma: no cover
             logger.exception(f"Error reading resource {uri}")
             raise ResourceError(str(e))
@@ -557,6 +559,7 @@ def resource(
         mime_type: str | None = None,
         icons: list[Icon] | None = None,
         annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a function as a resource.
 
@@ -575,6 +578,7 @@ def resource(
             title: Optional human-readable title for the resource
             description: Optional description of the resource
             mime_type: Optional MIME type for the resource
+            meta: Optional metadata dictionary for the resource
 
         Example:
             @server.resource("resource://my-resource")
@@ -633,6 +637,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                     mime_type=mime_type,
                     icons=icons,
                     annotations=annotations,
+                    meta=meta,
                 )
             else:
                 # Register as regular resource
@@ -645,6 +650,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                     mime_type=mime_type,
                     icons=icons,
                     annotations=annotations,
+                    meta=meta,
                 )
                 self.add_resource(resource)
             return fn

src/mcp/server/lowlevel/experimental.py

@@ -31,6 +31,7 @@
     ServerResult,
     ServerTasksCapability,
     ServerTasksRequestsCapability,
+    TasksCallCapability,
     TasksCancelCapability,
     TasksListCapability,
     TasksToolsCapability,
@@ -79,7 +80,7 @@ def update_capabilities(self, capabilities: ServerCapabilities) -> None:
             capabilities.tasks.cancel = TasksCancelCapability()
 
         capabilities.tasks.requests = ServerTasksRequestsCapability(
-            tools=TasksToolsCapability()
+            tools=TasksToolsCapability(call=TasksCallCapability())
         )  # assuming always supported for now
 
     def enable_tasks(

src/mcp/server/lowlevel/helper_types.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+from typing import Any
 
 
 @dataclass
@@ -7,3 +8,4 @@ class ReadResourceContents:
 
     content: str | bytes
     mime_type: str | None = None
+    meta: dict[str, Any] | None = None

src/mcp/server/lowlevel/server.py

@@ -344,19 +344,23 @@ def decorator(
             async def handler(req: types.ReadResourceRequest):
                 result = await func(req.params.uri)
 
-                def create_content(data: str | bytes, mime_type: str | None):
+                def create_content(data: str | bytes, mime_type: str | None, meta: dict[str, Any] | None = None):
+                    # Note: ResourceContents uses Field(alias="_meta"), so we must use the alias key
+                    meta_kwargs: dict[str, Any] = {"_meta": meta} if meta is not None else {}
                     match data:
                         case str() as data:
                             return types.TextResourceContents(
                                 uri=req.params.uri,
                                 text=data,
                                 mimeType=mime_type or "text/plain",
+                                **meta_kwargs,
                             )
                         case bytes() as data:  # pragma: no cover
                             return types.BlobResourceContents(
                                 uri=req.params.uri,
                                 blob=base64.b64encode(data).decode(),
                                 mimeType=mime_type or "application/octet-stream",
+                                **meta_kwargs,
                             )
 
                 match result:
@@ -370,7 +374,10 @@ def create_content(data: str | bytes, mime_type: str | None):
                         content = create_content(data, None)
                     case Iterable() as contents:
                         contents_list = [
-                            create_content(content_item.content, content_item.mime_type) for content_item in contents
+                            create_content(
+                                content_item.content, content_item.mime_type, getattr(content_item, "meta", None)
+                            )
+                            for content_item in contents
                         ]
                         return types.ServerResult(
                             types.ReadResourceResult(