Merge branch 'main' into issue-3683-file-system-support

Author: vijaydeepsinha

.github/workflows/main.yml

@@ -11,7 +11,7 @@ permissions:
 
 jobs:
   checks:
-    uses: ./.github/workflows/shared.yml
+    uses: $/.github/workflows/shared.yml
 
   all-green:
     if: always()

.github/workflows/publish-pypi.yml

@@ -38,7 +38,7 @@ jobs:
           path: dist/
 
   checks:
-    uses: ./.github/workflows/shared.yml
+    uses: $/.github/workflows/shared.yml
 
   pypi-publish:
     name: Upload release to PyPI

.pre-commit-config.yaml

@@ -6,8 +6,8 @@ repos:
     hooks:
       - id: end-of-file-fixer
 
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.1.0
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.9.10
     hooks:
       - id: prettier
         types_or: [yaml, json5]

docs/advanced/extensions.md

@@ -25,10 +25,10 @@ Done. The server now advertises `io.modelcontextprotocol/ui` under
     Extensions are fixed at construction. There is no `add_extension` to call later:
     a server's capability map should not change while clients are connected to it.
 
-The capability map rides `server/discover`, which is a **2026-07-28** path. A legacy
-`initialize` handshake has nowhere to put it, so a legacy client simply doesn't see
-the extension. Design for that: an extension *augments* a server, it must not be the
-only way the server is usable.
+The capability map rides `server/discover` on **2026-07-28** connections and the
+`initialize` result on legacy ones. A client that doesn't know an extension ignores
+it. Design for that: an extension *augments* a server, it must not be the only way
+the server is usable.
 
 ## Writing your own
 

docs/advanced/low-level-server.md

@@ -61,7 +61,7 @@ asyncio.run(main())
 The same text the `@mcp.tool()` version produced. Two honest differences:
 
 * `result.structured_content` is `None`. The high-level server wraps a `-> str` into `{"result": ...}` for you; here nobody builds what you didn't build.
-* `list_tools` returns the schema **you** typed, character for character. The high-level version had `"title": "Query"` on every property and a `"title": "search_booksArguments"` at the root: Pydantic artifacts. Down here, if it's on the wire, you put it there.
+* `list_tools` returns the schema **you** typed, character for character. Down here, if it's on the wire, you put it there.
 
 In a test you skip uvicorn and the port: `Client(server)` takes a low-level `Server` in-process exactly like it takes an `MCPServer`, and **[Testing](../get-started/testing.md)** is that pattern.
 

docs/client/index.md

@@ -72,11 +72,10 @@ and `tool.input_schema` is the JSON Schema the server derived from the function'
 {
   "type": "object",
   "properties": {
-    "query": {"title": "Query", "type": "string"},
-    "limit": {"default": 10, "title": "Limit", "type": "integer"}
+    "query": {"type": "string"},
+    "limit": {"default": 10, "type": "integer"}
   },
-  "required": ["query"],
-  "title": "search_booksArguments"
+  "required": ["query"]
 }
 ```
 

docs/handlers/context.md

@@ -30,10 +30,9 @@ This is the part to internalise. Here is the input schema `tools/list` reports f
 {
   "type": "object",
   "properties": {
-    "query": {"title": "Query", "type": "string"}
+    "query": {"type": "string"}
   },
-  "required": ["query"],
-  "title": "search_booksArguments"
+  "required": ["query"]
 }
 ```
 

docs/handlers/dependencies.md

@@ -28,10 +28,9 @@ Here is the input schema `tools/list` reports for `reserve_book`:
 {
   "type": "object",
   "properties": {
-    "title": {"title": "Title", "type": "string"}
+    "title": {"type": "string"}
   },
-  "required": ["title"],
-  "title": "reserve_bookArguments"
+  "required": ["title"]
 }
 ```
 

docs/handlers/lifespan.md

@@ -32,10 +32,9 @@ Nothing new. `ctx` is a **Context** parameter, so the SDK injects it and it neve
 {
   "type": "object",
   "properties": {
-    "genre": {"title": "Genre", "type": "string"}
+    "genre": {"type": "string"}
   },
-  "required": ["genre"],
-  "title": "count_booksArguments"
+  "required": ["genre"]
 }
 ```
 

docs/servers/structured-output.md

