agent-framework-hosting-mcp 1.0.0a260721__tar.gz

agent_framework_hosting_mcp-1.0.0a260721/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

agent_framework_hosting_mcp-1.0.0a260721/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: agent-framework-hosting-mcp
+Version: 1.0.0a260721
+Summary: Agent and workflow MCP tool adapters for app-owned hosting.
+Author-email: Microsoft <af-support@microsoft.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: agent-framework-core>=1.11.0,<2
+Requires-Dist: agent-framework-hosting==1.0.0a260721
+Requires-Dist: mcp>=1.11.0,<2
+Requires-Dist: pydantic>=2,<3
+Project-URL: homepage, https://aka.ms/agent-framework
+Project-URL: issues, https://github.com/microsoft/agent-framework/issues
+Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
+Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
+
+# agent-framework-hosting-mcp
+
+MCP conversion helpers for app-owned Agent Framework hosting.
+
+The package deliberately does not choose a web framework or wrap the MCP SDK
+server lifecycle. It provides two conversion functions and small adapters:
+
+- `mcp_to_run(...)` converts native MCP tool arguments into Agent Framework run
+  arguments.
+- `mcp_from_run(...)` converts an `AgentResponse` or `Message` into native MCP
+  `ContentBlock` values.
+- `AgentMCPTool(...)` generates the native `Tool` definition from an agent and
+  keeps listing, parsing, execution, result conversion, and optional
+  `AgentState` session persistence aligned.
+- `WorkflowMCPTool(...)` generates the native `Tool` definition from a
+  workflow's start-executor input type and converts completed workflow outputs.
+
+Application code keeps ownership of the MCP SDK's `Server`, handler
+registration, request context, transport, session-key policy, authentication,
+authorization, and deployment.
+
+For direct conversion, the argument name is part of the app-owned MCP tool
+contract. Define it once and use the same value in both the native tool schema
+and `mcp_to_run(...)`:
+
+```python
+agent_input_argument = "task"
+chat_option_arguments = {
+    "reasoning_effort": {
+        "type": "string",
+        "enum": ["low", "medium", "high"],
+    },
+}
+
+tool = Tool(
+    name="run_agent",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            agent_input_argument: {"type": "string"},
+            **chat_option_arguments,
+        },
+        "required": [agent_input_argument],
+    },
+)
+run = mcp_to_run(
+    arguments,
+    argument_name=agent_input_argument,
+    chat_option_arguments=chat_option_arguments,
+)
+```
+
+Only names listed in `chat_option_arguments` are copied to `run["options"]`;
+other MCP arguments remain available in the message's raw representation but
+are not forwarded to the model client. The native MCP schema remains
+responsible for validating exposed option types and ranges.
+
+For an agent exposed as one MCP tool, use the adapter so the schema and
+conversion cannot drift:
+
+```python
+agent_tool = AgentMCPTool(
+    agent,
+    name="run_agent",
+    argument_description="The request for the hosted agent.",
+    parameters={"audience": {"type": "string"}},
+    chat_option_parameters={
+        "reasoning_effort": {
+            "type": "string",
+            "enum": ["low", "medium", "high"],
+        }
+    },
+)
+
+@server.list_tools()
+async def list_tools():
+    return await agent_tool.list_tools()
+
+@server.call_tool()
+async def call_tool(name, arguments):
+    return await agent_tool.call_tool(name, arguments)
+```
+
+`AgentMCPTool` uses the agent's name and description unless overridden.
+`parameters` adds app-owned JSON Schema properties that remain available in the
+raw MCP arguments. `chat_option_parameters` adds properties and explicitly
+copies their values into Agent Framework chat options.
+
+For a workflow exposed as one MCP tool, use `WorkflowMCPTool`:
+
+```python
+workflow_tool = WorkflowMCPTool(
+    WorkflowState(create_workflow, cache_target=False),
+    name="run_workflow",
+)
+```
+
+The start executor must declare exactly one input type. Dataclass, Pydantic, and
+other object-shaped inputs become the MCP tool's top-level arguments. Primitive
+inputs are wrapped in the configurable `argument_name` property. The adapter
+validates MCP arguments against that derived type before calling
+`workflow.run(...)`.
+
+Workflow instances preserve execution state, so applications that need
+independent calls should supply a `WorkflowState` factory with
+`cache_target=False`, as above. Checkpoint restoration, human-in-the-loop
+responses, and continuation identifiers remain application-owned contracts.
+If a workflow requests external input, the adapter raises instead of returning
+an empty successful tool result.
+
+Pass an existing `AgentState` plus `session_id_parameter` to persist an
+`AgentSession`:
+
+```python
+state = AgentState(agent)
+agent_tool = AgentMCPTool(
+    state,
+    parameters={"session_id": {"type": "string", "minLength": 1}},
+    required_parameters={"session_id"},
+    session_id_parameter="session_id",
+)
+```
+
+The application must authenticate or authorize that session identifier and
+serialize concurrent calls for the same session. The adapter only performs the
+`AgentState` session-store get/run/set sequence. A configured session parameter
+is always marked required in the generated MCP schema.
+
+The session identifier is an opaque, application-defined key. Neither MCP nor
+Agent Framework prescribes its format. `AgentMCPTool` treats it as the key for
+one mutable conversation: each call loads that session and stores the updated
+session under the same key. It does not implement
+`previous_response_id`-style branching. Branching requires an app-owned
+contract with separate source and destination identifiers so the application
+can authorize both, copy the source session, and store the result under the
+destination key.
+
+MCP `tools/call` inputs are JSON objects defined by the app's `inputSchema`;
+the protocol does not define image, audio, or resource content blocks for tool
+arguments. This helper therefore converts one selected string argument and
+does not impose a non-standard multimodal JSON convention.
+
+For non-image/audio binary output, `mcp_from_run(...)` uses an app-provided
+`content.additional_properties["uri"]` when present and otherwise uses the
+short fallback `af://binary`; the payload itself is stored only in the MCP
+resource's `blob` field.
+
+`mcp_from_run(...)` targets `CallToolResult.content`, whose MCP content union
+does not include sampling-only `ToolUseContent`. Agent Framework
+`function_call` content is therefore omitted from tool results. MCP sampling
+callbacks use a separate response contract and may convert function calls to
+`ToolUseContent`.
+
+MCP tool calls return one final `CallToolResult`; they do not stream partial
+content blocks. Streamable HTTP may carry multiple MCP messages, and apps may
+send progress notifications while work runs, but neither mechanism turns
+Agent Framework response updates into incremental tool results. Experimental
+MCP tasks defer retrieval of the same final result.
+
+```python
+run = mcp_to_run(arguments)
+result = await agent.run(
+    run["messages"],
+    options=run["options"],
+)
+content = mcp_from_run(result)
+
+# Native MCP SDK application code returns `content` from its call_tool handler.
+```
+
+The surrounding MCP application still owns the low-level `Server`, handler
+registration, Starlette/FastAPI composition, stdio or streamable HTTP
+transport, request authentication, session-key trust, concurrency, and
+deployment.
+

