Reorganize docs around provider architecture#2723
Conversation
Adds a new Providers section documenting FastMCP v3's unified component sourcing model: LocalProvider, FastMCPProvider, ProxyProvider, and TransformingProvider. - New docs: overview, local, mounting, namespacing, proxy, custom - Absorbs composition.mdx and proxy.mdx into providers section - Updates navigation with Components before Providers - Adds v3 breaking changes to upgrade guide
marvin-context-protocol
Bot
added
documentation
|
Warning Rate limit exceeded@jlowin has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 15 minutes and 7 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (6)
WalkthroughThis pull request reorganizes documentation to reflect the new v3.0.0 provider architecture. It removes legacy server composition guidance, relocates proxy documentation under a new providers section, and introduces dedicated pages for LocalProvider, ProxyProvider, TransformingProvider, and custom providers. The Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/servers/middleware.mdx (1)
461-461: Update parameter name to match v3.0.0 API.The
mount()method parameter was renamed fromprefixtonamespacein v3.0.0. Update this example to use the correct parameter name.🔎 Proposed fix
-parent.mount(child, prefix="child") +parent.mount(child, namespace="child")
🧹 Nitpick comments (3)
docs/servers/providers/custom.mdx (2)
120-130: UseCallabletype fromtypingmodule.The type hint
callable(lowercase) is not a valid generic type annotation. UseCallablefrom thetypingmodule instead.Suggested fix
class DictProvider(Provider): - def __init__(self, tools: dict[str, callable]): + def __init__(self, tools: dict[str, Callable]): super().__init__() self._tools = [ Tool.from_function(fn, name=name) for name, fn in tools.items() ]Also add the import at the top of the code block:
from typing import Callable
196-206: Add return type annotation for consistency.The
lifespanmethod here is missing the return type annotation, while the earlier example (line 163) correctly includesAsyncIterator[None]. For consistency and completeness, add the type annotation.Suggested fix
@asynccontextmanager - async def lifespan(self): + async def lifespan(self) -> AsyncIterator[None]: self.client = httpx.AsyncClient(And ensure the import is present:
from collections.abc import AsyncIteratordocs/servers/providers/overview.mdx (1)
19-21: Minor phrasing repetition.The sentence uses "want to" twice in close proximity. Consider varying the phrasing for better readability.
Suggested fix
-Providers become important when your components come from multiple sources: another FastMCP server you want to include, a remote MCP server you want to proxy, or a database where tools are defined dynamically. Each source gets its own provider, and FastMCP queries them all seamlessly. +Providers become important when your components come from multiple sources: another FastMCP server you want to include, a remote MCP server to proxy, or a database where tools are defined dynamically. Each source gets its own provider, and FastMCP queries them all seamlessly.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (19)
docs/development/upgrade-guide.mdxdocs/docs.jsondocs/integrations/fastapi.mdxdocs/integrations/openapi.mdxdocs/patterns/tool-transformation.mdxdocs/servers/composition.mdxdocs/servers/middleware.mdxdocs/servers/prompts.mdxdocs/servers/providers/custom.mdxdocs/servers/providers/local.mdxdocs/servers/providers/mounting.mdxdocs/servers/providers/namespacing.mdxdocs/servers/providers/overview.mdxdocs/servers/providers/proxy.mdxdocs/servers/proxy.mdxdocs/servers/resources.mdxdocs/servers/server.mdxdocs/servers/tools.mdxdocs/snippets/version-badge.mdx
💤 Files with no reviewable changes (2)
- docs/servers/proxy.mdx
- docs/servers/composition.mdx
🧰 Additional context used
📓 Path-based instructions (1)
docs/**/*.mdx
📄 CodeRabbit inference engine (docs/.cursor/rules/mintlify.mdc)
docs/**/*.mdx: Use clear, direct language appropriate for technical audiences
Write in second person ('you') for instructions and procedures in MDX documentation
Use active voice over passive voice in MDX technical documentation
Employ present tense for current states and future tense for outcomes in MDX documentation
Maintain consistent terminology throughout all MDX documentation
Keep sentences concise while providing necessary context in MDX documentation
Use parallel structure in lists, headings, and procedures in MDX documentation
Lead with the most important information using inverted pyramid structure in MDX documentation
Use progressive disclosure in MDX documentation: present basic concepts before advanced ones
Break complex procedures into numbered steps in MDX documentation
Include prerequisites and context before instructions in MDX documentation
Provide expected outcomes for each major step in MDX documentation
End sections with next steps or related information in MDX documentation
Use descriptive, keyword-rich headings for navigation and SEO in MDX documentation
Focus on user goals and outcomes rather than system features in MDX documentation
Anticipate common questions and address them proactively in MDX documentation
Include troubleshooting for likely failure points in MDX documentation
Provide multiple pathways (beginner vs advanced) but offer an opinionated path to avoid overwhelming users in MDX documentation
Always include complete, runnable code examples that users can copy and execute in MDX documentation
Show proper error handling and edge case management in MDX code examples
Use realistic data instead of placeholder values in MDX code examples
Include expected outputs and results for verification in MDX code examples
Test all code examples thoroughly before publishing in MDX documentation
Specify language and include filename when relevant in MDX code examples
Add explanatory comments for complex logic in MDX code examples
Document all API...
Files:
docs/integrations/fastapi.mdxdocs/servers/middleware.mdxdocs/servers/providers/mounting.mdxdocs/development/upgrade-guide.mdxdocs/patterns/tool-transformation.mdxdocs/servers/providers/overview.mdxdocs/servers/providers/custom.mdxdocs/snippets/version-badge.mdxdocs/servers/providers/namespacing.mdxdocs/servers/providers/local.mdxdocs/integrations/openapi.mdxdocs/servers/providers/proxy.mdxdocs/servers/server.mdxdocs/servers/prompts.mdxdocs/servers/resources.mdxdocs/servers/tools.mdx
🧠 Learnings (4)
📚 Learning: 2025-12-21T21:37:55.031Z
Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-21T21:37:55.031Z
Learning: Applies to src/fastmcp/__init__.py : All module exports should be intentional - only re-export to `fastmcp.*` for fundamental types like `FastMCP` and `Client`, prefer users importing from specific submodules for specialized features
Applied to files:
docs/integrations/fastapi.mdx
📚 Learning: 2025-11-26T21:52:08.947Z
Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-11-26T21:52:08.947Z
Learning: Applies to docs/**/*.mdx : Validate Mintlify component syntax with all required properties in MDX documentation
Applied to files:
docs/snippets/version-badge.mdx
📚 Learning: 2025-11-03T17:36:13.363Z
Learnt from: jlowin
Repo: jlowin/fastmcp PR: 2355
File: docs/clients/client.mdx:226-246
Timestamp: 2025-11-03T17:36:13.363Z
Learning: In FastMCP documentation, prefer showing the happy path in onboarding examples without over-explaining edge cases or adding defensive checks, as this reduces cognitive burden for new users learning the API.
Applied to files:
docs/integrations/openapi.mdx
📚 Learning: 2025-11-26T21:52:08.947Z
Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-11-26T21:52:08.947Z
Learning: Applies to docs/**/*.mdx : Add appropriate warnings for destructive or security-sensitive actions in MDX documentation
Applied to files:
docs/servers/resources.mdxdocs/servers/tools.mdx
🪛 LanguageTool
docs/servers/providers/mounting.mdx
[grammar] ~189-~189: Ensure spelling is correct
Context: ...P-based mounted servers (300-400ms vs 1-2ms for local tools) - Mounted servers with...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/servers/providers/overview.mdx
[style] ~20-~20: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ant to include, a remote MCP server you want to proxy, or a database where tools are de...
(REP_WANT_TO_VB)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Run tests: Python 3.13 on ubuntu-latest
- GitHub Check: Run tests: Python 3.10 on ubuntu-latest
- GitHub Check: Run tests: Python 3.10 on windows-latest
- GitHub Check: Run tests with lowest-direct dependencies
🔇 Additional comments (14)
docs/development/upgrade-guide.mdx (2)
13-22: LGTM!The new Provider Architecture section clearly explains the v3 provider types and links to comprehensive documentation. The migration guidance is well-structured.
24-36: LGTM!Clear before/after examples for the
prefix→namespaceparameter rename.docs/servers/providers/local.mdx (2)
105-148: LGTM!The visibility control section provides comprehensive coverage of the new server-level enable/disable API with clear examples for keys, tags, and allowlist mode.
187-214: LGTM!The standalone LocalProvider section demonstrates a useful pattern for sharing components across servers with practical use cases.
docs/servers/providers/overview.mdx (1)
32-44: LGTM!The built-in providers table is clear and concise, showing what each provider does and how to use it.
docs/servers/providers/mounting.mdx (1)
217-239: LGTM!The conflict resolution section clearly explains the precedence behavior with a concrete example.
docs/servers/resources.mdx (2)
105-108: LGTM!Clear deprecation notice directing users to the new server-level visibility controls.
195-223: LGTM!The visibility control section properly documents the new server-level API with clear examples using keys and tags, and correctly links to the Local Provider documentation for the complete API reference.
docs/servers/tools.mdx (1)
80-83: LGTM!Clear deprecation notice consistent with the resources documentation.
docs/servers/providers/proxy.mdx (2)
35-59: LGTM!The Quick Start section provides a clear, minimal example with version badge and explains the key benefits.
92-127: LGTM!The session isolation section clearly explains the default behavior with good warning about shared session risks in concurrent scenarios.
docs/docs.json (3)
94-128: Well-structured provider section.The reorganization correctly:
- Renames "Core Components" to "Components" for brevity
- Introduces the "Providers" group with all six documented provider types (overview, local, mounting, namespacing, proxy, custom)
- Moves
servers/proxyfrom Features to the new Providers section- Maintains the navigation order with Components before Providers as specified in the PR objectives
543-559: Comprehensive redirect coverage for moved content.The redirects properly handle both legacy paths:
/patterns/proxyand/servers/proxy→/servers/providers/proxy/patterns/compositionand/servers/composition→/servers/providers/mountingThis ensures existing bookmarks and external links continue to work after the reorganization.
106-113: All provider documentation files exist and are correctly referenced in docs.json.
| "group": "fastmcp.utilities", | ||
| "pages": [ | ||
| "python-sdk/fastmcp-utilities-__init__", | ||
| "python-sdk/fastmcp-utilities-async_utils", |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the new async_utils documentation file exists
fd -t f "fastmcp-utilities-async_utils" --extension mdxRepository: jlowin/fastmcp
Length of output: 40
🏁 Script executed:
#!/bin/bash
# Broader search for async_utils files
echo "=== Searching for any async_utils files ==="
fd "async_utils"
# Check the directory structure for python-sdk docs
echo -e "\n=== Python SDK documentation files ==="
fd -t f "python-sdk" | head -20
# Look at examples from docs.json to see naming pattern
echo -e "\n=== Sample python-sdk entries from docs.json ==="
grep -o '"python-sdk/[^"]*"' docs/docs.json | head -10Repository: jlowin/fastmcp
Length of output: 618
🏁 Script executed:
#!/bin/bash
# Find all .mdx files in the docs directory
echo "=== MDX files in docs directory ==="
fd -t f "\.mdx" docs/ | head -20
# Check if there's a generated directory or specific SDK docs location
echo -e "\n=== Documentation directory structure ==="
ls -la docs/ 2>/dev/null | head -20
# Look for files matching the pattern of entries in docs.json
echo -e "\n=== Checking for fastmcp-utilities related docs ==="
find docs -type f \( -name "*utilities*" -o -name "*async*" \) 2>/dev/nullRepository: jlowin/fastmcp
Length of output: 3664
🏁 Script executed:
#!/bin/bash
# Get complete list of python-sdk files
echo "=== All files in docs/python-sdk ==="
ls -1 docs/python-sdk/ | grep "^fastmcp-utilities"
# Check if async_utils file exists
echo -e "\n=== Checking for async_utils specifically ==="
ls -1 docs/python-sdk/fastmcp-utilities-async_utils* 2>&1 || echo "File not found"
# Count total utilities files
echo -e "\n=== Total utilities files ==="
ls -1 docs/python-sdk/ | grep "^fastmcp-utilities" | wc -lRepository: jlowin/fastmcp
Length of output: 1549
Create the missing documentation file for the async_utils SDK reference page.
The navigation entry python-sdk/fastmcp-utilities-async_utils was added to docs.json at line 477, but the corresponding documentation file docs/python-sdk/fastmcp-utilities-async_utils.mdx does not exist. This creates a broken navigation link. The source module exists at src/fastmcp/utilities/async_utils.py, so generate the documentation file to match the other 31 SDK reference pages in the utilities module.
Test Failure AnalysisSummary: Integration test hit GitHub Copilot API rate limits (429 Too Many Requests), causing a 30s timeout. Root Cause: The test makes requests to which enforces rate limiting. The test timed out waiting for a response, and during teardown, the actual 429 error was revealed in the asyncio exception handler. Suggested Solution: This is an external API rate limit issue unrelated to the documentation changes in this PR. Since the PR is already merged and the changes are documentation-only, no code action is needed. However, for future runs:
The failure is transient and not caused by code changes in this PR. Detailed AnalysisThe test failure occurred during : The test successfully called the tool but the GitHub Copilot API returned a 429 rate limit error. Because this happened during the async context manager exit ( Related Files
|
Test Failure AnalysisSummary: Integration test Root Cause: The test makes requests to Suggested Solution: This is an external API rate limit issue unrelated to the documentation changes in this PR. Since the PR is already merged and the changes are documentation-only, no code action is needed. However, for future runs:
The failure is transient and not caused by code changes in this PR. Detailed AnalysisThe test failure occurred during The test successfully called the tool but the GitHub Copilot API returned a 429 rate limit error. Because this happened during the async context manager exit ( Related Files
|
1 participant
FastMCP v3's provider abstraction unifies how components are sourced—decorators, composition, and proxying are all provider patterns. This reorganization makes that architecture visible in the documentation structure.
New Providers section with six docs:
enable()/disable()FastMCPProviderTransformingProviderProxyProviderThe navigation now places Components before Providers (most users use decorators without needing provider knowledge). Composition and proxy docs are absorbed into the new section with redirects.
Also adds v3 breaking changes to the upgrade guide covering the provider architecture,
mount(namespace=...), and server-level visibility control.Closes #2691