Fix broken code examples in docs by strawgate · Pull Request #3869 · PrefectHQ/fastmcp

strawgate · 2026-04-12T15:01:09Z

Summary

Fixes 8 out of 26 broken code examples found by automated doc validation (pytest-examples scan of 1,448 Python code blocks across docs/).

Error output tagged as Python (4 files):

integrations/anthropic.mdx and integrations/openai.mdx — API error responses were tagged as ```python instead of ```text. Users copy-pasting would get syntax errors.
Fixed in both v1 and v2 doc mirrors.

Unquoted URL (2 files):

integrations/descope.mdx — config_url=https://... missing quotes. Copy-paste produces SyntaxError.
Fixed in both v1 and v2.

Wrong class name casing (1 file):

clients/sampling.mdx — GoogleGenAISamplingHandler should be GoogleGenaiSamplingHandler (lowercase ai). Copy-paste produces ImportError.

Wrong import path (1 file):

development/v3-notes/v3-features.mdx — from fastmcp.client.sampling.handlers import GoogleGenaiSamplingHandler should be from fastmcp.client.sampling.handlers.google_genai import GoogleGenaiSamplingHandler.

Remaining known issues (18, need more investigation)

The remaining failures involve renamed/removed APIs (BearerTokenAuth, OAuthClientProvider, WSTransport, ListToolsNext) and wrong module paths that need example rewrites, not simple find-replace. Tracked separately.

🤖 Generated with Claude Code

- Tag error output blocks as ```text instead of ```python (anthropic, openai integration docs + v2 mirrors) - Quote unquoted URL in Descope config example (+ v2 mirror) - Fix GoogleGenAISamplingHandler → GoogleGenaiSamplingHandler casing in sampling docs - Fix import path: handlers.GoogleGenaiSamplingHandler → handlers.google_genai.GoogleGenaiSamplingHandler in v3-features 🤖 Generated with Claude Code Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

- BearerTokenAuth → StaticTokenVerifier in deployment/http.mdx - providers.oauth → server.auth import in authentication.mdx - ListToolsNext → updated list_tools API in v3-features.mdx - OAuthClientProvider → OAuth in v2/storage-backends.mdx - Add test="skip" for upgrade guides, contrib placeholders, f-string backticks 🤖 Generated with Claude Code Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

All 1444 examples now pass syntax and import checks. 🤖 Generated with Claude Code Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

marvin-context-protocol · 2026-04-12T16:04:30Z

Test Failure Analysis

Note: Updated from previous analysis — the root cause is the same (missing pytest-examples dependency), but the current CI failures are runtime ModuleNotFoundError during test collection across all test jobs, not just static analysis.

Summary: All CI jobs fail because tests/docs/test_doc_examples.py (added by this PR) imports pytest_examples, a package that is not in the project's dev dependencies, causing a ModuleNotFoundError at collection time.

Root Cause: The new test file imports from pytest_examples import CodeExample and from pytest_examples.find_examples import _extract_code_chunks, but pytest-examples is absent from the [dependency-groups] dev section of pyproject.toml. Every test job fails with:

ModuleNotFoundError: No module named 'pytest_examples'

Suggested Solution: Add pytest-examples to dev dependencies in pyproject.toml:

[dependency-groups]
dev = [
    ...
    "pytest-examples>=0.0.13",
    ...
]

Then run uv sync and commit the updated uv.lock.

Side note: The test also calls a private internal API (_extract_code_chunks from pytest_examples.find_examples). This may be fragile across versions — worth checking whether a public API exists, or pinning the version tightly.

Detailed Analysis

All 6 jobs failed with the same error:

ERROR tests/docs/test_doc_examples.py - ImportError while importing test module
Traceback:
  tests/docs/test_doc_examples.py:21: in <module>
    from pytest_examples import CodeExample
E   ModuleNotFoundError: No module named 'pytest_examples'

This error occurs at collection time, so it blocks every test run even though the 5301 other tests pass fine.

Current dev dependencies in pyproject.toml include: pytest, pytest-asyncio, pytest-cov, pytest-env, pytest-flakefinder, pytest-httpx, pytest-report, pytest-retry, pytest-timeout, pytest-xdist — but no pytest-examples.

Related Files

