Type-check docstring code examples via companion files and unified sync script by jonathanhefner · Pull Request #2119 · modelcontextprotocol/python-sdk

jonathanhefner · 2026-02-20T22:38:35Z

Docstring code examples in src/mcp/ were previously raw text — invisible to pyright and ruff, so type errors and style drift went unnoticed. This PR introduces a system for keeping those examples in standalone, type-checked companion files that are synced back into the docstrings automatically.

The old update_readme_snippets.py is replaced with sync_snippets.py, a superset that handles README.v2.md, docs/**/*.md, and src/**/*.py docstrings. It adds region extraction (# region / # endregion markers) so a single companion file can supply multiple snippets. For docstrings specifically,  markers derive the companion path automatically from the target file's location (src/mcp/foo.py → examples/snippets/docstrings/mcp/foo.py), avoiding line-length violations from embedding full paths.

42 code examples across the public API surface (MCPServer, Client, ClientSession, Context, ResponseRouter, task support, OAuth providers, etc.) are extracted into 19 companion files under examples/snippets/docstrings/mcp/, mirroring the source tree. Each example is wrapped in a named function with typed parameters, so pyright and ruff check them on every CI run — catching signature changes, renamed parameters, and moved imports at CI time rather than when a user copies a broken example.

Conventions for the snippet system (region naming, function-parameter pattern, # type: ignore prohibition, editing workflow) are documented in CLAUDE.md.

@Kludex, I was told you were thinking about moving examples/snippets/ to docs/snippets/. Would you prefer that docstring snippets live in docs/snippets/docstrings/? (Or anywhere else other than examples/snippets/docstrings/?)

Kludex · 2026-02-22T12:46:11Z

@Kludex, I was told you were thinking about moving examples/snippets/ to docs/snippets/. Would you prefer that docstring snippets live in docs/snippets/docstrings/? (Or anywhere else other than examples/snippets/docstrings/?)

I said something like: "the examples/snippets are horribly lengthy, and complex". But yeah, I think ideally we want to have what would be an example as part of the docs.

jonathanhefner · 2026-02-23T15:36:28Z

I said something like: "the examples/snippets are horribly lengthy, and complex".

Ah, I see. Agreed. I am working on getting more focused examples in place (e.g., without setup boilerplate).

But yeah, I think ideally we want to have what would be an example as part of the docs.

Agreed that they should be part of the docs, as in "embedded in the docs". Do you feel like the underlying code should also live in docs/? Or is it okay for the underlying code to live in examples/ and regions of it be injected into docs/*.md files?

The way we've done it for the TypeScript SDK is to have, e.g., a examples/client/src/clientGuide.examples.ts file that is linted / type checked / etc, and to inject regions of that file into docs/client.md, which is what the user sees.

I slightly lean toward the way it's done the TypeScript SDK, but I don't have a strong preference. Which do you prefer?

Kludex · 2026-02-23T15:42:21Z

Do you feel like the underlying code should also live in docs/? Or is it okay for the underlying code to live in examples/ and regions of it be injected into docs/*.md files?

It's okay to live elsewhere, but for the perfect setup, that code should be tested.

Any approach is fine. Making sure that code is tested is the requirement here.

jonathanhefner · 2026-02-23T15:49:00Z

Any approach is fine. Making sure that code is tested is the requirement here.

My plan was to ensure the code is type checked, linted, and formatted. Actual tests would add a lot of overhead to the process (setup code, mocks, assertions, etc.).

Are you okay with simply type checking? Do any of the existing examples have test coverage?

maxisbey · 2026-02-23T17:20:02Z

Any approach is fine. Making sure that code is tested is the requirement here.
My plan was to ensure the code is type checked, linted, and formatted. Actual tests would add a lot of overhead to the process (setup code, mocks, assertions, etc.).
Are you okay with simply type checking? Do any of the existing examples have test coverage?

Having the code tested would be nice, but that is a lot of overhead. Type checking and linting IMO is probably good enough at least to start with.

maxisbey · 2026-02-23T15:51:12Z

 ```
+<!-- /snippet-source -->

 _Full example: [examples/snippets/servers/basic_resource.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_resource.py)_


we should delete all these, or maybe have them as comments in the markdown. Not sure how helpful a link to the snippet actually is in the markdown since the code block contains the entire source anyway

Makes sense. The snippet-source comment already contains the path (e.g., ), so I've removed the links.

Kludex · 2026-02-23T20:56:38Z

If we are making the examples simpler, then it's a good opportunity to test them.

I mean, the perfect world would be to add tests for that, so examples are tested and they actually work - given that in the past we got a lot of PRs/issues with example issues.

Kludex · 2026-02-23T20:57:27Z

Otherwise, lint/type checker in them is fine.

jonathanhefner · 2026-02-24T20:55:05Z

Otherwise, lint/type checker in them is fine.

Since the examples in this PR are all in examples/snippets/docstrings/, they are all linted and type-checked. 👍

@Kludex @maxisbey Are there any further concerns? Is this okay to merge?

The new script is a superset of the old one. It continues to handle the existing `` markers in `README.v2.md`, and adds support for syncing code snippets into Python docstrings and markdown docs under `docs/`. New capabilities beyond the old script: - Region extraction from example files using `# region` / `# endregion` markers, so a single example file can provide multiple snippets - All source paths resolve relative to the repository root - Scans `src/**/*.py` and `docs/**/*.md` in addition to the README - Caches file contents and extracted regions for efficiency The marker format uses HTML comments (`` / ``), which are invisible when rendered by `mkdocstrings` and do not interfere with `pymdownx.superfences` code fence parsing.

Add support for `` markers that omit the companion file path. The path is derived from the target file's location using the mapping `src/X` → `examples/snippets/docstrings/X`. This eliminates line-length violations on marker lines in docstrings, since the full companion path no longer needs to be embedded in every marker. The full-path form continues to work for non-`src/` targets like markdown files.

Move inline code examples from docstrings in `src/mcp/` into standalone companion files at `examples/snippets/docstrings/mcp/`, mirroring the source tree structure. The `scripts/sync_snippets.py` script keeps the docstring content in sync with the companion files via `` markers. This ensures all docstring examples are checked by pyright and ruff, catching type errors and style drift that would otherwise go unnoticed in raw docstring text. The pattern follows the TypeScript SDK's approach of one companion file per source file, with each example in a named function whose parameters supply typed context. 19 companion files cover 42 code examples across the public API surface: `MCPServer`, `Client`, `ClientSession`, `Context`, `ResponseRouter`, `ServerTaskContext`, `ExperimentalTaskHandlers`, `ClientCredentialsOAuthProvider`, `PrivateKeyJWTOAuthProvider`, `SignedJWTParameters`, and others. All source markers use path-less form (`#RegionName`) — the companion path is derived automatically from the target file location. Region names follow `ClassName_methodName_variant` without abbreviation. Pyright execution environment for the companion files suppresses only "unused artifact" diagnostics inherent to example code (`reportUnusedFunction`, `reportUnusedVariable`, `reportAbstractUsage`, `reportUnusedClass`, `reportPrivateUsage`). All actual type-checking rules remain enabled.

Add a "Docstring Code Examples" section covering the companion file system: directory layout, `` markers, `ClassName_methodName_variant` naming, the function-parameter pattern for typed dependencies, and the prohibition on type-suppression comments inside regions.

`sync_snippets.py` also syncs snippet-source markers in `docs/**/*.md` and `README.v2.md`, not just `src/` docstrings. Add a short section after "Docstring Code Examples" noting that these files use explicit paths (path-less `#Region` markers are only supported in `src/` files).

The previous documentation had two flat sections where the docstring section contained all the detail and the markdown section referred to it vaguely. Reorganize into a `## Code Snippet System` intro covering shared concepts (marker format, region extraction, naming conventions, function wrappers, typed params, `# type: ignore` prohibition, pyright workflow) with `### Markdown Code Examples` and `### Docstring Code Examples` subsections covering only what is unique to each target type.

The links to snippet source files are redundant since the code blocks already contain the entire source. Removes all 33 occurrences.

jonathanhefner · 2026-02-20T22:38:35Z

Docstring code examples in src/mcp/ were previously raw text — invisible to pyright and ruff, so type errors and style drift went unnoticed. This PR introduces a system for keeping those examples in standalone, type-checked companion files that are synced back into the docstrings automatically.

The old update_readme_snippets.py is replaced with sync_snippets.py, a superset that handles README.v2.md, docs/**/*.md, and src/**/*.py docstrings. It adds region extraction (# region / # endregion markers) so a single companion file can supply multiple snippets. For docstrings specifically,  markers derive the companion path automatically from the target file's location (src/mcp/foo.py → examples/snippets/docstrings/mcp/foo.py), avoiding line-length violations from embedding full paths.

42 code examples across the public API surface (MCPServer, Client, ClientSession, Context, ResponseRouter, task support, OAuth providers, etc.) are extracted into 19 companion files under examples/snippets/docstrings/mcp/, mirroring the source tree. Each example is wrapped in a named function with typed parameters, so pyright and ruff check them on every CI run — catching signature changes, renamed parameters, and moved imports at CI time rather than when a user copies a broken example.

Conventions for the snippet system (region naming, function-parameter pattern, # type: ignore prohibition, editing workflow) are documented in CLAUDE.md.

@Kludex, I was told you were thinking about moving examples/snippets/ to docs/snippets/. Would you prefer that docstring snippets live in docs/snippets/docstrings/? (Or anywhere else other than examples/snippets/docstrings/?)

Kludex · 2026-02-22T12:46:11Z

@Kludex, I was told you were thinking about moving examples/snippets/ to docs/snippets/. Would you prefer that docstring snippets live in docs/snippets/docstrings/? (Or anywhere else other than examples/snippets/docstrings/?)

I said something like: "the examples/snippets are horribly lengthy, and complex". But yeah, I think ideally we want to have what would be an example as part of the docs.

jonathanhefner · 2026-02-23T15:36:28Z

I said something like: "the examples/snippets are horribly lengthy, and complex".

Ah, I see. Agreed. I am working on getting more focused examples in place (e.g., without setup boilerplate).

But yeah, I think ideally we want to have what would be an example as part of the docs.

Agreed that they should be part of the docs, as in "embedded in the docs". Do you feel like the underlying code should also live in docs/? Or is it okay for the underlying code to live in examples/ and regions of it be injected into docs/*.md files?

The way we've done it for the TypeScript SDK is to have, e.g., a examples/client/src/clientGuide.examples.ts file that is linted / type checked / etc, and to inject regions of that file into docs/client.md, which is what the user sees.

I slightly lean toward the way it's done the TypeScript SDK, but I don't have a strong preference. Which do you prefer?

Kludex · 2026-02-23T15:42:21Z

Do you feel like the underlying code should also live in docs/? Or is it okay for the underlying code to live in examples/ and regions of it be injected into docs/*.md files?

It's okay to live elsewhere, but for the perfect setup, that code should be tested.

Any approach is fine. Making sure that code is tested is the requirement here.

jonathanhefner · 2026-02-23T15:49:00Z

Any approach is fine. Making sure that code is tested is the requirement here.

My plan was to ensure the code is type checked, linted, and formatted. Actual tests would add a lot of overhead to the process (setup code, mocks, assertions, etc.).

Are you okay with simply type checking? Do any of the existing examples have test coverage?

maxisbey · 2026-02-23T17:20:02Z

Any approach is fine. Making sure that code is tested is the requirement here.
My plan was to ensure the code is type checked, linted, and formatted. Actual tests would add a lot of overhead to the process (setup code, mocks, assertions, etc.).
Are you okay with simply type checking? Do any of the existing examples have test coverage?

Having the code tested would be nice, but that is a lot of overhead. Type checking and linting IMO is probably good enough at least to start with.

maxisbey · 2026-02-23T15:51:12Z

 ```
+<!-- /snippet-source -->

 _Full example: [examples/snippets/servers/basic_resource.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_resource.py)_


we should delete all these, or maybe have them as comments in the markdown. Not sure how helpful a link to the snippet actually is in the markdown since the code block contains the entire source anyway

Makes sense. The snippet-source comment already contains the path (e.g., ), so I've removed the links.

Kludex · 2026-02-23T20:56:38Z

If we are making the examples simpler, then it's a good opportunity to test them.

I mean, the perfect world would be to add tests for that, so examples are tested and they actually work - given that in the past we got a lot of PRs/issues with example issues.

Kludex · 2026-02-23T20:57:27Z

Otherwise, lint/type checker in them is fine.

jonathanhefner · 2026-02-24T20:55:05Z