Embed code snippets for README from executable examples by ihrpr · Pull Request #1055 · modelcontextprotocol/python-sdk · GitHub

We already had an integration test that verifies all current functionality works as expected, so we can use it as both a server example and as the source for README snippets. These snippets will be automatically updated and verified through CI checks. In the future, we'll also add an everything client example and include it in both the README and integration tests.

Automated README Snippets

Added scripts/update_readme_snippets.py that extracts code from example files into README
Uses  markers to identify updatable sections
Automatically adds links to full example files on GitHub with line highlighting
Supports both full-file and line-range extraction (e.g., #L10-L20)

New Example Structure

Created examples/snippets/ with single-feature examples:
- basic_tool.py - Simple tool example
- basic_resource.py - Resource handling
- basic_prompt.py - Prompt creation
- tool_progress.py - Progress reporting
- sampling.py - LLM sampling
- elicitation.py - User interaction
- completion.py - Argument completion
- notifications.py - Logging and notifications
Each example is self-contained

Everything Server Extraction

Moved the comprehensive make_everything_fastmcp() function from tests into a standalone example at examples/servers/everything/
Everything server remains available for testing all MCP features in one place

CI Integration

Added readme-snippets job to .github/workflows/shared.yml to verify snippets are current
Added pre-commit hook that checks snippet freshness on relevant file changes
Both use --check mode to fail if snippets are outdated

this is only one example for this PR, when we agree on the process, will replace the rest of the Server examples (and later client) in README as separate PRs

Neat!!

nit: revert to celsius to avoid frowns from US users?

move up w/ the others?

Might want to indent the code here too {indent}{code.replace('\n', f'\n{indent}')} (markdown should remove it)

Given you're not using the #line syntax, i wonder if you could just get the list of snippets on the fly from readme parser, avoid checking in these generated files / evaluate them on the fly (maybe create a temp directory, add it to the PYTHONPATH programmatically and load adhoc $tmp/snippet$i.py modules?)

(would also remove the need for a file name)

As mentioned on Discord, I don't think this will provide a good experience for readers.

We should have a setup in place where every example is an MRE in the documentation.

For inspiration, FastAPI and PydanticAI (popular python projects) have already this kind of setup in their repositories - although their setup is for the MkDocs, not for the README.

We should have a setup in place where every example is an MRE in the documentation.

@Kludex, the examples are now all standalone files, what am I missing?

LGTM

everything server for REAME snippets

e7d79e0

github-advanced-security AI found potential problems Jun 29, 2025

View reviewed changes

Comment thread .github/workflows/shared.yml Fixed

ihrpr commented Jun 29, 2025

View reviewed changes

ihrpr added 9 commits June 29, 2025 22:48

simplitfy readme for everything server

f02996c

more comment simplifications

1bbacf7

security suggestions

da0c986

CI fixes

6e5b666

remove readme from lint

d67ad08

update contributing

c4486f8

120 for docs as well...

3a70805

use ruff in snippets tests

3203841

Merge branch 'main' into ihrpr/readme-from-examples

61ec764

dsp-ant self-requested a review June 30, 2025 09:11

ihrpr added 6 commits July 1, 2025 14:26

use small servers

73676a5

add snipets to workspace

a9e8122

ruff

16ac8eb

update server names in tests

6c8011b

remove characters

b318929

replace chars

7457804

ihrpr changed the title RFC: Everything server as source of truth for integration tests and README snippets Embed code snippets for README from actual executable examples Jul 1, 2025

ihrpr changed the title Embed code snippets for README from actual executable examples Embed code snippets for README from executable examples Jul 1, 2025

ihrpr added 2 commits July 2, 2025 11:08

remove everything server

d1604b1

update docs

ddb2440

ihrpr marked this pull request as ready for review July 2, 2025 10:11

ihrpr added 2 commits July 2, 2025 11:26

simplify init

395f60c

ruff

982b115

ochafik reviewed Jul 3, 2025

View reviewed changes

Kludex requested changes Jul 4, 2025

View reviewed changes

ihrpr requested a review from Kludex July 4, 2025 07:52

ihrpr added 7 commits July 4, 2025 11:02

clean up after review comments

78ff6c9

remove line extractoin

81b423e

indent

d42be5a

Merge branch 'main' into ihrpr/readme-from-examples

4f326bd

ruff

b1a0913

readme after ruff

926c5f8

tests

478ce05

Kludex approved these changes Jul 4, 2025

View reviewed changes

ihrpr merged commit adf3271 into main Jul 4, 2025

ihrpr deleted the ihrpr/readme-from-examples branch July 4, 2025 16:25

                               severity="high",
                               title="Heat Wave Warning",
-                              description="Temperatures expected to exceed 40°C",
+                              description="Temperatures expected to exceed 40 degrees",

+                      # In check mode, only check if code has changed
+                      if check_mode:
+                          # Extract existing code from the match
+                          existing_content = match.group(5)

+                      # Build the replacement block
+                      replacement = f"""{indent}<!-- snippet-source {file_path}{line_ref} -->
+              {indent}```python
+              {code}

Embed code snippets for README from executable examples by ihrpr · Pull Request #1055 · modelcontextprotocol/python-sdk · GitHub

Uh oh!

Embed code snippets for README from executable examples - #1055

Embed code snippets for README from executable examples#1055
ihrpr merged 27 commits into
mainfrom
ihrpr/readme-from-examples

ihrpr commented Jun 29, 2025 •
edited
Loading

Uh oh!

Uh oh!

Uh oh!

ihrpr Jun 29, 2025

Uh oh!

ochafik left a comment

Uh oh!

ochafik Jul 3, 2025

Uh oh!

ochafik Jul 3, 2025

Uh oh!

ochafik Jul 3, 2025

Uh oh!

ochafik Jul 3, 2025

Uh oh!

Kludex left a comment

Uh oh!

ihrpr commented Jul 4, 2025

Uh oh!

Kludex left a comment •
edited
Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		The Context object gives your tools and resources access to MCP capabilities:

		<!-- snippet-source examples/servers/everything/src/everything/server.py#L43-L58 -->

+              from typing import Literal
+              # Available snippet modules
+              SNIPPET_MODULES = [

Embed code snippets for README from executable examples by ihrpr · Pull Request #1055 · modelcontextprotocol/python-sdk · GitHub

Uh oh!

Embed code snippets for README from executable examples - #1055

Embed code snippets for README from executable examples#1055ihrpr merged 27 commits intomainmodelcontextprotocol/python-sdk:mainfrom ihrpr/readme-from-examplesmodelcontextprotocol/python-sdk:ihrpr/readme-from-examplesCopy head branch name to clipboard

Conversation

ihrpr commented Jun 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ihrpr Jun 29, 2025

Choose a reason for hiding this comment

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

ochafik Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

ochafik Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

ochafik Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

ochafik Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

Kludex left a comment

Choose a reason for hiding this comment

Uh oh!

ihrpr commented Jul 4, 2025

Uh oh!

Kludex left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Embed code snippets for README from executable examples#1055
ihrpr merged 27 commits into
mainfrom
ihrpr/readme-from-examples

ihrpr commented Jun 29, 2025 •
edited
Loading

Kludex left a comment •
edited
Loading