@@ -19,10 +19,9 @@ Because of it, the tool the SDK sends during `tools/list` carries an `output_sch
 ```json
 {
   "properties": {
-    "result": {"title": "Result", "type": "integer"}
+    "result": {"type": "integer"}
   },
   "required": ["result"],
-  "title": "get_temperatureOutput",
   "type": "object"
 }
 ```
@@ -59,9 +58,9 @@ Declare the shape as a Pydantic `BaseModel` and return an instance:
 ```json
 {
   "properties": {
-    "temperature": {"description": "Degrees Celsius.", "title": "Temperature", "type": "number"},
-    "humidity": {"description": "Relative humidity, 0 to 1.", "title": "Humidity", "type": "number"},
-    "conditions": {"title": "Conditions", "type": "string"}
+    "temperature": {"description": "Degrees Celsius.", "type": "number"},
+    "humidity": {"description": "Relative humidity, 0 to 1.", "type": "number"},
+    "conditions": {"type": "string"}
   },
   "required": ["temperature", "humidity", "conditions"],
   "title": "WeatherData",
@@ -125,31 +124,30 @@ A `list[...]` isn't a JSON object either, so it gets the `{"result": ...}` wrapp
   "$defs": {
     "WeatherData": {
       "properties": {
-        "temperature": {"title": "Temperature", "type": "number"},
-        "humidity": {"title": "Humidity", "type": "number"},
-        "conditions": {"title": "Conditions", "type": "string"}
+        "temperature": {"type": "number"},
+        "humidity": {"type": "number"},
+        "conditions": {"type": "string"}
       },
       "required": ["temperature", "humidity", "conditions"],
       "title": "WeatherData",
       "type": "object"
     }
   },
   "properties": {
-    "result": {"items": {"$ref": "#/$defs/WeatherData"}, "title": "Result", "type": "array"}
+    "result": {"items": {"$ref": "#/$defs/WeatherData"}, "type": "array"}
   },
   "required": ["result"],
-  "title": "get_forecastOutput",
   "type": "object"
 }
 ```
 
 Ask for a two-day forecast and `structured_content` is `{"result": [{...}, {...}]}`. `content` becomes **two** `TextContent` blocks, one per item: a list is flattened for the model rather than dumped as one string.
 
-`tuple[...]`, unions, and `Optional[...]` are wrapped the same way.
+`tuple[...]`, unions, and `Optional[...]` are wrapped the same way, and so are `set` and `frozenset`, with or without an item type. A bare `list` or `tuple` is not: see **[Content blocks and media](#content-blocks-and-media)**.
 
 ## Dictionaries
 
-`dict[str, ...]` is the one generic that already *is* a JSON object, so it isn't wrapped:
+`dict[str, ...]` (or `typing.Dict[str, ...]`, or a bare `dict`, read as `dict[str, Any]`) is the one generic that already *is* a JSON object, so it isn't wrapped:
 
 ```python title="server.py" hl_lines="9"
 --8<-- "docs_src/structured_output/tutorial006.py"
@@ -158,7 +156,6 @@ Ask for a two-day forecast and `structured_content` is `{"result": [{...}, {...}
 ```json
 {
   "additionalProperties": {"type": "number"},
-  "title": "get_temperaturesDictOutput",
   "type": "object"
 }
 ```
@@ -169,7 +166,7 @@ result.structured_content  # {"London": 16.2, "Reykjavik": 4.4}
 
 The keys must be `str`. A `dict[int, float]` can't be a JSON object, so it falls back to the `{"result": ...}` wrapper.
 
-Dictionary results use Pydantic's `TypeAdapter` for validation and serialization. If you inspect a tool's `FuncMetadata.output_model`, it holds the dictionary type annotation with its schema title.
+Dictionary results use Pydantic's `TypeAdapter` for validation and serialization. If you inspect a tool's `FuncMetadata.output_model`, it holds the dictionary type annotation itself.
 
 ## Validation
 
@@ -215,6 +212,8 @@ The opposite, `structured_output=True`, turns the automatic detection into a req
 
 Content blocks and media (`TextContent`, `EmbeddedResource`, `Image`, `Audio` and friends, on their own, as the items of a `list`, `tuple` or `Sequence`, or as the arms of a union) are opted out for you: they are for the model to read, so auto-detection derives no schema from them (**[Images, audio & icons](media.md)** covers `Image` and `Audio`). `structured_output=True` still forces one for the content-block classes.
 
+A bare `list` or `tuple` is opted out too. Nothing in the annotation says its items aren't blocks, and a schema would send any image it holds twice: once as a block for the model, and again as base64 in `structured_content`. Write the item type (`list[str]`, `tuple[int, ...]`) to get a schema, or pass `structured_output=True` to wrap it as a list of anything. The forced wrapper still has to serialize every item as JSON, so an `Image` or `Audio` in it makes the call fail. Only a bare `list` or `tuple` as the whole annotation is opted out: `list | None` is wrapped like any other union.
+
 ## A class without type hints
 
 There is one way to end up unstructured without asking for it: return a class that has **no annotations on its body**.
@@ -244,9 +243,9 @@ There is one way to end up unstructured without asking for it: return a class th
 ## Recap
 
 * The **return type annotation** is the output schema. It's published in `tools/list` as `output_schema`.
-* Scalars, lists, tuples and unions are wrapped in `{"result": ...}`. Models, `TypedDict`s, dataclasses, annotated classes and `dict[str, ...]` are objects already and stay as they are.
+* Scalars, `list[...]`, `tuple[...]`, sets and unions are wrapped in `{"result": ...}`. Models, `TypedDict`s, dataclasses, annotated classes, `dict[str, ...]` and a bare `dict` are objects already and stay as they are.
 * Every result carries `content` (text, for the model) **and** `structured_content` (data, for the application).
 * What you return is validated against the schema. A mismatch is a tool error, not a corrupt result.
-* `structured_output=False` opts a tool out. Content blocks, `Image` and `Audio` opt out by default; a class without type hints opts out silently, so watch for it.
+* `structured_output=False` opts a tool out. Content blocks, `Image`, `Audio` and a bare `list` or `tuple` opt out by default; a class without type hints opts out silently, so watch for it.
 
 You now own everything a tool can say back. Next, the second primitive: **[Resources](resources.md)**.