fastmcp.utilities.components

Functions

get_fastmcp_metadata ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L26" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_fastmcp_metadata(meta: dict[str, Any] | None) -> FastMCPMeta

Extract FastMCP metadata from a component's meta dict.

Handles both the current fastmcp namespace and the legacy _fastmcp namespace for compatibility with older FastMCP servers.

Classes

FastMCPMeta ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

FastMCPComponent ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Base class for FastMCP tools, prompts, resources, and resource templates.

Methods:

make_key ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L125" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

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"

key ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L139" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

key(self) -> str

The globally unique lookup key for this component.

Format: "{key_prefix}:{identifier}@{version}" or "{key_prefix}:{identifier}@" e.g. "tool:my_tool@v2", "tool:my_tool@", "resource:file://x.txt@"

The @ suffix is ALWAYS present to enable unambiguous parsing of keys (URIs may contain @ characters, so we always include the delimiter).

Subclasses should override this to use their specific identifier. Base implementation uses name.

Prefer .key over ad-hoc name or uri or uri_template logic for any cross-component identity work (dedupe, grouping, collision detection, lookup tables). It encodes type, identifier, and version, so variants of the same component don't falsely collide with each other, and cross-type identifiers (e.g. a tool and a resource both named "foo") can't clash.

get_meta ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L161" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_meta(self) -> dict[str, Any]

Get the meta information about the component.

Returns a dict that always includes a fastmcp key containing:

• tags: sorted list of component tags
• version: component version (only if set)

Internal keys (prefixed with _) are stripped from the fastmcp namespace.

enable ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L209" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

enable(self) -> None

Removed in 3.0. Use server.enable(keys=[...]) instead.

disable ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L216" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

disable(self) -> None

Removed in 3.0. Use server.disable(keys=[...]) instead.

copy ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L223" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

copy(self) -> Self

Create a copy of the component.

register_with_docket ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L227" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

register_with_docket(self, docket: Docket) -> None

Register this component with docket for background execution.

No-ops if task_config.mode is "forbidden". Subclasses override to register their callable (self.run, self.read, self.render, or self.fn).

add_to_docket ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

add_to_docket(self, docket: Docket, *args: Any, **kwargs: Any) -> Execution

Schedule this component for background execution via docket.

Subclasses override this to handle their specific calling conventions:

• Tool: add_to_docket(docket, arguments: dict, **kwargs)
• Resource: add_to_docket(docket, **kwargs)
• ResourceTemplate: add_to_docket(docket, params: dict, **kwargs)
• Prompt: add_to_docket(docket, arguments: dict | None, **kwargs)

The **kwargs are passed through to docket.add() (e.g., key=task_key).

get_span_attributes ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/utilities/components.py#L257" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

get_span_attributes(self) -> dict[str, Any]

Return span attributes for telemetry.

Subclasses should call super() and merge their specific attributes.