Python: Add MCP-based skills discovery (McpSkillsSource) (#6169)

* Add MCP-based skills discovery (McpSkill, McpSkillsSource, McpSkillResource) Implement Agent Skills discovery over MCP following the SEP-2640 convention: - McpSkillsSource: reads skill://index.json to discover skills served by an MCP server - McpSkill: lazily fetches SKILL.md content via resources/read on demand - McpSkillResource: wraps MCP resource results (text and binary) - Path traversal protection in get_resource for defense in depth - Samples for Foundry Toolbox and standalone MCP skills server - Comprehensive unit tests (514 lines) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address PR review comments: rename to MCP* convention, fix error handling and samples - Rename McpSkill/McpSkillResource/McpSkillsSource to MCPSkill/MCPSkillResource/MCPSkillsSource - Add data-URI prefix stripping for blob resource decoding - Let non-McpError exceptions propagate from get_resource() - Fix contradictory test comment - Use interactive input() in mcp_based_skill sample - Remove misleading sample output block Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Restore debug logging for McpError in get_resource() Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Use AzureCliCredential in Foundry toolbox skills sample for consistency Replace DefaultAzureCredential with AzureCliCredential to match the credential convention used in all other samples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Use MCPStreamableHTTPTool in MCP skills sample Replace raw mcp library imports (ClientSession, streamable_http_client) with the framework's MCPStreamableHTTPTool to keep MCP server connections consistent regardless of whether skills are enabled. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Branch on McpError.error.code so only not-found errors return empty Previously _try_read_index() and get_resource() swallowed every McpError as 'no skills available', making auth failures, server crashes, and connection drops indistinguishable from a server that simply has no skills. Now only two codes are treated as not-found: - -32002 (MCP-spec Resource not found) - -32601 (METHOD_NOT_FOUND — server lacks resources/read) All other McpError codes and non-McpError exceptions propagate with a warning log, surfacing real failures visibly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add tests for non-McpError and non-not-found error propagation in MCP skills Cover the re-raise branch in MCPSkill.get_resource for plain ConnectionError/TimeoutError, the generic McpError (code 0) propagation on get_resource, and TimeoutError propagation in _try_read_index. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Revert "Use MCPStreamableHTTPTool in MCP skills sample" This reverts commit f31ed0ded9. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Introduce MCP_SKILLS experimental feature for MCP skill classes Add a separate MCP_SKILLS feature ID to ExperimentalFeature enum and use it for MCPSkillResource, MCPSkill, and MCPSkillsSource, since their promotion timeline is partly outside of our control. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-06-16 21:04:09 +08:00 · 2026-06-03 19:09:50 +01:00
parent a982428916
commit c6951c21f6
9 changed files with 1333 additions and 0 deletions
@@ -27,6 +27,7 @@ This folder contains Azure AI Foundry and Foundry Local samples for Agent Framew
 | [`foundry_chat_client_with_local_mcp.py`](foundry_chat_client_with_local_mcp.py) | Foundry Chat Client with local MCP |
 | [`foundry_chat_client_with_session.py`](foundry_chat_client_with_session.py) | Foundry Chat Client with session management |
 | [`foundry_chat_client_with_toolbox.py`](foundry_chat_client_with_toolbox.py) | Foundry Chat Client connected to a toolbox via its MCP endpoint using `MCPStreamableHTTPTool` |
+| [`foundry_chat_client_with_toolbox_skills.py`](foundry_chat_client_with_toolbox_skills.py) | Foundry Chat Client that discovers MCP-based skills from a Foundry Toolbox endpoint via `MCPSkillsSource` (uses an Azure AD bearer token and the toolbox preview header) |

 ## FoundryLocalClient Samples

@@ -0,0 +1,87 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from collections.abc import Generator
+
+import httpx
+from agent_framework import Agent, MCPSkillsSource, SkillsProvider
+from agent_framework.foundry import FoundryChatClient
+from azure.core.credentials import TokenCredential
+from azure.identity import AzureCliCredential, get_bearer_token_provider
+from dotenv import load_dotenv
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Toolbox-Hosted Skills
+
+Discover Agent Skills served by a Microsoft Foundry Toolbox MCP endpoint
+and inject them into a ``FoundryChatClient`` agent via ``MCPSkillsSource``.
+The toolbox's discovery document (``skill://index.json``) is read once at
+startup; SKILL.md bodies are fetched on demand as the agent uses them.
+
+Prerequisites:
+- A Microsoft Foundry project with a toolbox that exposes
+  ``skill://index.json`` with ``skill-md`` entries
+- FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL environment variables set
+- FOUNDRY_TOOLBOX_MCP_SERVER_URL: the toolbox's MCP endpoint URL, e.g.
+  ``https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<name>/mcp?api-version=v1``
+- Azure CLI authentication (``az login``)
+"""
+
+
+class _BearerAuth(httpx.Auth):
+    """Attach a fresh Foundry bearer token to every request."""
+
+    def __init__(self, credential: TokenCredential) -> None:
+        self._get_token = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = f"Bearer {self._get_token()}"
+        yield request
+
+
+async def main() -> None:
+    """Example showing toolbox-hosted MCP skills for a Foundry Chat Client agent."""
+    credential = AzureCliCredential()
+
+    # HTTP client that signs every request with a fresh Foundry bearer token
+    # and advertises the toolbox preview feature flag, plus the MCP streamable
+    # HTTP transport that uses it.
+    async with (
+        httpx.AsyncClient(
+            auth=_BearerAuth(credential),
+            headers={"Foundry-Features": "Toolboxes=V1Preview"},
+            timeout=httpx.Timeout(30.0, read=300.0),
+            follow_redirects=True,
+        ) as http_client,
+        streamable_http_client(
+            url=os.environ["FOUNDRY_TOOLBOX_MCP_SERVER_URL"],
+            http_client=http_client,
+        ) as (read, write, _),
+        ClientSession(read, write) as session,
+    ):
+        await session.initialize()
+
+        # Discover skills served by the toolbox and inject them as a context provider.
+        skills_provider = SkillsProvider(MCPSkillsSource(client=session))
+
+        async with Agent(
+            client=FoundryChatClient(credential=credential),
+            name="ToolboxMCPSkillsAgent",
+            instructions="You are a helpful assistant. Use available skills to answer the user.",
+            context_providers=[skills_provider],
+        ) as agent:
+            query = input("User: ").strip()  # noqa: ASYNC250
+            if not query:
+                return
+            response = await agent.run(query)
+            print(f"Assistant: {response.text}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -12,6 +12,7 @@ Start with file-based or code-defined skills, then explore combining them and ad
 | [**code_defined_skill**](code_defined_skill/) | Define skills entirely in Python code using `Skill`, `@skill.resource`, and `@skill.script` decorators. Uses a code-defined unit-converter skill. |
 | [**class_based_skill**](class_based_skill/) | Define skills as Python classes using `ClassSkill` with `@ClassSkill.resource` and `@ClassSkill.script` decorators for auto-discovery. Uses a class-based unit-converter skill. |
 | [**mixed_skills**](mixed_skills/) | Combine code-defined, class-based, and file-based skills in a single agent. Uses a code-defined volume-converter, a class-based temperature-converter, and a file-based unit-converter. |
+| [**mcp_based_skill**](mcp_based_skill/) | Discover skills served over the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) via `MCPSkillsSource`. Connects to a remote MCP server that exposes skills as `skill://...` resources following the SEP-2640 convention. |
 | [**script_approval**](script_approval/) | Require human-in-the-loop approval before executing skill scripts |

 ## Key Concepts
@@ -0,0 +1,51 @@
+# MCP-Based Agent Skills Sample
+
+This sample demonstrates how to discover **Agent Skills served over MCP** with an `Agent`.
+
+## What it demonstrates
+
+- Connecting to a remote MCP server (over streamable HTTP) that exposes skill
+  resources following the SEP-2640 convention.
+- Building a `SkillsProvider` from an `MCPSkillsSource`, which reads
+  `skill://index.json` (SEP-2640 canonical discovery) and constructs skills from
+  the index entries.
+- The progressive disclosure pattern across MCP: advertise → load → read
+  resources, exactly as for filesystem-backed skills.
+
+## Running the Sample
+
+### Prerequisites
+
+- Python 3.10+
+- An [Azure AI Foundry](https://ai.azure.com/) project with a deployed model
+- Azure CLI authentication (`az login`)
+- A running MCP server that hosts SEP-2640 skill resources (see "Providing
+  an MCP server" below)
+
+### Setup
+
+Set the following environment variables (in a `.env` file or your shell):
+
+```powershell
+$env:FOUNDRY_PROJECT_ENDPOINT="https://your-endpoint.services.ai.azure.com/api/projects/your-project"
+$env:FOUNDRY_MODEL="gpt-4o-mini"
+$env:MCP_SKILLS_SERVER_URL="https://your-mcp-server.example.com/mcp"
+```
+
+### Run
+
+```powershell
+python mcp_based_skill.py
+```
+
+## Providing an MCP server
+
+This sample is a **consumer**: it does not host an MCP server itself. To try
+it end-to-end you need an MCP server that exposes the SEP-2640 skill
+resources (`skill://index.json` plus per-skill `SKILL.md`).
+
+- See [`samples/02-agents/mcp/agent_as_mcp_server.py`](../../mcp/agent_as_mcp_server.py)
+  for an example of hosting an MCP server via the Agent Framework.
+- The Model Context Protocol working group maintains reference MCP-skills
+  servers at
+  [`modelcontextprotocol/experimental-ext-skills`](https://github.com/modelcontextprotocol/experimental-ext-skills).
@@ -0,0 +1,75 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+# Uncomment this filter to suppress the experimental Skills warning before
+# using the sample's Skills APIs.
+# import warnings
+# warnings.filterwarnings("ignore", message=r"\[SKILLS\].*", category=FutureWarning)
+from agent_framework import Agent, MCPSkillsSource, SkillsProvider
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+"""
+MCP-Based Agent Skills
+
+This sample demonstrates how to discover Agent Skills served over the
+Model Context Protocol (MCP) using :class:`MCPSkillsSource`.
+
+The sample connects to a remote MCP server that exposes skill resources
+under the ``skill://`` URI scheme:
+
+* ``skill://index.json`` — discovery document listing all skills
+* ``skill://<skill-name>/SKILL.md`` — the skill instructions
+
+To run, set ``MCP_SKILLS_SERVER_URL`` to the streamable HTTP endpoint of an
+MCP server that hosts the skill resources.
+"""
+
+
+async def main() -> None:
+    """Connect to a remote MCP skills server and run the agent."""
+    load_dotenv()
+
+    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
+    deployment = os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini")
+    mcp_url = os.environ["MCP_SKILLS_SERVER_URL"]
+
+    print("Discovering MCP-based skills")
+    print("-" * 60)
+
+    # 1. Connect to the MCP server over streamable HTTP.
+    async with streamable_http_client(url=mcp_url) as (read, write, _), ClientSession(read, write) as session:
+        await session.initialize()
+
+        # 2. Build a SkillsProvider that discovers skills over MCP.
+        #    MCPSkillsSource reads skill://index.json and creates one
+        #    MCPSkill per skill-md entry; SKILL.md bodies are fetched
+        #    on demand via resources/read.
+        skills_provider = SkillsProvider(MCPSkillsSource(client=session))
+
+        # 3. Run the agent.
+        client = FoundryChatClient(
+            project_endpoint=endpoint,
+            model=deployment,
+            credential=AzureCliCredential(),
+        )
+
+        async with Agent(
+            client=client,
+            instructions="You are a helpful assistant. Use available skills to answer the user.",
+            context_providers=[skills_provider],
+        ) as agent:
+            query = input("User: ").strip()  # noqa: ASYNC250
+            if not query:
+                return
+            response = await agent.run(query)
+            print(f"Agent: {response}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())