agent_framework_hosting_mcp-1.0.0a260721/README.md

@@ -0,0 +1,174 @@
+# agent-framework-hosting-mcp
+
+MCP conversion helpers for app-owned Agent Framework hosting.
+
+The package deliberately does not choose a web framework or wrap the MCP SDK
+server lifecycle. It provides two conversion functions and small adapters:
+
+- `mcp_to_run(...)` converts native MCP tool arguments into Agent Framework run
+  arguments.
+- `mcp_from_run(...)` converts an `AgentResponse` or `Message` into native MCP
+  `ContentBlock` values.
+- `AgentMCPTool(...)` generates the native `Tool` definition from an agent and
+  keeps listing, parsing, execution, result conversion, and optional
+  `AgentState` session persistence aligned.
+- `WorkflowMCPTool(...)` generates the native `Tool` definition from a
+  workflow's start-executor input type and converts completed workflow outputs.
+
+Application code keeps ownership of the MCP SDK's `Server`, handler
+registration, request context, transport, session-key policy, authentication,
+authorization, and deployment.
+
+For direct conversion, the argument name is part of the app-owned MCP tool
+contract. Define it once and use the same value in both the native tool schema
+and `mcp_to_run(...)`:
+
+```python
+agent_input_argument = "task"
+chat_option_arguments = {
+    "reasoning_effort": {
+        "type": "string",
+        "enum": ["low", "medium", "high"],
+    },
+}
+
+tool = Tool(
+    name="run_agent",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            agent_input_argument: {"type": "string"},
+            **chat_option_arguments,
+        },
+        "required": [agent_input_argument],
+    },
+)
+run = mcp_to_run(
+    arguments,
+    argument_name=agent_input_argument,
+    chat_option_arguments=chat_option_arguments,
+)
+```
+
+Only names listed in `chat_option_arguments` are copied to `run["options"]`;
+other MCP arguments remain available in the message's raw representation but
+are not forwarded to the model client. The native MCP schema remains
+responsible for validating exposed option types and ranges.
+
+For an agent exposed as one MCP tool, use the adapter so the schema and
+conversion cannot drift:
+
+```python
+agent_tool = AgentMCPTool(
+    agent,
+    name="run_agent",
+    argument_description="The request for the hosted agent.",
+    parameters={"audience": {"type": "string"}},
+    chat_option_parameters={
+        "reasoning_effort": {
+            "type": "string",
+            "enum": ["low", "medium", "high"],
+        }
+    },
+)
+
+@server.list_tools()
+async def list_tools():
+    return await agent_tool.list_tools()
+
+@server.call_tool()
+async def call_tool(name, arguments):
+    return await agent_tool.call_tool(name, arguments)
+```
+
+`AgentMCPTool` uses the agent's name and description unless overridden.
+`parameters` adds app-owned JSON Schema properties that remain available in the
+raw MCP arguments. `chat_option_parameters` adds properties and explicitly
+copies their values into Agent Framework chat options.
+
+For a workflow exposed as one MCP tool, use `WorkflowMCPTool`:
+
+```python
+workflow_tool = WorkflowMCPTool(
+    WorkflowState(create_workflow, cache_target=False),
+    name="run_workflow",
+)
+```
+
+The start executor must declare exactly one input type. Dataclass, Pydantic, and
+other object-shaped inputs become the MCP tool's top-level arguments. Primitive
+inputs are wrapped in the configurable `argument_name` property. The adapter
+validates MCP arguments against that derived type before calling
+`workflow.run(...)`.
+
+Workflow instances preserve execution state, so applications that need
+independent calls should supply a `WorkflowState` factory with
+`cache_target=False`, as above. Checkpoint restoration, human-in-the-loop
+responses, and continuation identifiers remain application-owned contracts.
+If a workflow requests external input, the adapter raises instead of returning
+an empty successful tool result.
+
+Pass an existing `AgentState` plus `session_id_parameter` to persist an
+`AgentSession`:
+
+```python
+state = AgentState(agent)
+agent_tool = AgentMCPTool(
+    state,
+    parameters={"session_id": {"type": "string", "minLength": 1}},
+    required_parameters={"session_id"},
+    session_id_parameter="session_id",
+)
+```
+
+The application must authenticate or authorize that session identifier and
+serialize concurrent calls for the same session. The adapter only performs the
+`AgentState` session-store get/run/set sequence. A configured session parameter
+is always marked required in the generated MCP schema.
+
+The session identifier is an opaque, application-defined key. Neither MCP nor
+Agent Framework prescribes its format. `AgentMCPTool` treats it as the key for
+one mutable conversation: each call loads that session and stores the updated
+session under the same key. It does not implement
+`previous_response_id`-style branching. Branching requires an app-owned
+contract with separate source and destination identifiers so the application
+can authorize both, copy the source session, and store the result under the
+destination key.
+
+MCP `tools/call` inputs are JSON objects defined by the app's `inputSchema`;
+the protocol does not define image, audio, or resource content blocks for tool
+arguments. This helper therefore converts one selected string argument and
+does not impose a non-standard multimodal JSON convention.
+
+For non-image/audio binary output, `mcp_from_run(...)` uses an app-provided
+`content.additional_properties["uri"]` when present and otherwise uses the
+short fallback `af://binary`; the payload itself is stored only in the MCP
+resource's `blob` field.
+
+`mcp_from_run(...)` targets `CallToolResult.content`, whose MCP content union
+does not include sampling-only `ToolUseContent`. Agent Framework
+`function_call` content is therefore omitted from tool results. MCP sampling
+callbacks use a separate response contract and may convert function calls to
+`ToolUseContent`.
+
+MCP tool calls return one final `CallToolResult`; they do not stream partial
+content blocks. Streamable HTTP may carry multiple MCP messages, and apps may
+send progress notifications while work runs, but neither mechanism turns
+Agent Framework response updates into incremental tool results. Experimental
+MCP tasks defer retrieval of the same final result.
+
+```python
+run = mcp_to_run(arguments)
+result = await agent.run(
+    run["messages"],
+    options=run["options"],
+)
+content = mcp_from_run(result)
+
+# Native MCP SDK application code returns `content` from its call_tool handler.
+```
+
+The surrounding MCP application still owns the low-level `Server`, handler
+registration, Starlette/FastAPI composition, stdio or streamable HTTP
+transport, request authentication, session-key trust, concurrency, and
+deployment.

