π The fast, Pythonic way to build MCP servers and clients.
Rename the resource-era list_skills helper to list_skill_summaries (#6051)
nate nowackf086fc32d826
diff --git a/docs/clients/client.mdx b/docs/clients/client.mdxindex 149a21935..601ef0e04 100644--- a/docs/clients/client.mdx+++ b/docs/clients/client.mdx@@ -60,7 +60,7 @@ Pass your server instance to `Client(server)` in a test to exercise tool discove### Discovering and Downloading Skills-An agent can also use the client to retrieve instructions and supporting files from servers that expose skills as resources. The [skills client utilities](/servers/skills#install-skills-into-a-local-agent) provide `list_skills()` for discovery, `get_skill_manifest()` for inspecting files, and `download_skill()` or `sync_skills()` for saving them locally.+An agent can also use the client to retrieve instructions and supporting files from servers that expose skills as resources. The [skills client utilities](/servers/skills#install-skills-into-a-local-agent) provide `list_skill_summaries()` for discovery, `get_skill_manifest()` for inspecting files, and `download_skill()` or `sync_skills()` for saving them locally.## Choosing a Transportdiff --git a/docs/servers/skills.mdx b/docs/servers/skills.mdxindex 602eaa43f..6ca81b03d 100644--- a/docs/servers/skills.mdx+++ b/docs/servers/skills.mdx@@ -140,7 +140,7 @@ async def main() -> None:asyncio.run(main())```-`fastmcp.utilities.skills` also provides `list_skills()`, which lists skill names from the resource listing, and `get_skill_manifest()`, which reads one manifest. These helpers work with any server that publishes skills as resources, with or without discovery.+`fastmcp.utilities.skills` also provides `list_skill_summaries()`, which lists skill names from the resource listing, and `get_skill_manifest()`, which reads one manifest. These helpers work with any server that publishes skills as resources, with or without discovery. Earlier releases named the summary helper `list_skills()`; that name still works with a deprecation warning. It is unrelated to `client.list_skills()`, described below.## Discover skills with the Skills extensiondiff --git a/fastmcp_slim/fastmcp/utilities/skills.py b/fastmcp_slim/fastmcp/utilities/skills.pyindex 73b859548..80baefae4 100644--- a/fastmcp_slim/fastmcp/utilities/skills.py+++ b/fastmcp_slim/fastmcp/utilities/skills.py@@ -4,12 +4,15 @@ from __future__ import annotationsimport base64import json+import warningsfrom dataclasses import dataclassfrom pathlib import Pathfrom typing import TYPE_CHECKINGimport mcp_types+from fastmcp._warnings import FastMCPDeprecationWarning+if TYPE_CHECKING:from fastmcp.client import Client@@ -40,11 +43,13 @@ class SkillManifest:files: list[SkillFile]-async def list_skills(client: Client) -> list[SkillSummary]:- """List all available skills from an MCP server.+async def list_skill_summaries(client: Client) -> list[SkillSummary]:+ """List the skills a server publishes as resources.Discovers skills by finding resources with URIs matching the- `skill://{name}/SKILL.md` pattern.+ `skill://{name}/SKILL.md` pattern, so it works with any server that+ serves skills as resources. For the Skills extension's `skills/list`,+ use `Client.list_skills()` with `SkillsClientExtension` instead.Args:client: Connected FastMCP client@@ -55,10 +60,10 @@ async def list_skills(client: Client) -> list[SkillSummary]:Example:```pythonfrom fastmcp import Client- from fastmcp.utilities.skills import list_skills+ from fastmcp.utilities.skills import list_skill_summariesasync with Client("http://skills-server/mcp") as client:- skills = await list_skills(client)+ skills = await list_skill_summaries(client)for skill in skills:print(f"{skill.name}: {skill.description}")```@@ -84,6 +89,22 @@ async def list_skills(client: Client) -> list[SkillSummary]:return skills+async def list_skills(client: Client) -> list[SkillSummary]:+ """Deprecated alias for `list_skill_summaries`.++ The name collided with `Client.list_skills()`, which sends the Skills+ extension's `skills/list` request and returns different results.+ """+ warnings.warn(+ "`fastmcp.utilities.skills.list_skills` is deprecated; use "+ "`list_skill_summaries`. For Skills extension discovery, use "+ "`Client.list_skills()` with `SkillsClientExtension`.",+ FastMCPDeprecationWarning,+ stacklevel=2,+ )+ return await list_skill_summaries(client)++async def get_skill_manifest(client: Client, skill_name: str) -> SkillManifest:"""Get the manifest for a specific skill.@@ -241,7 +262,7 @@ async def sync_skills(print(f"Downloaded {len(paths)} skills")```"""- skills = await list_skills(client)+ skills = await list_skill_summaries(client)downloaded = []for skill in skills:diff --git a/tests/utilities/test_skills.py b/tests/utilities/test_skills.pyindex 90c6f5726..b5309c79c 100644--- a/tests/utilities/test_skills.py+++ b/tests/utilities/test_skills.py@@ -11,6 +11,7 @@ import pytestfrom mcp_types import BlobResourceContents, TextResourceContentsfrom fastmcp import Client, FastMCP+from fastmcp._warnings import FastMCPDeprecationWarningfrom fastmcp.server.providers.skills import SkillsDirectoryProviderfrom fastmcp.utilities.skills import (SkillFile,@@ -18,6 +19,7 @@ from fastmcp.utilities.skills import (SkillSummary,download_skill,get_skill_manifest,+ list_skill_summaries,list_skills,sync_skills,)@@ -101,10 +103,18 @@ def skills_server(skills_dir: Path) -> FastMCP:return mcp-class TestListSkills:+class TestListSkillSummaries:+ async def test_list_skills_is_a_deprecated_alias(self, skills_server: FastMCP):+ async with Client(skills_server) as client:+ with pytest.warns(FastMCPDeprecationWarning, match="list_skill_summaries"):+ skills = await list_skills(client)+ expected = await list_skill_summaries(client)++ assert skills == expected+async def test_lists_available_skills(self, skills_server: FastMCP):async with Client(skills_server) as client:- skills = await list_skills(client)+ skills = await list_skill_summaries(client)assert len(skills) == 3names = {s.name for s in skills}@@ -112,7 +122,7 @@ class TestListSkills:async def test_returns_skill_summary_objects(self, skills_server: FastMCP):async with Client(skills_server) as client:- skills = await list_skills(client)+ skills = await list_skill_summaries(client)for skill in skills:assert isinstance(skill, SkillSummary)@@ -122,7 +132,7 @@ class TestListSkills:async def test_includes_descriptions(self, skills_server: FastMCP):async with Client(skills_server) as client:- skills = await list_skills(client)+ skills = await list_skill_summaries(client)by_name = {s.name: s for s in skills}assert by_name["pdf-processing"].description == "Process PDF documents"@@ -131,7 +141,7 @@ class TestListSkills:async def test_empty_server_returns_empty_list(self):mcp = FastMCP("Empty")async with Client(mcp) as client:- skills = await list_skills(client)+ skills = await list_skill_summaries(client)assert skills == []@@ -155,7 +165,7 @@ class TestListSkills:return "# Wrong suffix"async with Client(mcp) as client:- skills = await list_skills(client)+ skills = await list_skill_summaries(client)assert skills == [SkillSummary(