Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Embed code snippets for README from executable examples #1055

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 20 commits into
base: main
Choose a base branch
from

Conversation

ihrpr
Copy link
Contributor

@ihrpr ihrpr commented Jun 29, 2025

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.

  1. Automated README Snippets
  • Added scripts/update_readme_snippets.py that extracts code from example files into README
  • Uses <!-- snippet-source path/to/file.py --> 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)
  1. 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
  1. 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
  1. 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
image

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 -->
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@dsp-ant dsp-ant self-requested a review June 30, 2025 09:11
@ihrpr 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 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 ihrpr marked this pull request as ready for review July 2, 2025 10:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant