iXTdZddlmZddlmZmZddlmZddlm Z ddl m Z m Z m Z ddlmZddlmZdd lmZdd lmZdd lmZdd lmZdd lmZddlmZddlmZm Z e rddl!m"Z"GddZ#y)aBase Provider class for dynamic MCP components. This module provides the `Provider` abstraction for providing tools, resources, and prompts dynamically at runtime. Example: ```python from fastmcp import FastMCP from fastmcp.server.providers import Provider from fastmcp.tools import Tool class DatabaseProvider(Provider): def __init__(self, db_url: str): super().__init__() self.db = Database(db_url) async def _list_tools(self) -> list[Tool]: rows = await self.db.fetch("SELECT * FROM tools") return [self._make_tool(row) for row in rows] async def _get_tool(self, name: str) -> Tool | None: row = await self.db.fetchone("SELECT * FROM tools WHERE name = ?", name) return self._make_tool(row) if row else None mcp = FastMCP("Server", providers=[DatabaseProvider(db_url)]) ``` ) annotations) AsyncIteratorSequence)asynccontextmanager)partial) TYPE_CHECKINGLiteralcast)Self)Prompt)Resource)ResourceTemplate) Visibility)Tool)gather)FastMCPComponent) VersionSpecversion_sort_key) TransformceZdZdZddZd dZed!dZd"dZd#dZ d$dZ d% d&d Z d'd Z d% d(d Z d)d Z d% d*d Zd+dZ d% d,dZd$dZ d% d&dZd'dZ d% d(dZd)dZ d% d*dZd+dZ d% d,dZd-dZed.dZddddddd d/dZdddddd d0dZy)1Providera"Base class for dynamic component providers. Subclass and override whichever methods you need. Default implementations return empty lists / None, so you only need to implement what your provider supports. Provider semantics: - Return `None` from `get_*` methods to indicate "I don't have it" (search continues) - Static components (registered via decorators) always take precedence over providers - Providers are queried in registration order; first non-None wins - Components execute themselves via run()/read()/render() - providers just source them Error handling: - `list_*` methods: Errors are logged and the provider returns empty (graceful degradation). This allows other providers to still contribute their components. cg|_yN) _transformsselfs m/Users/bowang/.openclaw/workspace/ChatDev/.venv/lib/python3.12/site-packages/fastmcp/server/providers/base.py__init__zProvider.__init__Es ,.c4|jjdS)Nz()) __class____name__rs r__repr__zProvider.__repr__Hs..))*"--rc,t|jS)z8All transforms applied to components from this provider.)listrrs r transformszProvider.transformsKsD$$%%rc:|jj|y)aAdd a transform to this provider. Transforms modify components (tools, resources, prompts) as they flow through the provider. They're applied in order - first added is innermost. Args: transform: The transform to add. Example: ```python from fastmcp.server.transforms import Namespace provider = MyProvider() provider.add_transform(Namespace("api")) # Tools become "api_toolname" ``` N)rappend)r transforms r add_transformzProvider.add_transformPs$  *rc ddlm}|||S)a}Return a new provider with this transform applied (immutable). Unlike add_transform() which mutates this provider, wrap_transform() returns a new provider that wraps this one. The original provider is unchanged. This is useful when you want to apply transforms without side effects, such as adding the same provider to multiple aggregators with different namespaces. Args: transform: The transform to apply. Returns: A new provider that wraps this one with the transform applied. Example: ```python from fastmcp.server.transforms import Namespace provider = MyProvider() namespaced = provider.wrap_transform(Namespace("api")) # provider is unchanged # namespaced returns tools as "api_toolname" ``` r)_WrappedProvider))fastmcp.server.providers.wrapped_providerr,)rr)r,s rwrap_transformzProvider.wrap_transformds8 Oi00rcK|jd{}|jD]}|j|d{}|S707 w)uList tools with all transforms applied. Applies transforms sequentially: base → transforms (in order). Each transform receives the result from the previous transform. Components may be marked as disabled but are NOT filtered here - filtering happens at the server level to allow session transforms to override. Returns: Transformed sequence of tools (including disabled ones). N) _list_toolsr& list_tools)rtoolsr)s rr1zProvider.list_toolssH&&((I#..u55E) )5A A'A A  A  A NcKddfd }|}jD]}t|j|}|||d{S7w)aGet tool by transformed name with all transforms applied. Note: This method does NOT filter disabled components. The Server (FastMCP) performs enabled filtering after all transforms complete, allowing session-level transforms to override provider-level disables. Args: name: The transformed tool name to look up. version: Optional version filter. If None, returns highest version. Returns: The tool if found (may be marked disabled), None if not found. NcDKj||d{S7wr) _get_toolnversionrs rbasezProvider.get_tool..bases733 33    call_nextr9r)r8strr9VersionSpec | Nonereturn Tool | None)r&rget_toolrnamer9r:chainr)s` rrCzProvider.get_toolsH" 4II..%@E)41111?A AA cK|jd{}|jD]}|j|d{}|S707 w)z}List resources with all transforms applied. Components may be marked as disabled but are NOT filtered here. N)_list_resourcesr&list_resources)r resourcesr)s rrJzProvider.list_resourcessI ..00 I'66yAAI)1Ar3cKddfd }|}jD]}t|j|}|||d{S7w)aGet resource by transformed URI with all transforms applied. Note: This method does NOT filter disabled components. The Server (FastMCP) performs enabled filtering after all transforms complete. Args: uri: The transformed resource URI to look up. version: Optional version filter. If None, returns highest version. Returns: The resource if found (may be marked disabled), None if not found. NcDKj||d{S7wr) _get_resourceur9rs rr:z#Provider.get_resource..bases ++Aw77 77r;r<r>r)rPr?r9r@rAResource | None)r&r get_resourcerurir9r:rFr)s` rrRzProvider.get_resourcesH  8II22eDE)30000rGcK|jd{}|jD]}|j|d{}|S707 w)zList resource templates with all transforms applied. Components may be marked as disabled but are NOT filtered here. N)_list_resource_templatesr&list_resource_templates)r templatesr)s rrWz Provider.list_resource_templatessI 7799 I'?? JJI):Jr3cK d dfd }|}jD]}t|j|}|||d{S7w)aGet resource template by transformed URI with all transforms applied. Note: This method does NOT filter disabled components. The Server (FastMCP) performs enabled filtering after all transforms complete. Args: uri: The transformed template URI to look up. version: Optional version filter. If None, returns highest version. Returns: The template if found (may be marked disabled), None if not found. NcDKj||d{S7wr)_get_resource_templaterOs rr:z,Provider.get_resource_template..bases"44Q@@ @@r;r<r>r)rPr?r9r@rAResourceTemplate | None)r&rget_resource_templaterSs` rr]zProvider.get_resource_templatesi"37 A A/ A $ A II;;uME)30000sAAA  AcK|jd{}|jD]}|j|d{}|S707 w)z{List prompts with all transforms applied. Components may be marked as disabled but are NOT filtered here. N) _list_promptsr& list_prompts)rpromptsr)s rr`zProvider.list_promptssH **,,I%227;;G)-;r3cKddfd }|}jD]}t|j|}|||d{S7w)aGet prompt by transformed name with all transforms applied. Note: This method does NOT filter disabled components. The Server (FastMCP) performs enabled filtering after all transforms complete. Args: name: The transformed prompt name to look up. version: Optional version filter. If None, returns highest version. Returns: The prompt if found (may be marked disabled), None if not found. NcDKj||d{S7wr) _get_promptr7s rr:z!Provider.get_prompt..bases ))!W55 55r;r<r>r)r8r?r9r@rA Prompt | None)r&r get_promptrDs` rrfzProvider.get_promptsH  6II00EBE)41111rGcKgSw)zReturn all available tools. Override to provide tools dynamically. Returns ALL versions of all tools. The server handles deduplication to show one tool per name. rs rr0zProvider._list_tools!  cK|jd{}|Dcgc]}|j|k(s|}}|r+|Dcgc] }|j|js|"}}|syt |t S7dcc}wcc}ww)aGet a specific tool by name. Default implementation filters _list_tools() and picks the highest version that matches the spec. Args: name: The tool name. version: Optional version filter. If None, returns highest version. If specified, returns highest version matching the spec. Returns: The Tool if found, or None to continue searching other providers. Nkey)r0rEmatchesr9maxr)rrEr9r2tmatchings rr6zProvider._get_tool)s| &&(($7u!$Au7 #+J8awqyy/I8HJ8!122 )7J6BA;BA=A=B B!B%B= BcKgSw)zReturn all available resources. Override to provide resources dynamically. Returns ALL versions of all resources. The server handles deduplication to show one resource per URI. rhrs rrIzProvider._list_resourcesArirjc$K|jd{}|Dcgc]}t|j|k(s|}}|r+|Dcgc] }|j|js|"}}|syt |t S7mcc}wcc}ww)aGet a specific resource by URI. Default implementation filters _list_resources() and returns highest version matching the spec. Args: uri: The resource URI. version: Optional version filter. If None, returns highest version. Returns: The Resource if found, or None to continue searching other providers. Nrl)rIr?rTrnr9ror)rrTr9rKrrqs rrNzProvider._get_resourceIs..00 (>y!CJ#,=Ay> #+J8awqyy/I8HJ8!122 1>Js7BBBBBB B *B .B BcKgSw)zReturn all available resource templates. Override to provide resource templates dynamically. Returns ALL versions. The server handles deduplication. rhrs rrVz!Provider._list_resource_templates`rirjcK|jd{}|Dcgc]}|j||}}|r+|Dcgc] }|j|js|"}}|syt|tS7fcc}wcc}ww)aGet a resource template that matches the given URI. Default implementation lists all templates, finds those whose pattern matches the URI, and returns the highest version matching the spec. Args: uri: The URI to match against templates. version: Optional version filter. If None, returns highest version. Returns: The ResourceTemplate if a matching one is found, or None to continue searching. Nrl)rVrnr9ror)rrTr9rXrprqs rr[zProvider._get_resource_templatehs7799 (Gy!AIIcN,FAyG #+J8awqyy/I8HJ8!122 :GJs6B A=B A?A?B  B#B'B ? B cKgSw)zReturn all available prompts. Override to provide prompts dynamically. Returns ALL versions of all prompts. The server handles deduplication to show one prompt per name. rhrs rr_zProvider._list_promptsrirjcK|jd{}|Dcgc]}|j|k(s|}}|r+|Dcgc] }|j|js|"}}|syt |t S7dcc}wcc}ww)a|Get a specific prompt by name. Default implementation filters _list_prompts() and picks the highest version matching the spec. Args: name: The prompt name. version: Optional version filter. If None, returns highest version. Returns: The Prompt if found, or None to continue searching other providers. Nrl)r_rErnr9ror)rrEr9raprqs rrdzProvider._get_prompts|**,,&9w!!&&D.Aw9 #+J8awqyy/I8HJ8!122 -9JrrcKt|j|j|j|j d{}t t t|d}t t t|d}t t t|d}t t t|d}|jD]f}|j|d{}|j|d{}|j|d{}|j|d{}hg||||Dcgc]}|j j#r| c}S777o7X7Acc}ww)afReturn components that should be registered as background tasks. Override to customize which components are task-eligible. Default calls list_* methods, applies provider transforms, and filters for components with task_config.mode != 'forbidden'. Used by the server during startup to register functions with Docket. Nr)rr0rIrVr_r rrr rr r&r1rJrWr` task_configsupports_tasks)rresultsr2rKrXrar)cs r get_taskszProvider.get_taskssq      "  ) ) +       Xd^WQZ0(+WQZ8 "23WQZ@ x'4I#..u55E'66yAAI'?? JJI%227;;G )    }}++-   ' 6AJ;  smA E0 E  BE0E#E05E%6E0E'E0'E)(E0:#E+E0#E0%E0'E0)E0+E0cKdyw)aUser-overridable lifespan for custom setup and teardown. Override this method to perform provider-specific initialization like opening database connections, setting up external resources, or other state management needed for the provider's lifetime. The lifespan scope matches the server's lifespan - code before yield runs at startup, code after yield runs at shutdown. Example: ```python @asynccontextmanager async def lifespan(self): # Setup self.db = await connect_database() try: yield finally: # Teardown await self.db.close() ``` Nrhrs rlifespanzProvider.lifespans 0 s F)nameskeysr9tags componentsonlyc |r&|jjtdd|jjtd||||r t|nd|r t|nd|S)aEnable components matching all specified criteria. Adds a visibility transform that marks matching components as enabled. Later transforms override earlier ones, so enable after disable makes the component enabled. With only=True, switches to allowlist mode - first disables everything, then enables matching components. Args: names: Component names or URIs to enable. keys: Component keys to enable (e.g., {"tool:my_tool@v1"}). version: Component version spec to enable (e.g., VersionSpec(eq="v1") or VersionSpec(gte="v2")). Unversioned components will not match. tags: Enable components with these tags. components: Component types to include (e.g., {"tool", "prompt"}). only: If True, ONLY enable matching components (allowlist mode). Returns: Self for method chaining. FT) match_allNrrr9rrrr(rset)rrrr9rrrs renablezProvider.enablesj@     # #Ju$E F  .83z?d"&SYD    r)rrr9rrc |jjtd||||r t|nd|r t|nd|S)aDisable components matching all specified criteria. Adds a visibility transform that marks matching components as disabled. Components can be re-enabled by calling enable() with matching criteria (the later transform wins). Args: names: Component names or URIs to disable. keys: Component keys to disable (e.g., {"tool:my_tool@v1"}). version: Component version spec to disable (e.g., VersionSpec(eq="v1") or VersionSpec(gte="v2")). Unversioned components will not match. tags: Disable components with these tags. components: Component types to include (e.g., {"tool", "prompt"}). Returns: Self for method chaining. FNrr)rrrr9rrs rdisablezProvider.disablesI6  .83z?d"&SYD    r)rANone)rAr?)rAzlist[Transform])r)rrAr)r)rrAr)rAzSequence[Tool]r)rEr?r9r@rArB)rAzSequence[Resource])rTr?r9r@rArQ)rAzSequence[ResourceTemplate])rTr?r9r@rAr\)rAzSequence[Prompt])rEr?r9r@rAre)rAzSequence[FastMCPComponent])rAzAsyncIterator[None])rset[str] | Nonerrr9r@rrr=set[Literal['tool', 'resource', 'template', 'prompt']] | NonerboolrAr ) rrrrr9r@rrrrrAr )r" __module__ __qualname____doc__rr#propertyr&r*r.r1rCrJrRrWr]r`rfr0r6rIrNrVr[r_rdrrrrrrhrrrr3s5"/.&&+(1H"8<22"42 247;11!31 127;11!31 168<22"42 2:8<33"43 307;33!33 3.7;33!33 3.8<33"43 36& X@"& $&* $// / $ /  /// /h"& $&* $%% % $ %  %% %rrN)$r __future__rcollections.abcrr contextlibr functoolsrtypingrr r typing_extensionsr fastmcp.prompts.promptr fastmcp.resources.resourcer fastmcp.resources.templater$fastmcp.server.transforms.visibilityrfastmcp.tools.toolrfastmcp.utilities.async_utilsrfastmcp.utilities.componentsrfastmcp.utilities.versionsrrfastmcp.server.transformsrrrhrrrsK8#3*//")/7;#09D3OOr