Skip to content

πŸš€ 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.mdx
index 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 Transport
diff --git a/docs/servers/skills.mdx b/docs/servers/skills.mdx
index 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 extension
diff --git a/fastmcp_slim/fastmcp/utilities/skills.py b/fastmcp_slim/fastmcp/utilities/skills.py
index 73b859548..80baefae4 100644
--- a/fastmcp_slim/fastmcp/utilities/skills.py
+++ b/fastmcp_slim/fastmcp/utilities/skills.py
@@ -4,12 +4,15 @@ from __future__ import annotations
import base64
import json
+import warnings
from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING
import 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:
```python
from fastmcp import Client
- from fastmcp.utilities.skills import list_skills
+ from fastmcp.utilities.skills import list_skill_summaries
async 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.py
index 90c6f5726..b5309c79c 100644
--- a/tests/utilities/test_skills.py
+++ b/tests/utilities/test_skills.py
@@ -11,6 +11,7 @@ import pytest
from mcp_types import BlobResourceContents, TextResourceContents
from fastmcp import Client, FastMCP
+from fastmcp._warnings import FastMCPDeprecationWarning
from fastmcp.server.providers.skills import SkillsDirectoryProvider
from 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) == 3
names = {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(