tests/docs/test_doc_examples.py — new file added by this PR; imports pytest_examples
pyproject.toml — needs pytest-examples added under [dependency-groups] dev
uv.lock — needs regeneration after adding the dependency

Posted by marvin (automated triage bot)

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cbd8f7c09d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-12T16:07:21Z

+from pathlib import Path
+from uuid import uuid4
+
+from pytest_examples import CodeExample


Add pytest-examples to dev dependencies

This test file introduces a hard dependency on pytest_examples, but the commit does not add pytest-examples to pyproject.toml (or lock it in uv.lock), so the required workflow (uv sync then uv run pytest) now fails during collection with ModuleNotFoundError before any tests run. Please declare this package in the dev dependency group (or gate the import) so CI and local test runs remain green.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-12T16:07:21Z

 auth_token = os.environ.get("MCP_AUTH_TOKEN")
 if auth_token:
-    auth = BearerTokenAuth(token=auth_token)
+    auth = StaticTokenVerifier(tokens={auth_token: {"sub": "admin"}})


Include required client_id in static token example

StaticTokenVerifier requires each token payload to include client_id; this example only sets {"sub": "admin"}. When a request is authenticated with this token, verify_token reads token_data["client_id"] and raises KeyError, so the documented production snippet fails at runtime instead of authenticating requests.

Useful? React with 👍 / 👎.

…mple, commit missed openapi fixes - Add pytest-examples to dev dependencies (fixes CI ModuleNotFoundError) - Include required client_id in StaticTokenVerifier token payload - Commit previously unstaged HTTPRoute import fixes in openapi.mdx 🤖 Generated with Claude Code Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

- fastmcp.server.openapi → fastmcp.server.providers.openapi - fastmcp.server.proxy → fastmcp.server.providers.proxy - fastmcp.server.apps → fastmcp.apps - Tag upgrade guide "Before" examples with test="skip" 🤖 Generated with Claude Code Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8e517746b7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-12T16:33:49Z

+from fastmcp.server.auth import OAuthProvider

 auth = MyOAuthProvider(


Align OAuth provider import with instantiated class

After this change, the snippet imports OAuthProvider but still instantiates MyOAuthProvider, so users who copy this example hit a NameError immediately when auth = MyOAuthProvider(...) runs. This block is presented as runnable Python (not skipped), so the import and constructor name need to be consistent (and the same mismatch is also present in the mirrored docs/v2/servers/auth/authentication.mdx section).

Useful? React with 👍 / 👎.

jlowin

Accurate mechanical fixes — wrong module paths, renamed classes, and retagged error-response code blocks. Good to see pytest-examples wiring in so these stay fixed.

marvin-context-protocol Bot added bug Something isn't working. Reports of errors, unexpected behavior, or broken functionality. documentation Updates to docs, examples, or guides. Primary change is documentation-related. labels Apr 12, 2026

strawgate and others added 2 commits April 12, 2026 11:01

Ratchet doc example baselines to zero

cbd8f7c

All 1444 examples now pass syntax and import checks. 🤖 Generated with Claude Code Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

chatgpt-codex-connector Bot reviewed Apr 12, 2026

View reviewed changes

strawgate and others added 2 commits April 12, 2026 11:22

chatgpt-codex-connector Bot reviewed Apr 12, 2026

View reviewed changes

jlowin approved these changes Apr 12, 2026

View reviewed changes

jlowin merged commit 9014539 into main Apr 12, 2026
11 of 12 checks passed

jlowin deleted the fix/doc-examples branch April 12, 2026 16:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix broken code examples in docs#3869

Fix broken code examples in docs#3869
jlowin merged 5 commits intomainfrom
fix/doc-examples

strawgate commented Apr 12, 2026

Uh oh!

marvin-context-protocol Bot commented Apr 12, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Apr 12, 2026

Uh oh!

chatgpt-codex-connector Bot Apr 12, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Apr 12, 2026

Uh oh!

jlowin left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		from fastmcp.server.auth import OAuthProvider

		auth = MyOAuthProvider(

Conversation

strawgate commented Apr 12, 2026

Summary

Remaining known issues (18, need more investigation)

Uh oh!

marvin-context-protocol Bot commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Failure Analysis

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

jlowin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marvin-context-protocol Bot commented Apr 12, 2026 •

edited

Loading