From 8596c09fdfbe4a496c174f9b415b6fffe510ef0a Mon Sep 17 00:00:00 2001 From: "marvin-context-protocol[bot]" <225465937+marvin-context-protocol[bot]@users.noreply.github.com> Date: Mon, 19 Jan 2026 21:22:39 -0500 Subject: [PATCH] chore: Update SDK documentation (#2949) Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com> --- docs/docs.json | 5 +- .../fastmcp-server-providers-base.mdx | 10 +- .../fastmcp-server-transforms-visibility.mdx | 35 +++--- docs/python-sdk/fastmcp-utilities-skills.mdx | 114 ++++++++++++++++++ 4 files changed, 140 insertions(+), 24 deletions(-) create mode 100644 docs/python-sdk/fastmcp-utilities-skills.mdx diff --git a/docs/docs.json b/docs/docs.json index cfc5f54e8..fe8935a37 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -563,12 +563,12 @@ "group": "transforms", "pages": [ "python-sdk/fastmcp-server-transforms-__init__", - "python-sdk/fastmcp-server-transforms-visibility", "python-sdk/fastmcp-server-transforms-namespace", "python-sdk/fastmcp-server-transforms-prompts_as_tools", "python-sdk/fastmcp-server-transforms-resources_as_tools", "python-sdk/fastmcp-server-transforms-tool_transform", - "python-sdk/fastmcp-server-transforms-version_filter" + "python-sdk/fastmcp-server-transforms-version_filter", + "python-sdk/fastmcp-server-transforms-visibility" ] } ] @@ -640,6 +640,7 @@ ] }, "python-sdk/fastmcp-utilities-pagination", + "python-sdk/fastmcp-utilities-skills", "python-sdk/fastmcp-utilities-tests", "python-sdk/fastmcp-utilities-timeout", "python-sdk/fastmcp-utilities-types", diff --git a/docs/python-sdk/fastmcp-server-providers-base.mdx b/docs/python-sdk/fastmcp-server-providers-base.mdx index ee80c310f..6db55a107 100644 --- a/docs/python-sdk/fastmcp-server-providers-base.mdx +++ b/docs/python-sdk/fastmcp-server-providers-base.mdx @@ -121,7 +121,7 @@ get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None Get tool by transformed name with all transforms applied. Note: This method does NOT filter disabled components. The Server -(FastMCP) performs visibility filtering after all transforms complete, +(FastMCP) performs enabled filtering after all transforms complete, allowing session-level transforms to override provider-level disables. **Args:** @@ -152,7 +152,7 @@ get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | N Get resource by transformed URI with all transforms applied. Note: This method does NOT filter disabled components. The Server -(FastMCP) performs visibility filtering after all transforms complete. +(FastMCP) performs enabled filtering after all transforms complete. **Args:** - `uri`: The transformed resource URI to look up. @@ -182,7 +182,7 @@ get_resource_template(self, uri: str, version: VersionSpec | None = None) -> Res Get resource template by transformed URI with all transforms applied. Note: This method does NOT filter disabled components. The Server -(FastMCP) performs visibility filtering after all transforms complete. +(FastMCP) performs enabled filtering after all transforms complete. **Args:** - `uri`: The transformed template URI to look up. @@ -212,7 +212,7 @@ get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None Get prompt by transformed name with all transforms applied. Note: This method does NOT filter disabled components. The Server -(FastMCP) performs visibility filtering after all transforms complete. +(FastMCP) performs enabled filtering after all transforms complete. **Args:** - `name`: The transformed prompt name to look up. @@ -261,7 +261,7 @@ enable(self) -> Self Enable components matching all specified criteria. -Adds an enabled transform that marks matching components as enabled. +Adds a visibility transform that marks matching components as enabled. Later transforms override earlier ones, so enable after disable makes the component enabled. diff --git a/docs/python-sdk/fastmcp-server-transforms-visibility.mdx b/docs/python-sdk/fastmcp-server-transforms-visibility.mdx index 383eb0cc4..4fcf9dbe8 100644 --- a/docs/python-sdk/fastmcp-server-transforms-visibility.mdx +++ b/docs/python-sdk/fastmcp-server-transforms-visibility.mdx @@ -15,7 +15,7 @@ Final filtering happens at the Provider level. ## Functions -### `is_enabled` +### `is_enabled` ```python is_enabled(component: FastMCPComponent) -> bool @@ -37,7 +37,7 @@ Returns False if visibility mark is False. - True if component should be enabled/visible to clients. -### `get_visibility_rules` +### `get_visibility_rules` ```python get_visibility_rules(context: Context) -> list[dict[str, Any]] @@ -47,7 +47,7 @@ get_visibility_rules(context: Context) -> list[dict[str, Any]] Load visibility rule dicts from session state. -### `save_visibility_rules` +### `save_visibility_rules` ```python save_visibility_rules(context: Context, rules: list[dict[str, Any]]) -> None @@ -64,7 +64,7 @@ If None, sends notifications for all types (safe default). If provided, only sends notifications for specified types. -### `create_visibility_transforms` +### `create_visibility_transforms` ```python create_visibility_transforms(rules: list[dict[str, Any]]) -> list[Visibility] @@ -74,7 +74,7 @@ create_visibility_transforms(rules: list[dict[str, Any]]) -> list[Visibility] Convert rule dicts to Visibility transforms. -### `get_session_transforms` +### `get_session_transforms` ```python get_session_transforms(context: Context) -> list[Visibility] @@ -84,7 +84,7 @@ get_session_transforms(context: Context) -> list[Visibility] Get session-specific Visibility transforms from state store. -### `enable_components` +### `enable_components` ```python enable_components(context: Context) -> None @@ -110,7 +110,7 @@ ResourceListChangedNotification, and PromptListChangedNotification. - `match_all`: If True, matches all components regardless of other criteria. -### `disable_components` +### `disable_components` ```python disable_components(context: Context) -> None @@ -136,7 +136,7 @@ ResourceListChangedNotification, and PromptListChangedNotification. - `match_all`: If True, matches all components regardless of other criteria. -### `reset_visibility` +### `reset_visibility` ```python reset_visibility(context: Context) -> None @@ -154,7 +154,7 @@ ResourceListChangedNotification, and PromptListChangedNotification. - `context`: The context for this session. -### `apply_session_transforms` +### `apply_session_transforms` ```python apply_session_transforms(components: Sequence[ComponentT]) -> Sequence[ComponentT] @@ -188,7 +188,7 @@ Final filtering happens at the Provider level after all transforms run. **Methods:** -#### `list_tools` +#### `list_tools` ```python list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool] @@ -197,7 +197,7 @@ list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool] Mark tools by visibility state. -#### `get_tool` +#### `get_tool` ```python get_tool(self, name: str, call_next: GetToolNext) -> Tool | None @@ -206,7 +206,7 @@ get_tool(self, name: str, call_next: GetToolNext) -> Tool | None Mark tool if found. -#### `list_resources` +#### `list_resources` ```python list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource] @@ -215,7 +215,7 @@ list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource] Mark resources by visibility state. -#### `get_resource` +#### `get_resource` ```python get_resource(self, uri: str, call_next: GetResourceNext) -> Resource | None @@ -224,7 +224,7 @@ get_resource(self, uri: str, call_next: GetResourceNext) -> Resource | None Mark resource if found. -#### `list_resource_templates` +#### `list_resource_templates` ```python list_resource_templates(self, templates: Sequence[ResourceTemplate]) -> Sequence[ResourceTemplate] @@ -233,7 +233,7 @@ list_resource_templates(self, templates: Sequence[ResourceTemplate]) -> Sequence Mark resource templates by visibility state. -#### `get_resource_template` +#### `get_resource_template` ```python get_resource_template(self, uri: str, call_next: GetResourceTemplateNext) -> ResourceTemplate | None @@ -242,7 +242,7 @@ get_resource_template(self, uri: str, call_next: GetResourceTemplateNext) -> Res Mark resource template if found. -#### `list_prompts` +#### `list_prompts` ```python list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt] @@ -251,10 +251,11 @@ list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt] Mark prompts by visibility state. -#### `get_prompt` +#### `get_prompt` ```python get_prompt(self, name: str, call_next: GetPromptNext) -> Prompt | None ``` Mark prompt if found. + diff --git a/docs/python-sdk/fastmcp-utilities-skills.mdx b/docs/python-sdk/fastmcp-utilities-skills.mdx new file mode 100644 index 000000000..32aed81ca --- /dev/null +++ b/docs/python-sdk/fastmcp-utilities-skills.mdx @@ -0,0 +1,114 @@ +--- +title: skills +sidebarTitle: skills +--- + +# `fastmcp.utilities.skills` + + +Client utilities for discovering and downloading skills from MCP servers. + +## Functions + +### `list_skills` + +```python +list_skills(client: Client) -> list[SkillSummary] +``` + + +List all available skills from an MCP server. + +Discovers skills by finding resources with URIs matching the +`skill://{name}/SKILL.md` pattern. + +**Args:** +- `client`: Connected FastMCP client + +**Returns:** +- List of SkillSummary objects with name, description, and URI + + +### `get_skill_manifest` + +```python +get_skill_manifest(client: Client, skill_name: str) -> SkillManifest +``` + + +Get the manifest for a specific skill. + +**Args:** +- `client`: Connected FastMCP client +- `skill_name`: Name of the skill + +**Returns:** +- SkillManifest with file listing + +**Raises:** +- `ValueError`: If manifest cannot be read or parsed + + +### `download_skill` + +```python +download_skill(client: Client, skill_name: str, target_dir: str | Path) -> Path +``` + + +Download a skill and all its files to a local directory. + +Creates a subdirectory named after the skill containing all files. + +**Args:** +- `client`: Connected FastMCP client +- `skill_name`: Name of the skill to download +- `target_dir`: Directory where skill folder will be created +- `overwrite`: If True, overwrite existing skill directory. If False +(default), raise FileExistsError if directory exists. + +**Returns:** +- Path to the downloaded skill directory + +**Raises:** +- `ValueError`: If skill cannot be found or downloaded +- `FileExistsError`: If skill directory exists and overwrite=False + + +### `sync_skills` + +```python +sync_skills(client: Client, target_dir: str | Path) -> list[Path] +``` + + +Download all available skills from a server. + +**Args:** +- `client`: Connected FastMCP client +- `target_dir`: Directory where skill folders will be created +- `overwrite`: If True, overwrite existing files + +**Returns:** +- List of paths to downloaded skill directories + + +## Classes + +### `SkillSummary` + + +Summary information about a skill available on a server. + + +### `SkillFile` + + +Information about a file within a skill. + + +### `SkillManifest` + + +Full manifest of a skill including all files. +