diff --git a/docs/docs.json b/docs/docs.json index b1db8d756..af88bb341 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -478,7 +478,22 @@ "python-sdk/fastmcp-server-providers-fastmcp_provider", "python-sdk/fastmcp-server-providers-filesystem", "python-sdk/fastmcp-server-providers-filesystem_discovery", - "python-sdk/fastmcp-server-providers-local_provider", + { + "group": "local_provider", + "pages": [ + "python-sdk/fastmcp-server-providers-local_provider-__init__", + { + "group": "decorators", + "pages": [ + "python-sdk/fastmcp-server-providers-local_provider-decorators-__init__", + "python-sdk/fastmcp-server-providers-local_provider-decorators-prompts", + "python-sdk/fastmcp-server-providers-local_provider-decorators-resources", + "python-sdk/fastmcp-server-providers-local_provider-decorators-tools" + ] + }, + "python-sdk/fastmcp-server-providers-local_provider-local_provider" + ] + }, { "group": "openapi", "pages": [ diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-__init__.mdx new file mode 100644 index 000000000..5fe082a63 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-providers-local_provider-__init__.mdx @@ -0,0 +1,13 @@ +--- +title: __init__ +sidebarTitle: __init__ +--- + +# `fastmcp.server.providers.local_provider` + + +LocalProvider for locally-defined MCP components. + +This module provides the `LocalProvider` class that manages tools, resources, +templates, and prompts registered via decorators or direct methods. + diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-__init__.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-__init__.mdx new file mode 100644 index 000000000..d6009a6de --- /dev/null +++ b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-__init__.mdx @@ -0,0 +1,13 @@ +--- +title: __init__ +sidebarTitle: __init__ +--- + +# `fastmcp.server.providers.local_provider.decorators` + + +Decorator mixins for LocalProvider. + +This module provides mixin classes that add decorator functionality +to LocalProvider for tools, resources, templates, and prompts. + diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-prompts.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-prompts.mdx new file mode 100644 index 000000000..5db75f648 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-prompts.mdx @@ -0,0 +1,81 @@ +--- +title: prompts +sidebarTitle: prompts +--- + +# `fastmcp.server.providers.local_provider.decorators.prompts` + + +Prompt decorator mixin for LocalProvider. + +This module provides the PromptDecoratorMixin class that adds prompt +registration functionality to LocalProvider. + + +## Classes + +### `PromptDecoratorMixin` + + +Mixin class providing prompt decorator functionality for LocalProvider. + +This mixin contains all methods related to: +- Prompt registration via add_prompt() +- Prompt decorator (@provider.prompt) + + +**Methods:** + +#### `add_prompt` + +```python +add_prompt(self: LocalProvider, prompt: Prompt | Callable[..., Any]) -> Prompt +``` + +Add a prompt to this provider's storage. + +Accepts either a Prompt object or a decorated function with __fastmcp__ metadata. + + +#### `prompt` + +```python +prompt(self: LocalProvider, name_or_fn: AnyFunction) -> FunctionPrompt +``` + +#### `prompt` + +```python +prompt(self: LocalProvider, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionPrompt] +``` + +#### `prompt` + +```python +prompt(self: LocalProvider, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt | partial[Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt] +``` + +Decorator to register a prompt. + +This decorator supports multiple calling patterns: +- @provider.prompt (without parentheses) +- @provider.prompt() (with empty parentheses) +- @provider.prompt("custom_name") (with name as first argument) +- @provider.prompt(name="custom_name") (with name as keyword argument) +- provider.prompt(function, name="custom_name") (direct function call) + +**Args:** +- `name_or_fn`: Either a function (when used as @prompt), a string name, or None +- `name`: Optional name for the prompt (keyword-only, alternative to name_or_fn) +- `title`: Optional title for the prompt +- `description`: Optional description of what the prompt does +- `icons`: Optional icons for the prompt +- `tags`: Optional set of tags for categorizing the prompt +- `enabled`: Whether the prompt is enabled (default True). If False, adds to blocklist. +- `meta`: Optional meta information about the prompt +- `task`: Optional task configuration for background execution +- `auth`: Optional authorization checks for the prompt + +**Returns:** +- The registered FunctionPrompt or a decorator function. + diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-resources.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-resources.mdx new file mode 100644 index 000000000..dd5861dcb --- /dev/null +++ b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-resources.mdx @@ -0,0 +1,77 @@ +--- +title: resources +sidebarTitle: resources +--- + +# `fastmcp.server.providers.local_provider.decorators.resources` + + +Resource decorator mixin for LocalProvider. + +This module provides the ResourceDecoratorMixin class that adds resource +and template registration functionality to LocalProvider. + + +## Classes + +### `ResourceDecoratorMixin` + + +Mixin class providing resource decorator functionality for LocalProvider. + +This mixin contains all methods related to: +- Resource registration via add_resource() +- Resource template registration via add_template() +- Resource decorator (@provider.resource) + + +**Methods:** + +#### `add_resource` + +```python +add_resource(self: LocalProvider, resource: Resource | ResourceTemplate | Callable[..., Any]) -> Resource | ResourceTemplate +``` + +Add a resource to this provider's storage. + +Accepts either a Resource/ResourceTemplate object or a decorated function with __fastmcp__ metadata. + + +#### `add_template` + +```python +add_template(self: LocalProvider, template: ResourceTemplate) -> ResourceTemplate +``` + +Add a resource template to this provider's storage. + + +#### `resource` + +```python +resource(self: LocalProvider, uri: str) -> Callable[[AnyFunction], Resource | ResourceTemplate | AnyFunction] +``` + +Decorator to register a function as a resource. + +If the URI contains parameters (e.g. "resource://{param}") or the function +has parameters, it will be registered as a template resource. + +**Args:** +- `uri`: URI for the resource (e.g. "resource\://my-resource" or "resource\://{param}") +- `name`: Optional name for the resource +- `title`: Optional title for the resource +- `description`: Optional description of the resource +- `icons`: Optional icons for the resource +- `mime_type`: Optional MIME type for the resource +- `tags`: Optional set of tags for categorizing the resource +- `enabled`: Whether the resource is enabled (default True). If False, adds to blocklist. +- `annotations`: Optional annotations about the resource's behavior +- `meta`: Optional meta information about the resource +- `task`: Optional task configuration for background execution +- `auth`: Optional authorization checks for the resource + +**Returns:** +- A decorator function. + diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-tools.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-tools.mdx new file mode 100644 index 000000000..fd501251e --- /dev/null +++ b/docs/python-sdk/fastmcp-server-providers-local_provider-decorators-tools.mdx @@ -0,0 +1,84 @@ +--- +title: tools +sidebarTitle: tools +--- + +# `fastmcp.server.providers.local_provider.decorators.tools` + + +Tool decorator mixin for LocalProvider. + +This module provides the ToolDecoratorMixin class that adds tool +registration functionality to LocalProvider. + + +## Classes + +### `ToolDecoratorMixin` + + +Mixin class providing tool decorator functionality for LocalProvider. + +This mixin contains all methods related to: +- Tool registration via add_tool() +- Tool decorator (@provider.tool) + + +**Methods:** + +#### `add_tool` + +```python +add_tool(self: LocalProvider, tool: Tool | Callable[..., Any]) -> Tool +``` + +Add a tool to this provider's storage. + +Accepts either a Tool object or a decorated function with __fastmcp__ metadata. + + +#### `tool` + +```python +tool(self: LocalProvider, name_or_fn: AnyFunction) -> FunctionTool +``` + +#### `tool` + +```python +tool(self: LocalProvider, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionTool] +``` + +#### `tool` + +```python +tool(self: LocalProvider, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool | partial[Callable[[AnyFunction], FunctionTool] | FunctionTool] +``` + +Decorator to register a tool. + +This decorator supports multiple calling patterns: +- @provider.tool (without parentheses) +- @provider.tool() (with empty parentheses) +- @provider.tool("custom_name") (with name as first argument) +- @provider.tool(name="custom_name") (with name as keyword argument) +- provider.tool(function, name="custom_name") (direct function call) + +**Args:** +- `name_or_fn`: Either a function (when used as @tool), a string name, or None +- `name`: Optional name for the tool (keyword-only, alternative to name_or_fn) +- `title`: Optional title for the tool +- `description`: Optional description of what the tool does +- `icons`: Optional icons for the tool +- `tags`: Optional set of tags for categorizing the tool +- `output_schema`: Optional JSON schema for the tool's output +- `annotations`: Optional annotations about the tool's behavior +- `exclude_args`: Optional list of argument names to exclude from the tool schema +- `meta`: Optional meta information about the tool +- `enabled`: Whether the tool is enabled (default True). If False, adds to blocklist. +- `task`: Optional task configuration for background execution +- `serializer`: Deprecated. Return ToolResult from your tools for full control over serialization. + +**Returns:** +- The registered FunctionTool or a decorator function. + diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider-local_provider.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider-local_provider.mdx new file mode 100644 index 000000000..3fc46b59f --- /dev/null +++ b/docs/python-sdk/fastmcp-server-providers-local_provider-local_provider.mdx @@ -0,0 +1,125 @@ +--- +title: local_provider +sidebarTitle: local_provider +--- + +# `fastmcp.server.providers.local_provider.local_provider` + + +LocalProvider for locally-defined MCP components. + +This module provides the `LocalProvider` class that manages tools, resources, +templates, and prompts registered via decorators or direct methods. + +LocalProvider can be used standalone and attached to multiple servers: + +```python +from fastmcp.server.providers import LocalProvider + +# Create a reusable provider with tools +provider = LocalProvider() + +@provider.tool +def greet(name: str) -> str: + return f"Hello, {name}!" + +# Attach to any server +from fastmcp import FastMCP +server1 = FastMCP("Server1", providers=[provider]) +server2 = FastMCP("Server2", providers=[provider]) +``` + + +## Classes + +### `LocalProvider` + + +Provider for locally-defined components. + +Supports decorator-based registration (`@provider.tool`, `@provider.resource`, +`@provider.prompt`) and direct object registration methods. + +When used standalone, LocalProvider uses default settings. When attached +to a FastMCP server via the server's decorators, server-level settings +like `_tool_serializer` and `_support_tasks_by_default` are injected. + + +**Methods:** + +#### `remove_tool` + +```python +remove_tool(self, name: str, version: str | None = None) -> None +``` + +Remove tool(s) from this provider's storage. + +**Args:** +- `name`: The tool name. +- `version`: If None, removes ALL versions. If specified, removes only that version. + +**Raises:** +- `KeyError`: If no matching tool is found. + + +#### `remove_resource` + +```python +remove_resource(self, uri: str, version: str | None = None) -> None +``` + +Remove resource(s) from this provider's storage. + +**Args:** +- `uri`: The resource URI. +- `version`: If None, removes ALL versions. If specified, removes only that version. + +**Raises:** +- `KeyError`: If no matching resource is found. + + +#### `remove_template` + +```python +remove_template(self, uri_template: str, version: str | None = None) -> None +``` + +Remove resource template(s) from this provider's storage. + +**Args:** +- `uri_template`: The template URI pattern. +- `version`: If None, removes ALL versions. If specified, removes only that version. + +**Raises:** +- `KeyError`: If no matching template is found. + + +#### `remove_prompt` + +```python +remove_prompt(self, name: str, version: str | None = None) -> None +``` + +Remove prompt(s) from this provider's storage. + +**Args:** +- `name`: The prompt name. +- `version`: If None, removes ALL versions. If specified, removes only that version. + +**Raises:** +- `KeyError`: If no matching prompt is found. + + +#### `get_tasks` + +```python +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 via +decorators and custom Tool/Resource/Prompt subclasses. + diff --git a/docs/python-sdk/fastmcp-server-providers-local_provider.mdx b/docs/python-sdk/fastmcp-server-providers-local_provider.mdx deleted file mode 100644 index 5fa847d37..000000000 --- a/docs/python-sdk/fastmcp-server-providers-local_provider.mdx +++ /dev/null @@ -1,285 +0,0 @@ ---- -title: local_provider -sidebarTitle: local_provider ---- - -# `fastmcp.server.providers.local_provider` - - -LocalProvider for locally-defined MCP components. - -This module provides the `LocalProvider` class that manages tools, resources, -templates, and prompts registered via decorators or direct methods. - -LocalProvider can be used standalone and attached to multiple servers: - -```python -from fastmcp.server.providers import LocalProvider - -# Create a reusable provider with tools -provider = LocalProvider() - -@provider.tool -def greet(name: str) -> str: - return f"Hello, {name}!" - -# Attach to any server -from fastmcp import FastMCP -server1 = FastMCP("Server1", providers=[provider]) -server2 = FastMCP("Server2", providers=[provider]) -``` - - -## Classes - -### `LocalProvider` - - -Provider for locally-defined components. - -Supports decorator-based registration (`@provider.tool`, `@provider.resource`, -`@provider.prompt`) and direct object registration methods. - -When used standalone, LocalProvider uses default settings. When attached -to a FastMCP server via the server's decorators, server-level settings -like `_tool_serializer` and `_support_tasks_by_default` are injected. - - -**Methods:** - -#### `add_tool` - -```python -add_tool(self, tool: Tool | Callable[..., Any]) -> Tool -``` - -Add a tool to this provider's storage. - -Accepts either a Tool object or a decorated function with __fastmcp__ metadata. - - -#### `remove_tool` - -```python -remove_tool(self, name: str, version: str | None = None) -> None -``` - -Remove tool(s) from this provider's storage. - -**Args:** -- `name`: The tool name. -- `version`: If None, removes ALL versions. If specified, removes only that version. - -**Raises:** -- `KeyError`: If no matching tool is found. - - -#### `add_resource` - -```python -add_resource(self, resource: Resource | ResourceTemplate | Callable[..., Any]) -> Resource | ResourceTemplate -``` - -Add a resource to this provider's storage. - -Accepts either a Resource/ResourceTemplate object or a decorated function with __fastmcp__ metadata. - - -#### `remove_resource` - -```python -remove_resource(self, uri: str, version: str | None = None) -> None -``` - -Remove resource(s) from this provider's storage. - -**Args:** -- `uri`: The resource URI. -- `version`: If None, removes ALL versions. If specified, removes only that version. - -**Raises:** -- `KeyError`: If no matching resource is found. - - -#### `add_template` - -```python -add_template(self, template: ResourceTemplate) -> ResourceTemplate -``` - -Add a resource template to this provider's storage. - - -#### `remove_template` - -```python -remove_template(self, uri_template: str, version: str | None = None) -> None -``` - -Remove resource template(s) from this provider's storage. - -**Args:** -- `uri_template`: The template URI pattern. -- `version`: If None, removes ALL versions. If specified, removes only that version. - -**Raises:** -- `KeyError`: If no matching template is found. - - -#### `add_prompt` - -```python -add_prompt(self, prompt: Prompt | Callable[..., Any]) -> Prompt -``` - -Add a prompt to this provider's storage. - -Accepts either a Prompt object or a decorated function with __fastmcp__ metadata. - - -#### `remove_prompt` - -```python -remove_prompt(self, name: str, version: str | None = None) -> None -``` - -Remove prompt(s) from this provider's storage. - -**Args:** -- `name`: The prompt name. -- `version`: If None, removes ALL versions. If specified, removes only that version. - -**Raises:** -- `KeyError`: If no matching prompt is found. - - -#### `get_tasks` - -```python -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 via -decorators and custom Tool/Resource/Prompt subclasses. - - -#### `tool` - -```python -tool(self, name_or_fn: AnyFunction) -> FunctionTool -``` - -#### `tool` - -```python -tool(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionTool] -``` - -#### `tool` - -```python -tool(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool | partial[Callable[[AnyFunction], FunctionTool] | FunctionTool] -``` - -Decorator to register a tool. - -This decorator supports multiple calling patterns: -- @provider.tool (without parentheses) -- @provider.tool() (with empty parentheses) -- @provider.tool("custom_name") (with name as first argument) -- @provider.tool(name="custom_name") (with name as keyword argument) -- provider.tool(function, name="custom_name") (direct function call) - -**Args:** -- `name_or_fn`: Either a function (when used as @tool), a string name, or None -- `name`: Optional name for the tool (keyword-only, alternative to name_or_fn) -- `title`: Optional title for the tool -- `description`: Optional description of what the tool does -- `icons`: Optional icons for the tool -- `tags`: Optional set of tags for categorizing the tool -- `output_schema`: Optional JSON schema for the tool's output -- `annotations`: Optional annotations about the tool's behavior -- `exclude_args`: Optional list of argument names to exclude from the tool schema -- `meta`: Optional meta information about the tool -- `enabled`: Whether the tool is enabled (default True). If False, adds to blocklist. -- `task`: Optional task configuration for background execution -- `serializer`: Deprecated. Return ToolResult from your tools for full control over serialization. - -**Returns:** -- The registered FunctionTool or a decorator function. - - -#### `resource` - -```python -resource(self, uri: str) -> Callable[[AnyFunction], Resource | ResourceTemplate | AnyFunction] -``` - -Decorator to register a function as a resource. - -If the URI contains parameters (e.g. "resource://{param}") or the function -has parameters, it will be registered as a template resource. - -**Args:** -- `uri`: URI for the resource (e.g. "resource\://my-resource" or "resource\://{param}") -- `name`: Optional name for the resource -- `title`: Optional title for the resource -- `description`: Optional description of the resource -- `icons`: Optional icons for the resource -- `mime_type`: Optional MIME type for the resource -- `tags`: Optional set of tags for categorizing the resource -- `enabled`: Whether the resource is enabled (default True). If False, adds to blocklist. -- `annotations`: Optional annotations about the resource's behavior -- `meta`: Optional meta information about the resource -- `task`: Optional task configuration for background execution -- `auth`: Optional authorization checks for the resource - -**Returns:** -- A decorator function. - - -#### `prompt` - -```python -prompt(self, name_or_fn: AnyFunction) -> FunctionPrompt -``` - -#### `prompt` - -```python -prompt(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionPrompt] -``` - -#### `prompt` - -```python -prompt(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt | partial[Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt] -``` - -Decorator to register a prompt. - -This decorator supports multiple calling patterns: -- @provider.prompt (without parentheses) -- @provider.prompt() (with empty parentheses) -- @provider.prompt("custom_name") (with name as first argument) -- @provider.prompt(name="custom_name") (with name as keyword argument) -- provider.prompt(function, name="custom_name") (direct function call) - -**Args:** -- `name_or_fn`: Either a function (when used as @prompt), a string name, or None -- `name`: Optional name for the prompt (keyword-only, alternative to name_or_fn) -- `title`: Optional title for the prompt -- `description`: Optional description of what the prompt does -- `icons`: Optional icons for the prompt -- `tags`: Optional set of tags for categorizing the prompt -- `enabled`: Whether the prompt is enabled (default True). If False, adds to blocklist. -- `meta`: Optional meta information about the prompt -- `task`: Optional task configuration for background execution -- `auth`: Optional authorization checks for the prompt - -**Returns:** -- The registered FunctionPrompt or a decorator function. -