agent_framework_hosting_mcp-1.0.0a260721/agent_framework_hosting_mcp/__init__.py

@@ -0,0 +1,22 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent and workflow MCP tool adapters for app-owned hosting."""
+
+import importlib.metadata
+
+from ._agent_tool import AgentMCPTool
+from ._conversion import mcp_from_run, mcp_to_run
+from ._workflow_tool import WorkflowMCPTool
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AgentMCPTool",
+    "WorkflowMCPTool",
+    "__version__",
+    "mcp_from_run",
+    "mcp_to_run",
+]

agent_framework_hosting_mcp-1.0.0a260721/agent_framework_hosting_mcp/_agent_tool.py

@@ -0,0 +1,179 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent-backed MCP tool adapter for app-owned servers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Collection, Mapping
+from typing import Any, Generic, TypeVar, cast
+
+from agent_framework import AgentResponse, Message, SupportsAgentRun
+from agent_framework_hosting import AgentRunArgs, AgentState
+from mcp import types
+
+from ._conversion import mcp_from_run, mcp_to_run
+
+AgentT = TypeVar("AgentT", bound=SupportsAgentRun)
+
+
+class AgentMCPTool(Generic[AgentT]):
+    """Expose one Agent Framework agent through an app-owned MCP server.
+
+    The adapter generates the native MCP tool definition and keeps its argument
+    parsing aligned with agent execution. It does not create an MCP server,
+    register handlers, derive trusted session identifiers, or choose a
+    transport.
+    """
+
+    def __init__(
+        self,
+        target: AgentT | AgentState[AgentT],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        argument_name: str = "task",
+        argument_description: str | None = None,
+        parameters: Mapping[str, Mapping[str, Any]] | None = None,
+        required_parameters: Collection[str] = (),
+        chat_option_parameters: Mapping[str, Mapping[str, Any]] | None = None,
+        session_id_parameter: str | None = None,
+    ) -> None:
+        """Create an agent-backed MCP tool adapter.
+
+        Args:
+            target: Agent target or existing ``AgentState``.
+
+        Keyword Args:
+            name: MCP tool name override. Defaults to a sanitized agent name.
+            description: MCP tool description override. Defaults to the agent description.
+            argument_name: Name of the main text argument.
+            argument_description: Description of the main text argument.
+            parameters: Additional app-owned MCP parameter schemas.
+            required_parameters: Additional parameter names that are required.
+            chat_option_parameters: MCP parameter schemas whose values are copied to chat options.
+            session_id_parameter: Additional string parameter used as the ``AgentState`` session key.
+
+        Raises:
+            ValueError: If parameter names overlap or required/session parameters are not defined.
+        """
+        self.state = target if isinstance(target, AgentState) else AgentState(target)
+        self._name = name
+        self._description = description
+        self.argument_name = argument_name
+        self.argument_description = argument_description
+        self.parameters = {key: dict(value) for key, value in (parameters or {}).items()}
+        self.chat_option_parameters = {key: dict(value) for key, value in (chat_option_parameters or {}).items()}
+        self.session_id_parameter = session_id_parameter
+
+        parameter_names = set(self.parameters)
+        chat_option_names = set(self.chat_option_parameters)
+        if self.argument_name in parameter_names | chat_option_names:
+            raise ValueError(f"Main argument '{self.argument_name}' must not be repeated in additional parameters.")
+        if parameter_names & chat_option_names:
+            raise ValueError("Additional parameters and chat option parameters must have distinct names.")
+        required_names = set(required_parameters)
+        if session_id_parameter is not None:
+            required_names.add(session_id_parameter)
+        if self.session_id_parameter is not None and self.session_id_parameter not in parameter_names:
+            raise ValueError("session_id_parameter must name an additional parameter.")
+        undefined_required = required_names - parameter_names - chat_option_names
+        if undefined_required:
+            raise ValueError(f"Required parameters are not defined: {sorted(undefined_required)}")
+        self.required_parameters = tuple(
+            name for name in (*self.parameters, *self.chat_option_parameters) if name in required_names
+        )
+
+    async def list_tools(self) -> list[types.Tool]:
+        """Return the native MCP tool definition for the target agent."""
+        target = await self.state.get_target()
+        return [self._tool_for_target(target)]
+
+    def _tool_for_target(self, target: AgentT) -> types.Tool:
+        """Create the native MCP tool definition for a resolved target."""
+        tool_name = self._name
+        if tool_name is None:
+            if target.name is None:
+                raise ValueError("MCP tool name requires either an override or an agent name.")
+            tool_name = re.sub(r"[^a-zA-Z0-9_.-]+", "_", target.name).strip("_") or "agent"
+
+        properties: dict[str, Any] = {
+            self.argument_name: {
+                "type": "string",
+                "description": self.argument_description or f"Task for {tool_name}",
+            },
+            **self.parameters,
+            **self.chat_option_parameters,
+        }
+        return types.Tool(
+            name=tool_name,
+            description=self._description if self._description is not None else target.description or "",
+            inputSchema={
+                "type": "object",
+                "properties": properties,
+                "required": [self.argument_name, *self.required_parameters],
+                "additionalProperties": False,
+            },
+        )
+
+    def mcp_to_run(self, arguments: Mapping[str, Any] | None) -> AgentRunArgs:
+        """Convert this tool's MCP arguments into Agent Framework run arguments."""
+        return mcp_to_run(
+            arguments,
+            argument_name=self.argument_name,
+            chat_option_arguments=self.chat_option_parameters,
+        )
+
+    def mcp_from_run(self, result: AgentResponse[Any] | Message) -> list[types.ContentBlock]:
+        """Convert Agent Framework output into this tool's MCP result content."""
+        return mcp_from_run(result)
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: Mapping[str, Any] | None,
+    ) -> list[types.ContentBlock]:
+        """Run the target agent for a native MCP ``call_tool`` handler.
+
+        Args:
+            name: MCP tool name selected by the client.
+            arguments: Native MCP tool arguments.
+
+        Returns:
+            Native MCP content blocks for the completed tool result.
+
+        Raises:
+            ValueError: If the tool name or configured session id is invalid.
+        """
+        target = await self.state.get_target()
+        tool = self._tool_for_target(target)
+        if name != tool.name:
+            raise ValueError(f"Unknown MCP tool: {name}")
+
+        run = self.mcp_to_run(arguments)
+        if self.session_id_parameter is None:
+            result = cast(
+                "AgentResponse[Any]",
+                await target.run(  # pyright: ignore[reportCallIssue]
+                    run["messages"],
+                    options=run["options"],
+                    stream=False,
+                ),
+            )
+            return self.mcp_from_run(result)
+
+        session_id = arguments.get(self.session_id_parameter) if arguments else None
+        if not isinstance(session_id, str) or not session_id:
+            raise ValueError(f"MCP tool argument '{self.session_id_parameter}' must be a non-empty string.")
+        session = await self.state.get_or_create_session(session_id)
+        result = cast(
+            "AgentResponse[Any]",
+            await target.run(  # pyright: ignore[reportCallIssue]
+                run["messages"],
+                options=run["options"],
+                session=session,
+                stream=False,
+            ),
+        )
+        await self.state.set_session(session_id, session)
+        return self.mcp_from_run(result)

