π The fast, Pythonic way to build MCP servers and clients.
Add type-prefixed keys for globally unique component identification (#2704)
Jeremiah Lowinaef1ccc02605
diff --git a/docs/development/upgrade-guide.mdx b/docs/development/upgrade-guide.mdxindex f72f1087f..96e3f10d4 100644--- a/docs/development/upgrade-guide.mdx+++ b/docs/development/upgrade-guide.mdx@@ -8,6 +8,29 @@ tag: NEWThis guide provides migration instructions for breaking changes and major updates when upgrading between FastMCP versions.+## v3.0.0++### Component Lookup Method Parameter Names++The server lookup methods now use semantic parameter names instead of generic `key`:++- `FastMCP.get_tool(name=...)` (was `key`)+- `FastMCP.get_resource(uri=...)` (was `key`)+- `FastMCP.get_resource_template(uri=...)` (was `key`)+- `FastMCP.get_prompt(name=...)` (was `key`)++If you were passing arguments positionally, no change is needed. If you were using keyword arguments:++<CodeGroup>+```python Before+tool = await mcp.get_tool(key="my_tool")+```++```python After+tool = await mcp.get_tool(name="my_tool")+```+</CodeGroup>+## v2.14.0### OpenAPI Parser Promotiondiff --git a/src/fastmcp/contrib/component_manager/component_service.py b/src/fastmcp/contrib/component_manager/component_service.pyindex e21c486e8..cd89fdbc2 100644--- a/src/fastmcp/contrib/component_manager/component_service.py+++ b/src/fastmcp/contrib/component_manager/component_service.py@@ -58,84 +58,82 @@ class ComponentService:def __init__(self, server: FastMCP):self._server = server- async def _enable_tool(self, key: str) -> Tool:+ async def _enable_tool(self, name: str) -> Tool:"""Handle 'enableTool' requests.Args:- key: The key of the tool to enable+ name: The name of the tool to enableReturns:The tool that was enabled"""- logger.debug("Enabling tool: %s", key)+ logger.debug("Enabling tool: %s", name)# 1. Check local tools first. The server will have already applied its filter.- if key in self._server._local_provider._tools:- tool: Tool = await self._server.get_tool(key)+ if Tool.make_key(name) in self._server._local_provider._components:+ tool: Tool = await self._server.get_tool(name)tool.enable()return tool# 2. Check mounted servers via FastMCPProvider/TransformingProviderfor provider in self._server._providers:- result = _get_mounted_server_and_key(provider, key, "tool")+ result = _get_mounted_server_and_key(provider, name, "tool")if result is not None:server, unprefixed = resultmounted_service = ComponentService(server)tool = await mounted_service._enable_tool(unprefixed)return tool- raise NotFoundError(f"Unknown tool: {key}")+ raise NotFoundError(f"Unknown tool: {name}")- async def _disable_tool(self, key: str) -> Tool:+ async def _disable_tool(self, name: str) -> Tool:"""Handle 'disableTool' requests.Args:- key: The key of the tool to disable+ name: The name of the tool to disableReturns:The tool that was disabled"""- logger.debug("Disable tool: %s", key)+ logger.debug("Disable tool: %s", name)# 1. Check local tools first. The server will have already applied its filter.- if key in self._server._local_provider._tools:- tool: Tool = await self._server.get_tool(key)+ if Tool.make_key(name) in self._server._local_provider._components:+ tool: Tool = await self._server.get_tool(name)tool.disable()return tool# 2. Check mounted servers via FastMCPProvider/TransformingProviderfor provider in self._server._providers:- result = _get_mounted_server_and_key(provider, key, "tool")+ result = _get_mounted_server_and_key(provider, name, "tool")if result is not None:server, unprefixed = resultmounted_service = ComponentService(server)tool = await mounted_service._disable_tool(unprefixed)return tool- raise NotFoundError(f"Unknown tool: {key}")+ raise NotFoundError(f"Unknown tool: {name}")- async def _enable_resource(self, key: str) -> Resource | ResourceTemplate:+ async def _enable_resource(self, uri: str) -> Resource | ResourceTemplate:"""Handle 'enableResource' requests.Args:- key: The key of the resource to enable+ uri: The URI of the resource to enableReturns:The resource that was enabled"""- logger.debug("Enabling resource: %s", key)-- # 1. Check local resources first. The server will have already applied its filter.- if key in self._server._local_provider._resources:- resource: Resource = await self._server.get_resource(key)- resource.enable()- return resource- if key in self._server._local_provider._templates:- template: ResourceTemplate = await self._server.get_resource_template(key)- template.enable()- return template+ logger.debug("Enabling resource: %s", uri)++ # 1. Check local components first (try resource, then template)+ component = self._server._local_provider._get_component(+ Resource.make_key(uri)+ ) or self._server._local_provider._get_component(ResourceTemplate.make_key(uri))+ if component is not None:+ component.enable()+ return component # type: ignore[return-value]# 2. Check mounted servers via FastMCPProvider/TransformingProviderfor provider in self._server._providers:- result = _get_mounted_server_and_key(provider, key, "resource")+ result = _get_mounted_server_and_key(provider, uri, "resource")if result is not None:server, unprefixed = resultmounted_service = ComponentService(server)@@ -143,32 +141,30 @@ class ComponentService:Resource | ResourceTemplate) = await mounted_service._enable_resource(unprefixed)return mounted_resource- raise NotFoundError(f"Unknown resource: {key}")+ raise NotFoundError(f"Unknown resource: {uri}")- async def _disable_resource(self, key: str) -> Resource | ResourceTemplate:+ async def _disable_resource(self, uri: str) -> Resource | ResourceTemplate:"""Handle 'disableResource' requests.Args:- key: The key of the resource to disable+ uri: The URI of the resource to disableReturns:The resource that was disabled"""- logger.debug("Disable resource: %s", key)-- # 1. Check local resources first. The server will have already applied its filter.- if key in self._server._local_provider._resources:- resource: Resource = await self._server.get_resource(key)- resource.disable()- return resource- if key in self._server._local_provider._templates:- template: ResourceTemplate = await self._server.get_resource_template(key)- template.disable()- return template+ logger.debug("Disable resource: %s", uri)++ # 1. Check local components first (try resource, then template)+ component = self._server._local_provider._get_component(+ Resource.make_key(uri)+ ) or self._server._local_provider._get_component(ResourceTemplate.make_key(uri))+ if component is not None:+ component.disable()+ return component # type: ignore[return-value]# 2. Check mounted servers via FastMCPProvider/TransformingProviderfor provider in self._server._providers:- result = _get_mounted_server_and_key(provider, key, "resource")+ result = _get_mounted_server_and_key(provider, uri, "resource")if result is not None:server, unprefixed = resultmounted_service = ComponentService(server)@@ -176,7 +172,7 @@ class ComponentService:Resource | ResourceTemplate) = await mounted_service._disable_resource(unprefixed)return mounted_resource- raise NotFoundError(f"Unknown resource: {key}")+ raise NotFoundError(f"Unknown resource: {uri}")async def _enable_prompt(self, key: str) -> Prompt:"""Handle 'enablePrompt' requests.@@ -190,7 +186,7 @@ class ComponentService:logger.debug("Enabling prompt: %s", key)# 1. Check local prompts first. The server will have already applied its filter.- if key in self._server._local_provider._prompts:+ if Prompt.make_key(key) in self._server._local_provider._components:prompt: Prompt = await self._server.get_prompt(key)prompt.enable()return prompt@@ -216,7 +212,7 @@ class ComponentService:"""# 1. Check local prompts first. The server will have already applied its filter.- if key in self._server._local_provider._prompts:+ if Prompt.make_key(key) in self._server._local_provider._components:prompt: Prompt = await self._server.get_prompt(key)prompt.disable()return promptdiff --git a/src/fastmcp/prompts/prompt.py b/src/fastmcp/prompts/prompt.pyindex d2369ae58..6fb439130 100644--- a/src/fastmcp/prompts/prompt.py+++ b/src/fastmcp/prompts/prompt.py@@ -6,7 +6,7 @@ import inspectimport jsonimport warningsfrom collections.abc import Awaitable, Callable, Sequence-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKING, Any, ClassVarimport pydantic_core@@ -118,6 +118,8 @@ class PromptResult(FastMCPBaseModel):class Prompt(FastMCPComponent):"""A prompt template that can be rendered with parameters."""+ KEY_PREFIX: ClassVar[str] = "prompt"+arguments: list[PromptArgument] | None = Field(default=None, description="Arguments that can be passed to the prompt")diff --git a/src/fastmcp/resources/resource.py b/src/fastmcp/resources/resource.pyindex 3155bdfd7..1e44f3ae4 100644--- a/src/fastmcp/resources/resource.py+++ b/src/fastmcp/resources/resource.py@@ -6,7 +6,7 @@ import base64import inspectimport warningsfrom collections.abc import Callable-from typing import TYPE_CHECKING, Annotated, Any+from typing import TYPE_CHECKING, Annotated, Any, ClassVarimport mcp.types@@ -137,6 +137,8 @@ class ResourceContent(pydantic.BaseModel):class Resource(FastMCPComponent):"""Base class for all resources."""+ KEY_PREFIX: ClassVar[str] = "resource"+model_config = ConfigDict(validate_default=True)uri: Annotated[AnyUrl, UrlConstraints(host_required=False)] = Field(@@ -300,8 +302,8 @@ class Resource(FastMCPComponent):@propertydef key(self) -> str:- """The lookup key for this resource. Returns str(uri)."""- return str(self.uri)+ """The globally unique lookup key for this resource."""+ return self.make_key(str(self.uri))def register_with_docket(self, docket: Docket) -> None:"""Register this resource with docket for background execution."""diff --git a/src/fastmcp/resources/template.py b/src/fastmcp/resources/template.pyindex 8de57c938..ca7596359 100644--- a/src/fastmcp/resources/template.py+++ b/src/fastmcp/resources/template.py@@ -5,7 +5,7 @@ from __future__ import annotationsimport inspectimport refrom collections.abc import Callable-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKING, Any, ClassVarfrom urllib.parse import parse_qs, unquoteimport mcp.types@@ -97,6 +97,8 @@ def match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None:class ResourceTemplate(FastMCPComponent):"""A template for dynamically creating resources."""+ KEY_PREFIX: ClassVar[str] = "template"+uri_template: str = Field(description="URI template with parameters (e.g. weather://{city}/current)")@@ -265,8 +267,8 @@ class ResourceTemplate(FastMCPComponent):@propertydef key(self) -> str:- """The lookup key for this template. Returns uri_template."""- return self.uri_template+ """The globally unique lookup key for this template."""+ return self.make_key(self.uri_template)def register_with_docket(self, docket: Docket) -> None:"""Register this template with docket for background execution."""diff --git a/src/fastmcp/server/providers/base.py b/src/fastmcp/server/providers/base.pyindex d6f7186e2..3c20f11f4 100644--- a/src/fastmcp/server/providers/base.py+++ b/src/fastmcp/server/providers/base.py@@ -30,27 +30,13 @@ from __future__ import annotationsfrom collections.abc import AsyncIterator, Sequencefrom contextlib import asynccontextmanager-from dataclasses import dataclassfrom typing import Literalfrom fastmcp.prompts.prompt import Promptfrom fastmcp.resources.resource import Resourcefrom fastmcp.resources.template import ResourceTemplatefrom fastmcp.tools.tool import Tool---@dataclass-class TaskComponents:- """Collection of components eligible for background task execution.-- Used by get_tasks() to return components for Docket registration.- Components must implement register_with_docket() and add_to_docket().- """-- tools: Sequence[Tool] = ()- resources: Sequence[Resource] = ()- templates: Sequence[ResourceTemplate] = ()- prompts: Sequence[Prompt] = ()+from fastmcp.utilities.components import FastMCPComponentclass Provider:@@ -239,11 +225,37 @@ class Provider:prompts = await self.list_prompts()return next((p for p in prompts if p.name == name), None)+ async def get_component(+ self, key: str+ ) -> Tool | Resource | ResourceTemplate | Prompt | None:+ """Get a component by its prefixed key.++ Args:+ key: The prefixed key (e.g., "tool:name", "resource:uri", "template:uri").++ Returns:+ The component if found, or None to continue searching other providers.+ """+ # Default implementation: iterate through all components and match by key+ for tool in await self.list_tools():+ if tool.key == key:+ return tool+ for resource in await self.list_resources():+ if resource.key == key:+ return resource+ for template in await self.list_resource_templates():+ if template.key == key:+ return template+ for prompt in await self.list_prompts():+ if prompt.key == key:+ return prompt+ return None+# -------------------------------------------------------------------------# Task registration# -------------------------------------------------------------------------- async def get_tasks(self) -> TaskComponents:+ async def get_tasks(self) -> Sequence[FastMCPComponent]:"""Return components that should be registered as background tasks.Override to customize which components are task-eligible.@@ -257,34 +269,28 @@ class Provider:from fastmcp.resources.template import FunctionResourceTemplatefrom fastmcp.tools.tool import FunctionTool- all_tools = await self.list_tools()- all_resources = await self.list_resources()- all_templates = await self.list_resource_templates()- all_prompts = await self.list_prompts()-- return TaskComponents(- tools=[- t- for t in all_tools- if isinstance(t, FunctionTool) and t.task_config.supports_tasks()- ],- resources=[- r- for r in all_resources- if isinstance(r, FunctionResource) and r.task_config.supports_tasks()- ],- templates=[- t- for t in all_templates- if isinstance(t, FunctionResourceTemplate)+ components: list[FastMCPComponent] = []++ for t in await self.list_tools():+ if isinstance(t, FunctionTool) and t.task_config.supports_tasks():+ components.append(t)++ for r in await self.list_resources():+ if isinstance(r, FunctionResource) and r.task_config.supports_tasks():+ components.append(r)++ for t in await self.list_resource_templates():+ if (+ isinstance(t, FunctionResourceTemplate)and t.task_config.supports_tasks()- ],- prompts=[- p- for p in all_prompts- if isinstance(p, FunctionPrompt) and p.task_config.supports_tasks()- ],- )+ ):+ components.append(t)++ for p in await self.list_prompts():+ if isinstance(p, FunctionPrompt) and p.task_config.supports_tasks():+ components.append(p)++ return components# -------------------------------------------------------------------------# Lifecycle methodsdiff --git a/src/fastmcp/server/providers/fastmcp_provider.py b/src/fastmcp/server/providers/fastmcp_provider.pyindex 0d69133d9..578bc9a61 100644--- a/src/fastmcp/server/providers/fastmcp_provider.py+++ b/src/fastmcp/server/providers/fastmcp_provider.py@@ -21,8 +21,9 @@ from mcp.types import AnyUrlfrom fastmcp.prompts.prompt import Prompt, PromptResultfrom fastmcp.resources.resource import Resource, ResourceContentfrom fastmcp.resources.template import ResourceTemplate-from fastmcp.server.providers.base import Provider, TaskComponents+from fastmcp.server.providers.base import Providerfrom fastmcp.tools.tool import Tool, ToolResult+from fastmcp.utilities.components import FastMCPComponentif TYPE_CHECKING:from docket import Docket@@ -353,7 +354,7 @@ class FastMCPProviderResourceTemplate(ResourceTemplate):existing_key = _docket_fn_key.get()key_token = Noneif not existing_key or "{" not in existing_key:- key_token = _docket_fn_key.set(self.uri_template)+ key_token = _docket_fn_key.set(self.key)try:try:from fastmcp.server.dependencies import get_context@@ -556,7 +557,7 @@ class FastMCPProvider(Provider):# Task registration# -------------------------------------------------------------------------- async def get_tasks(self) -> TaskComponents:+ async def get_tasks(self) -> Sequence[FastMCPComponent]:"""Return task-eligible components from the mounted server.Returns the child's ACTUAL components (not wrapped) so their actual@@ -566,22 +567,10 @@ class FastMCPProvider(Provider):Iterates through all providers in the wrapped server (including itsLocalProvider) to collect task-eligible components."""- tools: list[Tool] = []- resources: list[Resource] = []- templates: list[ResourceTemplate] = []- prompts: list[Prompt] = []-- # Get tasks from all providers in the wrapped server+ components: list[FastMCPComponent] = []for provider in self.server._providers:- nested = await provider.get_tasks()- tools.extend(nested.tools)- resources.extend(nested.resources)- templates.extend(nested.templates)- prompts.extend(nested.prompts)-- return TaskComponents(- tools=tools, resources=resources, templates=templates, prompts=prompts- )+ components.extend(await provider.get_tasks())+ return components# -------------------------------------------------------------------------# Lifecycle methodsdiff --git a/src/fastmcp/server/providers/local_provider.py b/src/fastmcp/server/providers/local_provider.pyindex 4b25a8f6a..fac296f6c 100644--- a/src/fastmcp/server/providers/local_provider.py+++ b/src/fastmcp/server/providers/local_provider.py@@ -27,7 +27,7 @@ from __future__ import annotationsimport inspectfrom collections.abc import Callable, Sequencefrom functools import partial-from typing import TYPE_CHECKING, Any, Literal, overload+from typing import TYPE_CHECKING, Any, Literal, TypeVar, overloadimport mcp.typesfrom mcp.types import Annotations, AnyFunction, ToolAnnotations@@ -35,13 +35,14 @@ from mcp.types import Annotations, AnyFunction, ToolAnnotationsfrom fastmcp.prompts.prompt import FunctionPrompt, Promptfrom fastmcp.resources.resource import Resourcefrom fastmcp.resources.template import ResourceTemplate-from fastmcp.server.providers.base import Provider, TaskComponents+from fastmcp.server.providers.base import Providerfrom fastmcp.server.tasks.config import TaskConfigfrom fastmcp.tools.tool import FunctionTool, Toolfrom fastmcp.tools.tool_transform import (ToolTransformConfig,apply_transformations_to_tools,)+from fastmcp.utilities.components import FastMCPComponentfrom fastmcp.utilities.logging import get_loggerfrom fastmcp.utilities.types import NotSet, NotSetT@@ -52,6 +53,8 @@ logger = get_logger(__name__)DuplicateBehavior = Literal["error", "warn", "replace", "ignore"]+_C = TypeVar("_C", bound=FastMCPComponent)+class LocalProvider(Provider):"""Provider for locally-defined components.@@ -103,160 +106,110 @@ class LocalProvider(Provider):"""super().__init__()self._on_duplicate = on_duplicate- self._tools: dict[str, Tool] = {}- self._resources: dict[str, Resource] = {}- self._templates: dict[str, ResourceTemplate] = {}- self._prompts: dict[str, Prompt] = {}+ # Unified component storage - keyed by prefixed key (e.g., "tool:name", "resource:uri")+ self._components: dict[str, FastMCPComponent] = {}self._tool_transformations: dict[str, ToolTransformConfig] = {}# =========================================================================# Storage methods# =========================================================================- def add_tool(self, tool: Tool) -> Tool:- """Add a tool to this provider's storage.+ def _add_component(self, component: _C) -> _C:+ """Add a component to unified storage.Args:- tool: The Tool instance to add.+ component: The component to add.Returns:- The tool that was added (or existing tool if on_duplicate="ignore").+ The component that was added (or existing if on_duplicate="ignore")."""- existing = self._tools.get(tool.key)+ existing = self._components.get(component.key)if existing:if self._on_duplicate == "error":- raise ValueError(f"Tool already exists: {tool.key}")+ raise ValueError(f"Component already exists: {component.key}")elif self._on_duplicate == "warn":- logger.warning(f"Tool already exists: {tool.key}")+ logger.warning(f"Component already exists: {component.key}")elif self._on_duplicate == "ignore":- return existing+ return existing # type: ignore[return-value]# "replace" and "warn" fall through to add- self._tools[tool.key] = tool- self._notify("tools")- return tool+ self._components[component.key] = component- def remove_tool(self, key: str) -> None:- """Remove a tool from this provider's storage.+ # Notify based on component type+ if isinstance(component, Tool):+ self._notify("tools")+ elif isinstance(component, (Resource, ResourceTemplate)):+ self._notify("resources")+ elif isinstance(component, Prompt):+ self._notify("prompts")- Args:- key: The key of the tool to remove.+ return component- Raises:- KeyError: If the tool is not found.- """- if key not in self._tools:- raise KeyError(f"Tool {key!r} not found")- del self._tools[key]- self._notify("tools")-- def add_resource(self, resource: Resource) -> Resource:- """Add a resource to this provider's storage.+ def _remove_component(self, key: str) -> None:+ """Remove a component from unified storage.Args:- resource: The Resource instance to add.+ key: The prefixed key of the component.- Returns:- The resource that was added (or existing if on_duplicate="ignore").+ Raises:+ KeyError: If the component is not found."""- existing = self._resources.get(resource.key)- if existing:- if self._on_duplicate == "error":- raise ValueError(f"Resource already exists: {resource.key}")- elif self._on_duplicate == "warn":- logger.warning(f"Resource already exists: {resource.key}")- elif self._on_duplicate == "ignore":- return existing+ component = self._components.get(key)+ if component is None:+ raise KeyError(f"Component {key!r} not found")- self._resources[resource.key] = resource- self._notify("resources")- return resource+ del self._components[key]- def remove_resource(self, key: str) -> None:- """Remove a resource from this provider's storage.+ # Notify based on component type+ if isinstance(component, Tool):+ self._notify("tools")+ elif isinstance(component, (Resource, ResourceTemplate)):+ self._notify("resources")+ elif isinstance(component, Prompt):+ self._notify("prompts")- Args:- key: The key of the resource to remove.-- Raises:- KeyError: If the resource is not found.- """- if key not in self._resources:- raise KeyError(f"Resource {key!r} not found")- del self._resources[key]- self._notify("resources")-- def add_template(self, template: ResourceTemplate) -> ResourceTemplate:- """Add a resource template to this provider's storage.+ def _get_component(self, key: str) -> FastMCPComponent | None:+ """Get a component by its prefixed key.Args:- template: The ResourceTemplate instance to add.+ key: The prefixed key (e.g., "tool:name", "resource:uri").Returns:- The template that was added (or existing if on_duplicate="ignore").+ The component, or None if not found."""- existing = self._templates.get(template.key)- if existing:- if self._on_duplicate == "error":- raise ValueError(f"Template already exists: {template.key}")- elif self._on_duplicate == "warn":- logger.warning(f"Template already exists: {template.key}")- elif self._on_duplicate == "ignore":- return existing-- self._templates[template.key] = template- self._notify("resources")- return template-- def remove_template(self, key: str) -> None:- """Remove a resource template from this provider's storage.+ return self._components.get(key)- Args:- key: The key of the template to remove.-- Raises:- KeyError: If the template is not found.- """- if key not in self._templates:- raise KeyError(f"Template {key!r} not found")- del self._templates[key]- self._notify("resources")+ def add_tool(self, tool: Tool) -> Tool:+ """Add a tool to this provider's storage."""+ return self._add_component(tool)- def add_prompt(self, prompt: Prompt) -> Prompt:- """Add a prompt to this provider's storage.+ def remove_tool(self, name: str) -> None:+ """Remove a tool from this provider's storage."""+ self._remove_component(Tool.make_key(name))- Args:- prompt: The Prompt instance to add.+ def add_resource(self, resource: Resource) -> Resource:+ """Add a resource to this provider's storage."""+ return self._add_component(resource)- Returns:- The prompt that was added (or existing if on_duplicate="ignore").- """- existing = self._prompts.get(prompt.key)- if existing:- if self._on_duplicate == "error":- raise ValueError(f"Prompt already exists: {prompt.key}")- elif self._on_duplicate == "warn":- logger.warning(f"Prompt already exists: {prompt.key}")- elif self._on_duplicate == "ignore":- return existing+ def remove_resource(self, uri: str) -> None:+ """Remove a resource from this provider's storage."""+ self._remove_component(Resource.make_key(uri))- self._prompts[prompt.key] = prompt- self._notify("prompts")- return prompt+ def add_template(self, template: ResourceTemplate) -> ResourceTemplate:+ """Add a resource template to this provider's storage."""+ return self._add_component(template)- def remove_prompt(self, key: str) -> None:- """Remove a prompt from this provider's storage.+ def remove_template(self, uri_template: str) -> None:+ """Remove a resource template from this provider's storage."""+ self._remove_component(ResourceTemplate.make_key(uri_template))- Args:- key: The key of the prompt to remove.+ def add_prompt(self, prompt: Prompt) -> Prompt:+ """Add a prompt to this provider's storage."""+ return self._add_component(prompt)- Raises:- KeyError: If the prompt is not found.- """- if key not in self._prompts:- raise KeyError(f"Prompt {key!r} not found")- del self._prompts[key]- self._notify("prompts")+ def remove_prompt(self, name: str) -> None:+ """Remove a prompt from this provider's storage."""+ self._remove_component(Prompt.make_key(name))# =========================================================================# Tool transformation methods@@ -299,8 +252,9 @@ class LocalProvider(Provider):async def list_tools(self) -> Sequence[Tool]:"""Return all tools with transformations applied."""+ tools = {k: v for k, v in self._components.items() if isinstance(v, Tool)}transformed = apply_transformations_to_tools(- tools=self._tools,+ tools=tools,transformations=self._tool_transformations,)return list(transformed.values())@@ -312,54 +266,57 @@ class LocalProvider(Provider):async def list_resources(self) -> Sequence[Resource]:"""Return all resources."""- return list(self._resources.values())+ return [v for v in self._components.values() if isinstance(v, Resource)]async def get_resource(self, uri: str) -> Resource | None:"""Get a resource by URI."""- return self._resources.get(uri)+ component = self._components.get(Resource.make_key(uri))+ return component if isinstance(component, Resource) else Noneasync def list_resource_templates(self) -> Sequence[ResourceTemplate]:"""Return all resource templates."""- return list(self._templates.values())+ return [v for v in self._components.values() if isinstance(v, ResourceTemplate)]async def get_resource_template(self, uri: str) -> ResourceTemplate | None:"""Get a resource template that matches the given URI."""- for template in self._templates.values():- if template.matches(uri) is not None:- return template+ for component in self._components.values():+ if (+ isinstance(component, ResourceTemplate)+ and component.matches(uri) is not None+ ):+ return componentreturn Noneasync def list_prompts(self) -> Sequence[Prompt]:"""Return all prompts."""- return list(self._prompts.values())+ return [v for v in self._components.values() if isinstance(v, Prompt)]async def get_prompt(self, name: str) -> Prompt | None:"""Get a prompt by name."""- return self._prompts.get(name)+ component = self._components.get(Prompt.make_key(name))+ return component if isinstance(component, Prompt) else None++ async def get_component(+ self, key: str+ ) -> Tool | Resource | ResourceTemplate | Prompt | None:+ """Get a component by its prefixed key.++ Efficient O(1) lookup in the unified components dict.+ """+ return self._get_component(key) # type: ignore[return-value]# =========================================================================# Task registration# =========================================================================- async def get_tasks(self) -> TaskComponents:+ async def get_tasks(self) -> Sequence[FastMCPComponent]:"""Return components eligible for background task execution.Returns components that have task_config.mode != 'forbidden'.This includes both FunctionTool/Resource/Prompt instances created viadecorators and custom Tool/Resource/Prompt subclasses."""- return TaskComponents(- tools=[t for t in self._tools.values() if t.task_config.supports_tasks()],- resources=[- r for r in self._resources.values() if r.task_config.supports_tasks()- ],- templates=[- t for t in self._templates.values() if t.task_config.supports_tasks()- ],- prompts=[- p for p in self._prompts.values() if p.task_config.supports_tasks()- ],- )+ return [c for c in self._components.values() if c.task_config.supports_tasks()]# =========================================================================# Decorator methodsdiff --git a/src/fastmcp/server/providers/openapi/provider.py b/src/fastmcp/server/providers/openapi/provider.pyindex 15d6741c2..38e5da241 100644--- a/src/fastmcp/server/providers/openapi/provider.py+++ b/src/fastmcp/server/providers/openapi/provider.py@@ -11,7 +11,7 @@ from jsonschema_path import SchemaPathfrom fastmcp.prompts import Promptfrom fastmcp.resources import Resource, ResourceTemplate-from fastmcp.server.providers.base import Provider, TaskComponents+from fastmcp.server.providers.base import Providerfrom fastmcp.server.providers.openapi.components import (OpenAPIResource,OpenAPIResourceTemplate,@@ -27,6 +27,7 @@ from fastmcp.server.providers.openapi.routing import (_determine_route_type,)from fastmcp.tools.tool import Tool+from fastmcp.utilities.components import FastMCPComponentfrom fastmcp.utilities.logging import get_loggerfrom fastmcp.utilities.openapi import (HTTPRoute,@@ -378,6 +379,6 @@ class OpenAPIProvider(Provider):"""Return empty list - OpenAPI doesn't create prompts."""return []- async def get_tasks(self) -> TaskComponents:- """Return empty TaskComponents - OpenAPI components don't support tasks."""- return TaskComponents()+ async def get_tasks(self) -> Sequence[FastMCPComponent]:+ """Return empty list - OpenAPI components don't support tasks."""+ return []diff --git a/src/fastmcp/server/providers/proxy.py b/src/fastmcp/server/providers/proxy.pyindex f0aa06c70..98168eea1 100644--- a/src/fastmcp/server/providers/proxy.py+++ b/src/fastmcp/server/providers/proxy.py@@ -39,7 +39,7 @@ from fastmcp.resources import Resource, ResourceTemplatefrom fastmcp.resources.resource import ResourceContentfrom fastmcp.server.context import Contextfrom fastmcp.server.dependencies import get_context-from fastmcp.server.providers.base import Provider, TaskComponents+from fastmcp.server.providers.base import Providerfrom fastmcp.server.server import FastMCPfrom fastmcp.server.tasks.config import TaskConfigfrom fastmcp.tools.tool import Tool, ToolResult@@ -47,7 +47,7 @@ from fastmcp.tools.tool_transform import (ToolTransformConfig,apply_transformations_to_tools,)-from fastmcp.utilities.components import MirroredComponent+from fastmcp.utilities.components import FastMCPComponent, MirroredComponentfrom fastmcp.utilities.logging import get_loggerif TYPE_CHECKING:@@ -541,14 +541,14 @@ class ProxyProvider(Provider):# Task methods# -------------------------------------------------------------------------- async def get_tasks(self) -> TaskComponents:- """Return empty TaskComponents since proxy components don't support tasks.+ async def get_tasks(self) -> Sequence[FastMCPComponent]:+ """Return empty list since proxy components don't support tasks.Override the base implementation to avoid calling list_tools() duringserver lifespan initialization, which would open the client before anycontext is set. All Proxy* components have task_config.mode="forbidden"."""- return TaskComponents()+ return []# lifespan() uses default implementation (empty context manager)# because client cleanup is handled per-requestdiff --git a/src/fastmcp/server/providers/transforming.py b/src/fastmcp/server/providers/transforming.pyindex 8c27d70e4..f6231a733 100644--- a/src/fastmcp/server/providers/transforming.py+++ b/src/fastmcp/server/providers/transforming.py@@ -14,14 +14,12 @@ from typing import TYPE_CHECKINGfrom fastmcp.prompts.prompt import Promptfrom fastmcp.resources.resource import Resourcefrom fastmcp.resources.template import ResourceTemplate-from fastmcp.server.providers.base import Provider, TaskComponents+from fastmcp.server.providers.base import Providerfrom fastmcp.tools.tool import Tool+from fastmcp.utilities.components import FastMCPComponentif TYPE_CHECKING:- from fastmcp.prompts.prompt import FunctionPrompt- from fastmcp.resources.resource import FunctionResource- from fastmcp.resources.template import FunctionResourceTemplate- from fastmcp.tools.tool import FunctionTool+ pass# Pattern for matching URIs: protocol://path@@ -262,49 +260,41 @@ class TransformingProvider(Provider):# Task registration# -------------------------------------------------------------------------- async def get_tasks(self) -> TaskComponents:+ async def get_tasks(self) -> Sequence[FastMCPComponent]:"""Get tasks with transformations applied to all components."""+ transformed: list[FastMCPComponent] = []- tasks = await self._wrapped.get_tasks()-- # Apply transforms to tools- transformed_tools: list[FunctionTool] = []- for t in tasks.tools:- transformed_tools.append(- t.model_copy(update={"name": self._transform_tool_name(t.name)}) # type: ignore[arg-type]- )-- # Apply transforms to resources- transformed_resources: list[FunctionResource] = []- for r in tasks.resources:- transformed_resources.append(- r.model_copy(update={"uri": self._transform_resource_uri(str(r.uri))}) # type: ignore[arg-type]- )-- # Apply transforms to templates- transformed_templates: list[FunctionResourceTemplate] = []- for t in tasks.templates:- transformed_templates.append(- t.model_copy(- update={- "uri_template": self._transform_resource_uri(t.uri_template)- }- ) # type: ignore[arg-type]- )-- # Apply transforms to prompts- transformed_prompts: list[FunctionPrompt] = []- for p in tasks.prompts:- transformed_prompts.append(- p.model_copy(update={"name": self._transform_prompt_name(p.name)}) # type: ignore[arg-type]- )+ for component in await self._wrapped.get_tasks():+ if isinstance(component, Tool):+ transformed.append(+ component.model_copy(+ update={"name": self._transform_tool_name(component.name)}+ )+ )+ elif isinstance(component, ResourceTemplate):+ transformed.append(+ component.model_copy(+ update={+ "uri_template": self._transform_resource_uri(+ component.uri_template+ )+ }+ )+ )+ elif isinstance(component, Resource):+ transformed.append(+ component.model_copy(+ update={"uri": self._transform_resource_uri(str(component.uri))}+ )+ )+ elif isinstance(component, Prompt):+ transformed.append(+ component.model_copy(+ update={"name": self._transform_prompt_name(component.name)}+ )+ )- return TaskComponents(- tools=transformed_tools,- resources=transformed_resources,- templates=transformed_templates,- prompts=transformed_prompts,- )+ return transformed# -------------------------------------------------------------------------# Lifecyclediff --git a/src/fastmcp/server/server.py b/src/fastmcp/server/server.pyindex 5ca424810..2a6ef1871 100644--- a/src/fastmcp/server/server.py+++ b/src/fastmcp/server/server.py@@ -461,15 +461,8 @@ class FastMCP(Generic[LifespanResultT]):# Register task-enabled components from all providers (LocalProvider first)for provider in self._providers:try:- tasks = await provider.get_tasks()- for tool in tasks.tools:- tool.register_with_docket(docket)- for resource in tasks.resources:- resource.register_with_docket(docket)- for template in tasks.templates:- template.register_with_docket(docket)- for prompt in tasks.prompts:- prompt.register_with_docket(docket)+ for component in await provider.get_tasks():+ component.register_with_docket(docket)except Exception as e:provider_name = getattr(provider, "server", provider@@ -707,18 +700,18 @@ class FastMCP(Generic[LifespanResultT]):self._providers.append(provider)async def get_tools(self) -> dict[str, Tool]:- """Get all tools (unfiltered), including from providers, indexed by key.+ """Get all tools (unfiltered), including from providers, indexed by name.Iterates through all providers (LocalProvider first) and collects tools.- First provider wins for duplicate keys.+ First provider wins for duplicate names."""all_tools: dict[str, Tool] = {}for provider in self._providers:try:provider_tools = await provider.list_tools()for tool in provider_tools:- if tool.key not in all_tools:- all_tools[tool.key] = tool+ if tool.name not in all_tools:+ all_tools[tool.name] = toolexcept Exception as e:provider_name = getattr(provider, "server", provider).__class__.__name__logger.warning(@@ -729,21 +722,21 @@ class FastMCP(Generic[LifespanResultT]):continuereturn all_tools- async def get_tool(self, key: str) -> Tool:- """Get a tool by key.+ async def get_tool(self, name: str) -> Tool:+ """Get a tool by name.Iterates through all providers (LocalProvider first) to find the tool.First provider wins."""for provider in self._providers:try:- tool = await provider.get_tool(key)+ tool = await provider.get_tool(name)if tool is not None:return toolexcept NotFoundError:continue- raise NotFoundError(f"Unknown tool: {key}")+ raise NotFoundError(f"Unknown tool: {name}")async def _get_resource_or_template_or_none(self, uri: str@@ -777,18 +770,19 @@ class FastMCP(Generic[LifespanResultT]):return Noneasync def get_resources(self) -> dict[str, Resource]:- """Get all resources (unfiltered), including from providers, indexed by key.+ """Get all resources (unfiltered), including from providers, indexed by URI.Iterates through all providers (LocalProvider first) and collects resources.- First provider wins for duplicate keys.+ First provider wins for duplicate URIs."""all_resources: dict[str, Resource] = {}for provider in self._providers:try:provider_resources = await provider.list_resources()for resource in provider_resources:- if resource.key not in all_resources:- all_resources[resource.key] = resource+ uri = str(resource.uri)+ if uri not in all_resources:+ all_resources[uri] = resourceexcept Exception as e:provider_name = getattr(provider, "server", provider).__class__.__name__logger.warning(@@ -799,35 +793,35 @@ class FastMCP(Generic[LifespanResultT]):continuereturn all_resources- async def get_resource(self, key: str) -> Resource:- """Get a resource by key.+ async def get_resource(self, uri: str) -> Resource:+ """Get a resource by URI.Iterates through all providers (LocalProvider first) to find the resource.First provider wins."""for provider in self._providers:try:- resource = await provider.get_resource(key)+ resource = await provider.get_resource(uri)if resource is not None:return resourceexcept NotFoundError:continue- raise NotFoundError(f"Unknown resource: {key}")+ raise NotFoundError(f"Unknown resource: {uri}")async def get_resource_templates(self) -> dict[str, ResourceTemplate]:- """Get all resource templates (unfiltered), including from providers, indexed by key.+ """Get all resource templates (unfiltered), including from providers, indexed by uri_template.Iterates through all providers (LocalProvider first) and collects templates.- First provider wins for duplicate keys.+ First provider wins for duplicate uri_templates."""all_templates: dict[str, ResourceTemplate] = {}for provider in self._providers:try:provider_templates = await provider.list_resource_templates()for template in provider_templates:- if template.key not in all_templates:- all_templates[template.key] = template+ if template.uri_template not in all_templates:+ all_templates[template.uri_template] = templateexcept Exception as e:provider_name = getattr(provider, "server", provider).__class__.__name__logger.warning(@@ -838,35 +832,35 @@ class FastMCP(Generic[LifespanResultT]):continuereturn all_templates- async def get_resource_template(self, key: str) -> ResourceTemplate:- """Get a registered resource template by key.+ async def get_resource_template(self, uri: str) -> ResourceTemplate:+ """Get a resource template that matches the given URI.Iterates through all providers (LocalProvider first) to find the template.First provider wins."""for provider in self._providers:try:- template = await provider.get_resource_template(key)+ template = await provider.get_resource_template(uri)if template is not None:return templateexcept NotFoundError:continue- raise NotFoundError(f"Unknown resource template: {key}")+ raise NotFoundError(f"Unknown resource template: {uri}")async def get_prompts(self) -> dict[str, Prompt]:- """Get all prompts (unfiltered), including from providers, indexed by key.+ """Get all prompts (unfiltered), including from providers, indexed by name.Iterates through all providers (LocalProvider first) and collects prompts.- First provider wins for duplicate keys.+ First provider wins for duplicate names."""all_prompts: dict[str, Prompt] = {}for provider in self._providers:try:provider_prompts = await provider.list_prompts()for prompt in provider_prompts:- if prompt.key not in all_prompts:- all_prompts[prompt.key] = prompt+ if prompt.name not in all_prompts:+ all_prompts[prompt.name] = promptexcept Exception as e:provider_name = getattr(provider, "server", provider).__class__.__name__logger.warning(@@ -877,21 +871,48 @@ class FastMCP(Generic[LifespanResultT]):continuereturn all_prompts- async def get_prompt(self, key: str) -> Prompt:- """Get a prompt by key.+ async def get_prompt(self, name: str) -> Prompt:+ """Get a prompt by name.Iterates through all providers (LocalProvider first) to find the prompt.First provider wins."""for provider in self._providers:try:- prompt = await provider.get_prompt(key)+ prompt = await provider.get_prompt(name)if prompt is not None:return promptexcept NotFoundError:continue- raise NotFoundError(f"Unknown prompt: {key}")+ raise NotFoundError(f"Unknown prompt: {name}")++ async def get_component(+ self, key: str+ ) -> Tool | Resource | ResourceTemplate | Prompt:+ """Get a component by its prefixed key.++ Iterates through all providers (LocalProvider first) to find the component.+ First provider wins.++ Args:+ key: The prefixed key (e.g., "tool:name", "resource:uri", "template:uri").++ Returns:+ The component if found.++ Raises:+ NotFoundError: If no component is found with the given key.+ """+ for provider in self._providers:+ try:+ component = await provider.get_component(key)+ if component is not None:+ return component+ except NotFoundError:+ continue++ raise NotFoundError(f"Unknown component: {key}")def custom_route(self,@@ -965,7 +986,7 @@ class FastMCP(Generic[LifespanResultT]):tools = await self._list_tools_middleware()return [tool.to_mcp_tool(- name=tool.key,+ name=tool.name,include_fastmcp_meta=self.include_fastmcp_meta,)for tool in tools@@ -1030,7 +1051,7 @@ class FastMCP(Generic[LifespanResultT]):resources = await self._list_resources_middleware()return [resource.to_mcp_resource(- uri=resource.key,+ uri=str(resource.uri),include_fastmcp_meta=self.include_fastmcp_meta,)for resource in resources@@ -1095,7 +1116,7 @@ class FastMCP(Generic[LifespanResultT]):templates = await self._list_resource_templates_middleware()return [template.to_mcp_template(- uriTemplate=template.key,+ uriTemplate=template.uri_template,include_fastmcp_meta=self.include_fastmcp_meta,)for template in templates@@ -1161,7 +1182,7 @@ class FastMCP(Generic[LifespanResultT]):prompts = await self._list_prompts_middleware()return [prompt.to_mcp_prompt(- name=prompt.key,+ name=prompt.name,include_fastmcp_meta=self.include_fastmcp_meta,)for prompt in prompts@@ -1257,7 +1278,7 @@ class FastMCP(Generic[LifespanResultT]):# Set contextvars so tool._run() can access themtask_token = _task_metadata.set(task_meta_dict)- key_token = _docket_fn_key.set(key)+ key_token = _docket_fn_key.set(Tool.make_key(key))try:# Middleware always runs - tool._run() handles backgroundingresult = await self._call_tool_middleware(key, arguments)@@ -1301,7 +1322,7 @@ class FastMCP(Generic[LifespanResultT]):try:# Set contextvars so Resource._read() can access themtask_token = _task_metadata.set(task_meta_dict)- key_token = _docket_fn_key.set(str(uri))+ key_token = _docket_fn_key.set(Resource.make_key(str(uri)))try:# Middleware always runs - Resource._read() handles backgroundingresult = await self._read_resource_middleware(uri)@@ -1353,7 +1374,7 @@ class FastMCP(Generic[LifespanResultT]):try:# Set contextvars so Prompt._render() can access themtask_token = _task_metadata.set(task_meta_dict)- key_token = _docket_fn_key.set(name)+ key_token = _docket_fn_key.set(Prompt.make_key(name))try:# Middleware always runs - Prompt._render() handles backgroundingresult = await self._get_prompt_content_middleware(name, arguments)diff --git a/src/fastmcp/server/tasks/requests.py b/src/fastmcp/server/tasks/requests.pyindex d9aee6147..434958953 100644--- a/src/fastmcp/server/tasks/requests.py+++ b/src/fastmcp/server/tasks/requests.py@@ -276,10 +276,17 @@ async def tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any:},)- # Parse task key to get type and component info+ # Parse task key to get component keykey_parts = parse_task_key(task_key)- task_type = key_parts["task_type"]- component_id = key_parts["component_identifier"]+ component_key = key_parts["component_identifier"]++ # Look up component by its prefixed key+ from fastmcp.prompts.prompt import Prompt+ from fastmcp.resources.resource import Resource+ from fastmcp.resources.template import ResourceTemplate+ from fastmcp.tools.tool import Tool++ component = await server.get_component(component_key)# Build related-task metadatarelated_task_meta = {@@ -288,10 +295,9 @@ async def tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any:}}- # Convert based on task type- if task_type == "tool":- tool = await server.get_tool(component_id)- fastmcp_result = tool.convert_result(raw_value)+ # Convert based on component type+ if isinstance(component, Tool):+ fastmcp_result = component.convert_result(raw_value)mcp_result = fastmcp_result.to_mcp_result()# Ensure we have a CallToolResult and add metadataif isinstance(mcp_result, mcp.types.CallToolResult):@@ -310,26 +316,25 @@ async def tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any:)return mcp_result- elif task_type == "prompt":- prompt = await server.get_prompt(component_id)- fastmcp_result = prompt.convert_result(raw_value)+ elif isinstance(component, Prompt):+ fastmcp_result = component.convert_result(raw_value)mcp_result = fastmcp_result.to_mcp_prompt_result()mcp_result._meta = related_task_meta # type: ignore[attr-defined]return mcp_result- elif task_type == "resource":- resource = await server.get_resource(component_id)- resource_content = resource.convert_result(raw_value)- mcp_content = resource_content.to_mcp_resource_contents(component_id)+ elif isinstance(component, ResourceTemplate):+ resource_content = component.convert_result(raw_value)+ mcp_content = resource_content.to_mcp_resource_contents(+ component.uri_template+ )return mcp.types.ReadResourceResult(contents=[mcp_content],_meta=related_task_meta, # type: ignore[call-arg] # _meta is Pydantic alias for meta field)- elif task_type == "template":- template = await server.get_resource_template(component_id)- resource_content = template.convert_result(raw_value)- mcp_content = resource_content.to_mcp_resource_contents(component_id)+ elif isinstance(component, Resource):+ resource_content = component.convert_result(raw_value)+ mcp_content = resource_content.to_mcp_resource_contents(str(component.uri))return mcp.types.ReadResourceResult(contents=[mcp_content],_meta=related_task_meta, # type: ignore[call-arg] # _meta is Pydantic alias for meta field@@ -339,7 +344,7 @@ async def tasks_result_handler(server: FastMCP, params: dict[str, Any]) -> Any:raise McpError(ErrorData(code=INTERNAL_ERROR,- message=f"Internal error: Unknown task type: {task_type}",+ message=f"Internal error: Unknown component type: {type(component).__name__}",))diff --git a/src/fastmcp/tools/tool.py b/src/fastmcp/tools/tool.pyindex a2a6f431e..8980a37e5 100644--- a/src/fastmcp/tools/tool.py+++ b/src/fastmcp/tools/tool.py@@ -8,6 +8,7 @@ from typing import (TYPE_CHECKING,Annotated,Any,+ ClassVar,Generic,TypeAlias,get_type_hints,@@ -126,6 +127,8 @@ class ToolResult:class Tool(FastMCPComponent):"""Internal tool registration info."""+ KEY_PREFIX: ClassVar[str] = "tool"+parameters: Annotated[dict[str, Any], Field(description="JSON schema for tool parameters")]diff --git a/src/fastmcp/tools/tool_transform.py b/src/fastmcp/tools/tool_transform.pyindex 62ade0cbb..33b6f0a73 100644--- a/src/fastmcp/tools/tool_transform.py+++ b/src/fastmcp/tools/tool_transform.py@@ -927,17 +927,20 @@ def apply_transformations_to_tools() -> dict[str, Tool]:"""Apply a list of transformations to a list of tools. Tools that do not have any transformationsare left unchanged.++ Note: tools dict is keyed by prefixed key (e.g., "tool:my_tool"),+ but transformations are keyed by tool name (e.g., "my_tool")."""transformed_tools: dict[str, Tool] = {}- for tool_name, tool in tools.items():- if transformation := transformations.get(tool_name):- transformed_tools[transformation.name or tool_name] = transformation.apply(- tool- )+ for tool_key, tool in tools.items():+ # Look up transformation by tool name, not prefixed key+ if transformation := transformations.get(tool.name):+ transformed = transformation.apply(tool)+ transformed_tools[transformed.key] = transformedcontinue- transformed_tools[tool_name] = tool+ transformed_tools[tool_key] = toolreturn transformed_toolsdiff --git a/src/fastmcp/utilities/components.py b/src/fastmcp/utilities/components.pyindex 2e5059f62..fedd4f271 100644--- a/src/fastmcp/utilities/components.py+++ b/src/fastmcp/utilities/components.py@@ -1,7 +1,7 @@from __future__ import annotationsfrom collections.abc import Sequence-from typing import TYPE_CHECKING, Annotated, Any, TypedDict+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, TypedDictfrom mcp.types import Iconfrom pydantic import BeforeValidator, Field, PrivateAttr@@ -34,6 +34,22 @@ def _convert_set_default_none(maybe_set: set[T] | Sequence[T] | None) -> set[T]:class FastMCPComponent(FastMCPBaseModel):"""Base class for FastMCP tools, prompts, resources, and resource templates."""+ KEY_PREFIX: ClassVar[str] = ""++ def __init_subclass__(cls, **kwargs: Any) -> None:+ super().__init_subclass__(**kwargs)+ # Warn if a subclass doesn't define KEY_PREFIX (inherited or its own)+ # MirroredComponent is a mixin that will be removed; skip it+ if not cls.KEY_PREFIX and cls.__name__ != "MirroredComponent":+ import warnings++ warnings.warn(+ f"{cls.__name__} does not define KEY_PREFIX. "+ f"Component keys will not be type-prefixed, which may cause collisions.",+ UserWarning,+ stacklevel=2,+ )+name: str = Field(description="The name of the component.",)@@ -65,16 +81,30 @@ class FastMCPComponent(FastMCPBaseModel):Field(description="Background task execution configuration (SEP-1686)."),] = Field(default_factory=lambda: TaskConfig(mode="forbidden"))+ @classmethod+ def make_key(cls, identifier: str) -> str:+ """Construct the lookup key for this component type.++ Args:+ identifier: The raw identifier (name for tools/prompts, uri for resources)++ Returns:+ A prefixed key like "tool:name" or "resource:uri"+ """+ if cls.KEY_PREFIX:+ return f"{cls.KEY_PREFIX}:{identifier}"+ return identifier+@propertydef key(self) -> str:- """The lookup key for this component. Returns name by default.+ """The globally unique lookup key for this component.++ Format: "{key_prefix}:{identifier}" e.g. "tool:my_tool", "resource:file://x.txt"- Subclasses override this to return different identifiers:- - Tools/Prompts: name- - Resources: str(uri)- - Templates: uri_template+ Subclasses should override this to use their specific identifier.+ Base implementation uses name."""- return self.name+ return self.make_key(self.name)def get_meta(self, include_fastmcp_meta: bool | None = Nonediff --git a/src/fastmcp/utilities/inspect.py b/src/fastmcp/utilities/inspect.pyindex b4563090d..273ca6d7c 100644--- a/src/fastmcp/utilities/inspect.py+++ b/src/fastmcp/utilities/inspect.py@@ -119,7 +119,7 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:# Extract detailed tool informationtool_infos = []for tool in tools_list:- mcp_tool = tool.to_mcp_tool(name=tool.key)+ mcp_tool = tool.to_mcp_tool(name=tool.name)tool_infos.append(ToolInfo(key=tool.key,@@ -165,7 +165,7 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:resource_infos.append(ResourceInfo(key=resource.key,- uri=resource.key,+ uri=str(resource.uri),name=resource.name,description=resource.description,mime_type=resource.mime_type,@@ -188,7 +188,7 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:template_infos.append(TemplateInfo(key=template.key,- uri_template=template.key,+ uri_template=template.uri_template,name=template.name,description=template.description,mime_type=template.mime_type,diff --git a/tests/server/providers/test_local_provider.py b/tests/server/providers/test_local_provider.pyindex 3bbc90805..b5447fe6e 100644--- a/tests/server/providers/test_local_provider.py+++ b/tests/server/providers/test_local_provider.py@@ -35,8 +35,8 @@ class TestLocalProviderStorage:)provider.add_tool(tool)- assert "test_tool" in provider._tools- assert provider._tools["test_tool"] is tool+ assert "tool:test_tool" in provider._components+ assert provider._components["tool:test_tool"] is tooldef test_add_multiple_tools(self):"""Test adding multiple tools."""@@ -55,8 +55,8 @@ class TestLocalProviderStorage:provider.add_tool(tool1)provider.add_tool(tool2)- assert "tool1" in provider._tools- assert "tool2" in provider._tools+ assert "tool:tool1" in provider._components+ assert "tool:tool2" in provider._componentsdef test_remove_tool(self):"""Test removing a tool from LocalProvider."""@@ -70,7 +70,7 @@ class TestLocalProviderStorage:provider.add_tool(tool)provider.remove_tool("test_tool")- assert "test_tool" not in provider._tools+ assert "tool:test_tool" not in provider._componentsdef test_remove_nonexistent_tool_raises(self):"""Test that removing a nonexistent tool raises KeyError."""@@ -87,7 +87,7 @@ class TestLocalProviderStorage:def test_resource() -> str:return "content"- assert "resource://test" in provider._resources+ assert "resource:resource://test" in provider._componentsdef test_remove_resource(self):"""Test removing a resource from LocalProvider."""@@ -99,7 +99,7 @@ class TestLocalProviderStorage:provider.remove_resource("resource://test")- assert "resource://test" not in provider._resources+ assert "resource:resource://test" not in provider._componentsdef test_add_template(self):"""Test adding a resource template to LocalProvider."""@@ -109,7 +109,7 @@ class TestLocalProviderStorage:def template_fn(id: str) -> str:return f"Resource {id}"- assert "resource://{id}" in provider._templates+ assert "template:resource://{id}" in provider._componentsdef test_remove_template(self):"""Test removing a resource template from LocalProvider."""@@ -121,7 +121,7 @@ class TestLocalProviderStorage:provider.remove_template("resource://{id}")- assert "resource://{id}" not in provider._templates+ assert "template:resource://{id}" not in provider._componentsdef test_add_prompt(self):"""Test adding a prompt to LocalProvider."""@@ -133,7 +133,7 @@ class TestLocalProviderStorage:)provider.add_prompt(prompt)- assert "test_prompt" in provider._prompts+ assert "prompt:test_prompt" in provider._componentsdef test_remove_prompt(self):"""Test removing a prompt from LocalProvider."""@@ -146,7 +146,7 @@ class TestLocalProviderStorage:provider.add_prompt(prompt)provider.remove_prompt("test_prompt")- assert "test_prompt" not in provider._prompts+ assert "prompt:test_prompt" not in provider._componentsclass TestLocalProviderInterface:@@ -304,8 +304,8 @@ class TestLocalProviderDecorators:def my_tool(x: int) -> int:return x * 2- assert "my_tool" in provider._tools- assert provider._tools["my_tool"].name == "my_tool"+ assert "tool:my_tool" in provider._components+ assert provider._components["tool:my_tool"].name == "my_tool"def test_tool_decorator_with_parens(self):"""Test @provider.tool() with empty parentheses."""@@ -315,7 +315,7 @@ class TestLocalProviderDecorators:def my_tool(x: int) -> int:return x * 2- assert "my_tool" in provider._tools+ assert "tool:my_tool" in provider._componentsdef test_tool_decorator_with_name_kwarg(self):"""Test @provider.tool(name='custom')."""@@ -325,8 +325,8 @@ class TestLocalProviderDecorators:def my_tool(x: int) -> int:return x * 2- assert "custom_name" in provider._tools- assert "my_tool" not in provider._tools+ assert "tool:custom_name" in provider._components+ assert "tool:my_tool" not in provider._componentsdef test_tool_decorator_with_description(self):"""Test @provider.tool(description='...')."""@@ -336,7 +336,7 @@ class TestLocalProviderDecorators:def my_tool(x: int) -> int:return x * 2- assert provider._tools["my_tool"].description == "Custom description"+ assert provider._components["tool:my_tool"].description == "Custom description"def test_tool_direct_call(self):"""Test provider.tool(fn, name='...')."""@@ -347,7 +347,7 @@ class TestLocalProviderDecorators:provider.tool(my_tool, name="direct_tool")- assert "direct_tool" in provider._tools+ assert "tool:direct_tool" in provider._componentsasync def test_tool_decorator_execution(self):"""Test that decorated tools execute correctly."""@@ -371,7 +371,7 @@ class TestLocalProviderDecorators:def my_resource() -> str:return "test content"- assert "resource://test" in provider._resources+ assert "resource:resource://test" in provider._componentsdef test_resource_decorator_with_name(self):"""Test @provider.resource with custom name."""@@ -381,7 +381,7 @@ class TestLocalProviderDecorators:def my_resource() -> str:return "test content"- assert provider._resources["resource://test"].name == "custom_name"+ assert provider._components["resource:resource://test"].name == "custom_name"async def test_resource_decorator_execution(self):"""Test that decorated resources execute correctly."""@@ -405,7 +405,7 @@ class TestLocalProviderDecorators:def my_prompt() -> str:return "A prompt"- assert "my_prompt" in provider._prompts+ assert "prompt:my_prompt" in provider._componentsdef test_prompt_decorator_with_parens(self):"""Test @provider.prompt() with empty parentheses."""@@ -415,7 +415,7 @@ class TestLocalProviderDecorators:def my_prompt() -> str:return "A prompt"- assert "my_prompt" in provider._prompts+ assert "prompt:my_prompt" in provider._componentsdef test_prompt_decorator_with_name(self):"""Test @provider.prompt(name='custom')."""@@ -425,8 +425,8 @@ class TestLocalProviderDecorators:def my_prompt() -> str:return "A prompt"- assert "custom_prompt" in provider._prompts- assert "my_prompt" not in provider._prompts+ assert "prompt:custom_prompt" in provider._components+ assert "prompt:my_prompt" not in provider._componentsclass TestLocalProviderToolTransformations:@@ -510,8 +510,8 @@ class TestLocalProviderTaskRegistration:return xtasks = await provider.get_tasks()- assert len(tasks.tools) == 1- assert tasks.tools[0].name == "background_tool"+ assert len(tasks) == 1+ assert tasks[0].name == "background_tool"async def test_get_tasks_filters_forbidden_tools(self):"""Test that get_tasks excludes tools with forbidden task mode."""@@ -522,7 +522,7 @@ class TestLocalProviderTaskRegistration:return xtasks = await provider.get_tasks()- assert len(tasks.tools) == 0+ assert len(tasks) == 0async def test_get_tasks_includes_custom_tool_subclasses(self):"""Test that custom Tool subclasses are included in get_tasks."""@@ -538,8 +538,8 @@ class TestLocalProviderTaskRegistration:provider.add_tool(CustomTool(name="custom", description="Custom tool"))tasks = await provider.get_tasks()- assert len(tasks.tools) == 1- assert tasks.tools[0].name == "custom"+ assert len(tasks) == 1+ assert tasks[0].name == "custom"class TestLocalProviderStandaloneUsage:diff --git a/tests/server/tasks/test_custom_subclass_tasks.py b/tests/server/tasks/test_custom_subclass_tasks.pyindex 3bb6f834a..a361560fb 100644--- a/tests/server/tasks/test_custom_subclass_tasks.py+++ b/tests/server/tasks/test_custom_subclass_tasks.py@@ -122,10 +122,10 @@ async def test_custom_tool_registers_with_docket():tool.register_with_docket(mock_docket)- # Should register self.run with docket+ # Should register self.run with docket using prefixed keymock_docket.register.assert_called_once()call_args = mock_docket.register.call_args- assert call_args[1]["names"] == ["test"]+ assert call_args[1]["names"] == ["tool:test"]async def test_custom_tool_forbidden_does_not_register():diff --git a/tests/server/tasks/test_server_tasks_parameter.py b/tests/server/tasks/test_server_tasks_parameter.pyindex b61edb4a4..b175a46ad 100644--- a/tests/server/tasks/test_server_tasks_parameter.py+++ b/tests/server/tasks/test_server_tasks_parameter.py@@ -28,12 +28,12 @@ async def test_server_tasks_true_defaults_all_components():async with Client(mcp) as client:# Verify all task-enabled components are registered with docket- # Tools and prompts use .key (which equals name), resources use .key (which is URI)+ # Components use prefixed keys: tool:name, prompt:name, resource:uridocket = mcp.docketassert docket is not None- assert "my_tool" in docket.tasks- assert "my_prompt" in docket.tasks- assert "test://resource" in docket.tasks+ assert "tool:my_tool" in docket.tasks+ assert "prompt:my_prompt" in docket.tasks+ assert "resource:test://resource" in docket.tasks# Tool should support background executiontool_task = await client.call_tool("my_tool", task=True)@@ -114,11 +114,13 @@ async def test_component_explicit_false_overrides_server_true():return "background result"async with Client(mcp) as client:- # Verify docket registration matches task settings+ # Verify docket registration matches task settings (prefixed keys)docket = mcp.docketassert docket is not None- assert "no_task_tool" not in docket.tasks # task=False means not registered- assert "default_tool" in docket.tasks # Inherits tasks=True+ assert (+ "tool:no_task_tool" not in docket.tasks+ ) # task=False means not registered+ assert "tool:default_tool" in docket.tasks # Inherits tasks=True# Explicit False (mode="forbidden") returns error when called with task=Trueno_task = await client.call_tool("no_task_tool", task=True)@@ -145,11 +147,11 @@ async def test_component_explicit_true_overrides_server_false():return "immediate result"async with Client(mcp) as client:- # Verify docket registration matches task settings+ # Verify docket registration matches task settings (prefixed keys)docket = mcp.docketassert docket is not None- assert "task_tool" in docket.tasks # task=True means registered- assert "default_tool" not in docket.tasks # Inherits tasks=False+ assert "tool:task_tool" in docket.tasks # task=True means registered+ assert "tool:default_tool" not in docket.tasks # Inherits tasks=False# Explicit True should support background execution despite server defaulttask = await client.call_tool("task_tool", task=True)@@ -199,18 +201,18 @@ async def test_mixed_explicit_and_inherited():async with Client(mcp) as client:# Verify docket registration matches task settings- # Tools/prompts use .key (name), resources use .key (URI)+ # Components use prefixed keys: tool:name, prompt:name, resource:uridocket = mcp.docketassert docket is not None- # task=True (explicit or inherited) means registered- assert "inherited_tool" in docket.tasks- assert "explicit_true_tool" in docket.tasks- assert "inherited_prompt" in docket.tasks- assert "test://inherited" in docket.tasks+ # task=True (explicit or inherited) means registered (with prefixed keys)+ assert "tool:inherited_tool" in docket.tasks+ assert "tool:explicit_true_tool" in docket.tasks+ assert "prompt:inherited_prompt" in docket.tasks+ assert "resource:test://inherited" in docket.tasks# task=False means NOT registered- assert "explicit_false_tool" not in docket.tasks- assert "explicit_false_prompt" not in docket.tasks- assert "test://explicit_false" not in docket.tasks+ assert "tool:explicit_false_tool" not in docket.tasks+ assert "prompt:explicit_false_prompt" not in docket.tasks+ assert "resource:test://explicit_false" not in docket.tasks# Toolsinherited = await client.call_tool("inherited_tool", task=True)@@ -326,10 +328,10 @@ async def test_task_with_custom_tool_name():mcp.tool(my_function, name="custom-tool-name")async with Client(mcp) as client:- # Verify the tool is registered with its custom name in Docket+ # Verify the tool is registered with its custom name in Docket (prefixed key)docket = mcp.docketassert docket is not None- assert "custom-tool-name" in docket.tasks+ assert "tool:custom-tool-name" in docket.tasks# Call the tool as a task using its custom nametask = await client.call_tool("custom-tool-name", task=True)@@ -350,10 +352,10 @@ async def test_task_with_custom_resource_name():return "result from custom-named resource"async with Client(mcp) as client:- # Verify the resource is registered with its key (URI) in Docket+ # Verify the resource is registered with its key (prefixed URI) in Docketdocket = mcp.docketassert docket is not None- assert "test://resource" in docket.tasks+ assert "resource:test://resource" in docket.tasks# Call the resource as a tasktask = await client.read_resource("test://resource", task=True)@@ -374,10 +376,10 @@ async def test_task_with_custom_template_name():return f"result for {item_id}"async with Client(mcp) as client:- # Verify the template is registered with its key (uri_template) in Docket+ # Verify the template is registered with its key (prefixed uri_template) in Docketdocket = mcp.docketassert docket is not None- assert "test://{item_id}" in docket.tasks+ assert "template:test://{item_id}" in docket.tasks# Call the template as a tasktask = await client.read_resource("test://123", task=True)diff --git a/tests/utilities/test_components.py b/tests/utilities/test_components.pyindex 15a9232a3..32d2c2f0c 100644--- a/tests/utilities/test_components.py+++ b/tests/utilities/test_components.py@@ -1,8 +1,14 @@"""Tests for fastmcp.utilities.components module."""+import warnings+import pytestfrom pydantic import ValidationError+from fastmcp.prompts.prompt import Prompt+from fastmcp.resources.resource import Resource+from fastmcp.resources.template import ResourceTemplate+from fastmcp.tools.tool import Toolfrom fastmcp.utilities.components import (FastMCPComponent,FastMCPMeta,@@ -187,6 +193,70 @@ class TestFastMCPComponent:assert "Extra inputs are not permitted" in str(exc_info.value)+class TestKeyPrefix:+ """Tests for KEY_PREFIX and make_key functionality."""++ def test_base_class_has_empty_prefix(self):+ """Test that FastMCPComponent has empty KEY_PREFIX."""+ assert FastMCPComponent.KEY_PREFIX == ""++ def test_make_key_without_prefix(self):+ """Test make_key returns just identifier when KEY_PREFIX is empty."""+ assert FastMCPComponent.make_key("my_name") == "my_name"++ def test_tool_has_tool_prefix(self):+ """Test that Tool has 'tool' KEY_PREFIX."""+ assert Tool.KEY_PREFIX == "tool"+ assert Tool.make_key("my_tool") == "tool:my_tool"++ def test_resource_has_resource_prefix(self):+ """Test that Resource has 'resource' KEY_PREFIX."""+ assert Resource.KEY_PREFIX == "resource"+ assert Resource.make_key("file://test.txt") == "resource:file://test.txt"++ def test_template_has_template_prefix(self):+ """Test that ResourceTemplate has 'template' KEY_PREFIX."""+ assert ResourceTemplate.KEY_PREFIX == "template"+ assert ResourceTemplate.make_key("data://{id}") == "template:data://{id}"++ def test_prompt_has_prompt_prefix(self):+ """Test that Prompt has 'prompt' KEY_PREFIX."""+ assert Prompt.KEY_PREFIX == "prompt"+ assert Prompt.make_key("my_prompt") == "prompt:my_prompt"++ def test_tool_key_property(self):+ """Test that Tool.key returns prefixed key."""+ tool = Tool(name="greet", description="A greeting tool", parameters={})+ assert tool.key == "tool:greet"++ def test_prompt_key_property(self):+ """Test that Prompt.key returns prefixed key."""+ prompt = Prompt(name="analyze", description="An analysis prompt")+ assert prompt.key == "prompt:analyze"++ def test_warning_for_missing_key_prefix(self):+ """Test that subclassing without KEY_PREFIX emits a warning."""+ with warnings.catch_warnings(record=True) as w:+ warnings.simplefilter("always")++ class NoPrefix(FastMCPComponent):+ pass++ assert len(w) == 1+ assert "NoPrefix does not define KEY_PREFIX" in str(w[0].message)++ def test_no_warning_when_key_prefix_defined(self):+ """Test that subclassing with KEY_PREFIX does not emit a warning."""+ with warnings.catch_warnings(record=True) as w:+ warnings.simplefilter("always")++ class WithPrefix(FastMCPComponent):+ KEY_PREFIX = "custom"++ assert len(w) == 0+ assert WithPrefix.make_key("test") == "custom:test"++class TestMirroredComponent:"""Tests for the MirroredComponent class."""