Embed code snippets for README from executable examples #1055
Conversation
README.md
Outdated
| @@ -419,21 +419,27 @@ def create_thumbnail(image_path: str) -> Image: | |||
|
|
|||
| The Context object gives your tools and resources access to MCP capabilities: | |||
|
|
|||
| <!-- snippet-source examples/servers/everything/src/everything/server.py#L43-L58 --> | |||
There was a problem hiding this comment.
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
| @@ -90,7 +90,7 @@ def get_weather_alerts(region: str) -> list[WeatherAlert]: | |||
| WeatherAlert( | |||
| severity="high", | |||
| title="Heat Wave Warning", | |||
| description="Temperatures expected to exceed 40°C", | |||
| description="Temperatures expected to exceed 40 degrees", | |||
There was a problem hiding this comment.
nit: revert to celsius to avoid frowns from US users?
| # 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} |
There was a problem hiding this comment.
Might want to indent the code here too {indent}{code.replace('\n', f'\n{indent}')} (markdown should remove it)
| from typing import Literal | ||
|
|
||
| # Available snippet modules | ||
| SNIPPET_MODULES = [ |
There was a problem hiding this comment.
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)
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.
scripts/update_readme_snippets.pythat extracts code from example files into README<!-- snippet-source path/to/file.py -->markers to identify updatable sections#L10-L20)examples/snippets/with single-feature examples:basic_tool.py- Simple tool examplebasic_resource.py- Resource handlingbasic_prompt.py- Prompt creationtool_progress.py- Progress reportingsampling.py- LLM samplingelicitation.py- User interactioncompletion.py- Argument completionnotifications.py- Logging and notificationsmake_everything_fastmcp()function from tests into a standalone example atexamples/servers/everything/readme-snippetsjob to.github/workflows/shared.ymlto verify snippets are current--checkmode to fail if snippets are outdated