agent_framework_hosting_mcp-1.0.0a260721/agent_framework_hosting_mcp/_conversion.py

@@ -0,0 +1,155 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Conversion between native MCP values and Agent Framework run values."""
+
+from __future__ import annotations
+
+import base64
+import logging
+from collections.abc import Collection, Mapping, Sequence
+from typing import Any, cast
+
+from agent_framework import AgentResponse, ChatOptions, Content, Message
+from agent_framework_hosting import AgentRunArgs
+from mcp import types
+
+logger = logging.getLogger("agent_framework.hosting.mcp")
+
+
+def mcp_to_run(
+    arguments: Mapping[str, Any] | None,
+    *,
+    argument_name: str = "task",
+    chat_option_arguments: Collection[str] = (),
+) -> AgentRunArgs:
+    """Convert native MCP tool arguments into Agent Framework run arguments.
+
+    The application owns the MCP tool schema and chooses which string argument
+    contains the user request. This helper does not create sessions, inspect
+    request context, or interact with an MCP server.
+
+    Args:
+        arguments: Arguments supplied to an MCP ``call_tool`` handler.
+
+    Keyword Args:
+        argument_name: Name of the required string argument containing the user request.
+        chat_option_arguments: MCP argument names to copy into Agent Framework chat options when present.
+
+    Returns:
+        Arguments corresponding to ``Agent.run(...)``.
+
+    Raises:
+        ValueError: If the selected argument is missing or is not a string.
+    """
+    if arguments is None or argument_name not in arguments:
+        raise ValueError(f"MCP tool arguments must include a '{argument_name}' string.")
+
+    message_value = arguments[argument_name]
+    if not isinstance(message_value, str):
+        raise ValueError(f"MCP tool argument '{argument_name}' must be a string.")
+
+    options = {name: arguments[name] for name in chat_option_arguments if name in arguments}
+    return AgentRunArgs(
+        messages=[
+            Message(
+                "user",
+                [Content.from_text(message_value)],
+                raw_representation=dict(arguments),
+            )
+        ],
+        options=cast("ChatOptions[Any]", options),
+        stream=False,
+    )
+
+
+def mcp_from_run(
+    result: AgentResponse[Any] | Message,
+) -> list[types.ContentBlock]:
+    """Convert Agent Framework output into native MCP content blocks.
+
+    ``AgentResponse`` values are flattened in message order. User-role
+    messages are omitted. Text, external URI, and inline data content become
+    the corresponding native MCP content block types. Content-level metadata
+    is preserved in each block's ``_meta`` field.
+
+    Args:
+        result: A completed response or response message.
+
+    Returns:
+        Native MCP content blocks ready for a ``CallToolResult``.
+
+    Raises:
+        ValueError: If Agent Framework data content contains an invalid data URI.
+    """
+    items: Sequence[Message] = result.messages if isinstance(result, AgentResponse) else [result]
+
+    blocks: list[types.ContentBlock] = []
+    for item in items:
+        if item.role == "user":
+            continue
+        for content in item.contents:
+            metadata = content.additional_properties or None
+            match content.type:
+                case "text" if content.text is not None:
+                    blocks.append(types.TextContent(type="text", text=content.text, _meta=metadata))
+                case "uri" if content.uri is not None:
+                    name = content.uri.rsplit("/", maxsplit=1)[-1] or content.uri
+                    blocks.append(
+                        types.ResourceLink(
+                            type="resource_link",
+                            name=name,
+                            uri=content.uri,  # pyright: ignore[reportArgumentType]
+                            mimeType=content.media_type,
+                            _meta=metadata,
+                        )
+                    )
+                case "data" if content.uri is not None:
+                    prefix, separator, encoded = content.uri.partition(",")
+                    if not separator or not prefix.startswith("data:") or ";base64" not in prefix:
+                        raise ValueError("Agent Framework data content must contain a base64 data URI.")
+                    try:
+                        base64.b64decode(encoded, validate=True)
+                    except ValueError as exc:
+                        raise ValueError("Agent Framework data content contains invalid base64 data.") from exc
+
+                    if content.media_type and content.media_type.startswith("image/"):
+                        blocks.append(
+                            types.ImageContent(
+                                type="image",
+                                data=encoded,
+                                mimeType=content.media_type,
+                                _meta=metadata,
+                            )
+                        )
+                    elif content.media_type and content.media_type.startswith("audio/"):
+                        blocks.append(
+                            types.AudioContent(
+                                type="audio",
+                                data=encoded,
+                                mimeType=content.media_type,
+                                _meta=metadata,
+                            )
+                        )
+                    else:
+                        resource_uri = (
+                            content.additional_properties.get("uri") if content.additional_properties else None
+                        )
+                        if not isinstance(resource_uri, str):
+                            resource_uri = "af://binary"
+                        blocks.append(
+                            types.EmbeddedResource(
+                                type="resource",
+                                resource=types.BlobResourceContents(
+                                    uri=resource_uri,  # pyright: ignore[reportArgumentType]
+                                    blob=encoded,
+                                    mimeType=content.media_type,
+                                ),
+                                _meta=metadata,
+                            )
+                        )
+                case _:
+                    logger.warning(
+                        "Agent Framework content type %s is not supported in MCP tool results and was omitted.",
+                        content.type,
+                    )
+    return blocks

agent_framework_hosting_mcp-1.0.0a260721/agent_framework_hosting_mcp/_workflow_tool.py

@@ -0,0 +1,143 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Workflow-backed MCP tool adapter for app-owned servers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any, Generic, TypeVar, cast
+
+from agent_framework import AgentResponse, Message, Workflow, WorkflowRunResult
+from agent_framework_hosting import WorkflowState
+from mcp import types
+from pydantic import TypeAdapter
+
+from ._conversion import mcp_from_run
+
+WorkflowT = TypeVar("WorkflowT", bound=Workflow)
+
+
+class WorkflowMCPTool(Generic[WorkflowT]):
+    """Expose one Agent Framework workflow through an app-owned MCP server.
+
+    The adapter derives the native MCP input schema from the workflow's start
+    executor. It does not create an MCP server, register handlers, choose a
+    transport, or manage workflow checkpoints and human-in-the-loop responses.
+    """
+
+    def __init__(
+        self,
+        target: WorkflowT | WorkflowState[WorkflowT],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        argument_name: str = "input",
+    ) -> None:
+        """Create a workflow-backed MCP tool adapter.
+
+        Args:
+            target: Workflow target or existing ``WorkflowState``. Use a
+                ``WorkflowState`` factory with ``cache_target=False`` when
+                concurrent calls need independent workflow instances.
+
+        Keyword Args:
+            name: MCP tool name override. Defaults to a sanitized workflow name.
+            description: MCP tool description override. Defaults to the workflow description.
+            argument_name: MCP property used when the workflow input is not an object.
+        """
+        self.state = target if isinstance(target, WorkflowState) else WorkflowState(target)
+        self._name = name
+        self._description = description
+        self.argument_name = argument_name
+
+    async def list_tools(self) -> list[types.Tool]:
+        """Return the native MCP tool definition for the target workflow."""
+        workflow = await self.state.get_target()
+        return [self._tool_for_workflow(workflow)]
+
+    def _tool_for_workflow(self, workflow: WorkflowT) -> types.Tool:
+        tool_name = self._name
+        if tool_name is None:
+            tool_name = re.sub(r"[^a-zA-Z0-9_.-]+", "_", workflow.name).strip("_") or "workflow"
+
+        input_adapter = self._input_adapter(workflow)
+        input_schema = input_adapter.json_schema()
+        if input_schema.get("type") != "object":
+            input_schema = {
+                "type": "object",
+                "properties": {self.argument_name: input_schema},
+                "required": [self.argument_name],
+                "additionalProperties": False,
+            }
+
+        return types.Tool(
+            name=tool_name,
+            description=self._description if self._description is not None else workflow.description or "",
+            inputSchema=input_schema,
+        )
+
+    def _input_adapter(self, workflow: WorkflowT) -> TypeAdapter[Any]:
+        input_types = workflow.get_start_executor().input_types
+        if len(input_types) != 1:
+            raise ValueError(
+                f"MCP workflow tools require exactly one start-executor input type; found {len(input_types)}."
+            )
+        return TypeAdapter(input_types[0])
+
+    def _workflow_input(self, workflow: WorkflowT, arguments: Mapping[str, Any] | None) -> Any:
+        input_adapter = self._input_adapter(workflow)
+        input_schema = input_adapter.json_schema()
+        if input_schema.get("type") == "object":
+            return input_adapter.validate_python(dict(arguments or {}))
+        if arguments is None or self.argument_name not in arguments:
+            raise ValueError(f"MCP tool arguments must include '{self.argument_name}'.")
+        return input_adapter.validate_python(arguments[self.argument_name])
+
+    def mcp_from_run(self, result: WorkflowRunResult) -> list[types.ContentBlock]:
+        """Convert completed workflow outputs into native MCP content blocks."""
+        if result.get_request_info_events():
+            raise ValueError(
+                "The workflow requires external input. WorkflowMCPTool does not manage "
+                "human-in-the-loop continuation; handle it in the application contract."
+            )
+
+        blocks: list[types.ContentBlock] = []
+        for output in result.get_outputs():
+            if isinstance(output, (AgentResponse, Message)):
+                blocks.extend(mcp_from_run(cast("AgentResponse[Any] | Message", output)))
+            elif isinstance(output, str):
+                blocks.append(types.TextContent(type="text", text=output))
+            else:
+                blocks.append(
+                    types.TextContent(
+                        type="text",
+                        text=TypeAdapter[Any](Any).dump_json(output, serialize_as_any=True).decode(),
+                    )
+                )
+        return blocks
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: Mapping[str, Any] | None,
+    ) -> list[types.ContentBlock]:
+        """Run the target workflow for a native MCP ``call_tool`` handler.
+
+        Args:
+            name: MCP tool name selected by the client.
+            arguments: Native MCP tool arguments.
+
+        Returns:
+            Native MCP content blocks for the completed workflow result.
+
+        Raises:
+            ValueError: If the tool name or workflow input contract is invalid.
+        """
+        workflow = await self.state.get_target()
+        tool = self._tool_for_workflow(workflow)
+        if name != tool.name:
+            raise ValueError(f"Unknown MCP tool: {name}")
+
+        result = await workflow.run(self._workflow_input(workflow, arguments), stream=False)
+        return self.mcp_from_run(result)

agent_framework_hosting_mcp-1.0.0a260721/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "agent-framework-hosting-mcp"
+description = "Agent and workflow MCP tool adapters for app-owned hosting."
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.0.0a260721"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core>=1.11.0,<2",
+    "agent-framework-hosting==1.0.0a260721",
+    "mcp>=1.11.0,<2",
+    "pydantic>=2,<3",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = []
+timeout = 120
+markers = [
+    "integration: marks tests as integration tests that require external services",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+include = ["agent_framework_hosting_mcp"]
+exclude = ['tests']
+
+[tool.bandit]
+targets = ["agent_framework_hosting_mcp"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+
+[tool.poe.tasks.test]
+help = "Run the default unit test suite for this package."
+cmd = 'pytest -m "not integration" --cov=agent_framework_hosting_mcp --cov-report=term-missing:skip-covered tests'
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"