microsoft-teams-mcpplugin 0.0.1a5__tar.gz

microsoft_teams_mcpplugin-0.0.1a5/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+.copilot-instructions.md
+
+# other
+.DS_STORE
+*.bak
+*~
+*.tmp
+
+ref/
+py.typed
+CLAUDE.md
+
+.env.claude/
+.claude/
+
+tests/**/.vscode/
+tests/**/appPackage/
+tests/**/infra/
+tests/**/teamsapp*

microsoft_teams_mcpplugin-0.0.1a5/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: microsoft-teams-mcpplugin
+Version: 0.0.1a5
+Summary: library for handling mcp with teams ai library
+Author-email: Microsoft <TeamsAISDKFeedback@microsoft.com>
+License-Expression: MIT
+Keywords: agents,ai,bot,microsoft,teams
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=0.5.0
+Requires-Dist: mcp>=1.13.1
+Requires-Dist: microsoft-teams-ai
+Requires-Dist: microsoft-teams-apps
+Requires-Dist: microsoft-teams-common

microsoft_teams_mcpplugin-0.0.1a5/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "microsoft-teams-mcpplugin"
+version = "0.0.1a5"
+description = "library for handling mcp with teams ai library"
+authors = [{ name = "Microsoft", email = "TeamsAISDKFeedback@microsoft.com" }]
+readme = "README.md"
+requires-python = ">=3.12"
+repository = "https://github.com/microsoft/teams.py"
+keywords = ["microsoft", "teams", "ai", "bot", "agents"]
+license = "MIT"
+dependencies = [
+    "mcp>=1.13.1",
+    "microsoft-teams-common",
+    "fastmcp>=0.5.0",
+    "microsoft-teams-apps",
+    "microsoft-teams-ai" 
+]
+
+[tool.microsoft-teams.metadata]
+external = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/microsoft"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src"]
+
+[tool.uv.sources]
+microsoft-teams-ai = { workspace = true }
+microsoft-teams-common = { workspace = true }

microsoft_teams_mcpplugin-0.0.1a5/src/microsoft/teams/mcpplugin/__init__.py

@@ -0,0 +1,12 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from . import models
+from .ai_plugin import McpClientPlugin, McpClientPluginParams, McpToolDetails
+from .models import *  # noqa: F403
+from .server_plugin import McpServerPlugin
+
+__all__: list[str] = ["McpClientPlugin", "McpClientPluginParams", "McpToolDetails", "McpServerPlugin"]
+__all__.extend(models.__all__)

microsoft_teams_mcpplugin-0.0.1a5/src/microsoft/teams/mcpplugin/ai_plugin.py

@@ -0,0 +1,226 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+import asyncio
+import json
+import logging
+import time
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from mcp import ClientSession
+from mcp.types import TextContent
+from microsoft.teams.ai.function import Function
+from microsoft.teams.ai.plugin import BaseAIPlugin
+from microsoft.teams.common.logging import ConsoleLogger
+from pydantic import BaseModel
+
+from .models import McpCachedValue, McpClientPluginParams, McpToolDetails
+from .transport import create_transport
+
+REFETCH_TIMEOUT_MS = 24 * 60 * 60 * 1000  # 1 day
+
+
+class McpClientPlugin(BaseAIPlugin):
+    """MCP Client Plugin for Teams AI integration."""
+
+    def __init__(
+        self,
+        name: str = "mcp_client",
+        version: str = "0.0.0",
+        cache: Optional[Dict[str, McpCachedValue]] = None,
+        logger: Optional[logging.Logger] = None,
+        refetch_timeout_ms: int = REFETCH_TIMEOUT_MS,  # 1 day
+    ):
+        super().__init__(name)
+
+        self._version = version
+        self._cache: Dict[str, McpCachedValue] = cache or {}
+        self._logger = logger.getChild(self.name) if logger else ConsoleLogger().create_logger(self.name)
+        self._refetch_timeout_ms = refetch_timeout_ms
+
+        # If cache is provided, update last_fetched for entries with tools
+        if cache:
+            current_time = time.time() * 1000
+            for cached_value in cache.values():
+                if cached_value.available_tools and not cached_value.last_fetched:
+                    cached_value.last_fetched = current_time
+
+        # Track MCP server URLs and their parameters
+        self._mcp_server_params: Dict[str, McpClientPluginParams] = {}
+
+    @property
+    def version(self) -> str:
+        """Get the plugin version."""
+        return self._version
+
+    @property
+    def cache(self) -> Dict[str, McpCachedValue]:
+        """Get the plugin cache."""
+        return self._cache
+
+    @property
+    def refetch_timeout_ms(self) -> int:
+        """Get the refetch timeout in milliseconds."""
+        return self._refetch_timeout_ms
+
+    def use_mcp_server(self, url: str, params: Optional[McpClientPluginParams] = None) -> None:
+        """Add or updates an MCP server to be used by this plugin."""
+        self._mcp_server_params[url] = params or McpClientPluginParams()
+
+        # Update cache if tools are provided
+        if params and params.available_tools:
+            self._cache[url] = McpCachedValue(
+                transport=params.transport,
+                available_tools=params.available_tools,
+                last_fetched=time.time() * 1000,  # Set to current time in milliseconds
+            )
+
+    async def on_build_functions(self, functions: List[Function[BaseModel]]) -> List[Function[BaseModel]]:
+        """Build functions from MCP tools."""
+        await self._fetch_tools_if_needed()
+
+        # Create functions from cached tools
+        all_functions = list(functions)
+
+        for url, params in self._mcp_server_params.items():
+            cached_data = self._cache.get(url)
+            available_tools = cached_data.available_tools if cached_data else []
+
+            for tool in available_tools:
+                # Create a function for each tool
+                function = self._create_function_from_tool(url, tool, params)
+                all_functions.append(function)
+
+        return all_functions
+
+    async def _fetch_tools_if_needed(self) -> None:
+        """
+        Fetch tools from MCP servers if needed.
+
+        We check if there the cached value has met its expiration
+        for being refetched. Or if the tools have never been fetched at all
+        """
+        fetch_needed: List[Tuple[str, McpClientPluginParams]] = []
+        current_time = time.time() * 1000  # Convert to milliseconds
+
+        for url, params in self._mcp_server_params.items():
+            # Skip if tools are explicitly provided
+            if params.available_tools:
+                continue
+
+            cached_data = self._cache.get(url)
+            should_fetch = (
+                not cached_data
+                or not cached_data.available_tools
+                or not cached_data.last_fetched
+                or (current_time - cached_data.last_fetched) > (params.refetch_timeout_ms or self._refetch_timeout_ms)
+            )
+
+            if should_fetch:
+                fetch_needed.append((url, params))
+
+        # Fetch tools in parallel
+        if fetch_needed:
+            tasks = [self._fetch_tools_from_server(url, params) for url, params in fetch_needed]
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+
+            for i, (url, params) in enumerate(fetch_needed):
+                result = results[i]
+                if isinstance(result, Exception):
+                    self._logger.error(f"Failed to fetch tools from {url}: {result}")
+                    if not params.skip_if_unavailable:
+                        raise result
+                elif isinstance(result, list):
+                    # Update cache with fetched tools
+                    if url not in self._cache:
+                        self._cache[url] = McpCachedValue()
+                    self._cache[url].available_tools = result
+                    self._cache[url].last_fetched = current_time
+                    self._cache[url].transport = params.transport
+
+                    self._logger.debug(f"Cached {len(result)} tools for {url}")
+
+    def _create_function_from_tool(
+        self, url: str, tool: McpToolDetails, plugin_params: McpClientPluginParams
+    ) -> Function[BaseModel]:
+        """Create a Teams AI function from an MCP tool."""
+        tool_name = tool.name
+        tool_description = tool.description
+
+        async def handler(params: BaseModel) -> str:
+            """Handle MCP tool call."""
+            try:
+                self._logger.debug(f"Making call to {url} tool-name={tool_name}")
+                result = await self._call_mcp_tool(url, tool_name, params.model_dump(), plugin_params)
+                self._logger.debug(f"Successfully received result for mcp call {result}")
+                return str(result)
+            except Exception as e:
+                self._logger.error(f"Error calling tool {tool_name} on {url}: {e}")
+                raise
+
+        return Function(
+            name=tool_name, description=tool_description, parameter_schema=tool.input_schema, handler=handler
+        )
+
+    async def _fetch_tools_from_server(self, url: str, params: McpClientPluginParams) -> List[McpToolDetails]:
+        """Fetch tools from a specific MCP server."""
+        transport_context = create_transport(url, params.transport or "streamable_http", params.headers)
+
+        async with transport_context as (read_stream, write_stream):
+            async with ClientSession(read_stream, write_stream) as session:
+                # Initialize the connection
+                await session.initialize()
+
+                # List available tools
+                tools_response = await session.list_tools()
+
+                # Convert MCP tools to our format
+                tools: list[McpToolDetails] = []
+                for tool in tools_response.tools:
+                    tools.append(
+                        McpToolDetails(
+                            name=tool.name, description=tool.description or "", input_schema=tool.inputSchema or {}
+                        )
+                    )
+
+                self._logger.debug(f"Got {len(tools)} tools for {url}")
+                return tools
+
+    async def _call_mcp_tool(
+        self, url: str, tool_name: str, arguments: Dict[str, Any], params: McpClientPluginParams
+    ) -> Optional[Union[str, List[str]]]:
+        """Call a specific tool on an MCP server."""
+        transport_context = create_transport(url, params.transport or "streamable_http", params.headers)
+
+        async with transport_context as (read_stream, write_stream):
+            async with ClientSession(read_stream, write_stream) as session:
+                # Initialize the connection
+                await session.initialize()
+
+                # Call the tool
+                result = await session.call_tool(tool_name, arguments)
+
+                # Return the content from the result
+                if result.content:
+                    if len(result.content) == 1:
+                        content_item = result.content[0]
+                        if isinstance(content_item, TextContent):
+                            return content_item.text
+                        else:
+                            return str(content_item)
+                    else:
+                        contents: list[str] = []
+                        for item in result.content:
+                            if isinstance(item, TextContent):
+                                contents.append(item.text)
+                            else:
+                                try:
+                                    contents.append(json.dumps(item, default=str, ensure_ascii=False))
+                                except (TypeError, ValueError) as e:
+                                    self._logger.warning(f"Failed to serialize content item: {e}")
+                                    contents.append(str(item))
+                        return contents
+
+                return None

microsoft_teams_mcpplugin-0.0.1a5/src/microsoft/teams/mcpplugin/models/__init__.py

@@ -0,0 +1,10 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from .cache import McpCachedValue
+from .params import McpClientPluginParams
+from .tool import McpToolDetails
+
+__all__ = ["McpCachedValue", "McpClientPluginParams", "McpToolDetails"]

microsoft_teams_mcpplugin-0.0.1a5/src/microsoft/teams/mcpplugin/models/cache.py

@@ -0,0 +1,22 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from typing import List, Optional
+
+from .tool import McpToolDetails
+
+
+class McpCachedValue:
+    """Cached value for MCP server data."""
+
+    def __init__(
+        self,
+        transport: Optional[str] = None,
+        available_tools: Optional[List[McpToolDetails]] = None,
+        last_fetched: Optional[float] = None,
+    ):
+        self.transport = transport
+        self.available_tools = available_tools or []
+        self.last_fetched = last_fetched

microsoft_teams_mcpplugin-0.0.1a5/src/microsoft/teams/mcpplugin/models/params.py

@@ -0,0 +1,26 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from typing import Awaitable, Callable, List, Mapping, Optional, Union
+
+from .tool import McpToolDetails
+
+
+class McpClientPluginParams:
+    """Parameters for MCP client plugin configuration."""
+
+    def __init__(
+        self,
+        transport: Optional[str] = "streamable_http",
+        available_tools: Optional[List[McpToolDetails]] = None,
+        headers: Optional[Mapping[str, Union[str, Callable[[], Union[str, Awaitable[str]]]]]] = None,
+        skip_if_unavailable: Optional[bool] = True,
+        refetch_timeout_ms: Optional[int] = None,
+    ):
+        self.transport = transport
+        self.available_tools = available_tools
+        self.headers = headers
+        self.skip_if_unavailable = skip_if_unavailable
+        self.refetch_timeout_ms = refetch_timeout_ms

microsoft_teams_mcpplugin-0.0.1a5/src/microsoft/teams/mcpplugin/models/tool.py

@@ -0,0 +1,16 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from typing import Any, Dict
+
+from pydantic import BaseModel
+
+
+class McpToolDetails(BaseModel):
+    """Details of an MCP tool."""
+
+    name: str
+    description: str
+    input_schema: Dict[str, Any]

microsoft_teams_mcpplugin-0.0.1a5/src/microsoft/teams/mcpplugin/server_plugin.py

@@ -0,0 +1,150 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+import importlib.metadata
+import logging
+from inspect import isawaitable
+from typing import Annotated, Any, TypeVar
+
+from fastmcp import FastMCP
+from fastmcp.tools import FunctionTool
+from microsoft.teams.ai import Function
+from microsoft.teams.apps import (
+    DependencyMetadata,
+    HttpPlugin,
+    Plugin,
+    PluginBase,
+    PluginStartEvent,
+)
+from microsoft.teams.common.logging import ConsoleLogger
+from pydantic import BaseModel
+
+try:
+    version = importlib.metadata.version("microsoft-teams-mcpplugin")
+except importlib.metadata.PackageNotFoundError:
+    version = "0.0.1-alpha.1"
+
+P = TypeVar("P", bound=BaseModel)
+
+
+@Plugin(
+    name="mcp-server", version=version, description="MCP server plugin that exposes Teams AI functions as MCP tools"
+)
+class McpServerPlugin(PluginBase):
+    """
+    MCP Server Plugin for Teams Apps.
+
+    This plugin wraps FastMCP and provides a bridge between Teams AI Functions
+    and MCP tools, exposing them via streamable HTTP transport.
+    """
+
+    # Dependency injection
+    http: Annotated[HttpPlugin, DependencyMetadata()]
+
+    def __init__(self, name: str = "teams-mcp-server", path: str = "/mcp", logger: logging.Logger | None = None):
+        """
+        Initialize the MCP server plugin.
+
+        Args:
+            name: The name of the MCP server
+            path: The path to mount the MCP server on (default: /mcp)
+        """
+        self.mcp_server = FastMCP(name)
+        self.path = path
+        self._mounted = False
+        self.logger = logger or ConsoleLogger().create_logger("mcp-server")
+
+    @property
+    def server(self) -> FastMCP:
+        """Get the underlying FastMCP server."""
+        return self.mcp_server
+
+    def use_tool(self, function: Function[P]) -> "McpServerPlugin":
+        """
+        Add a Teams AI function as an MCP tool.
+
+        This a convenience wrapper on top of the underlying FastMCP's add_tool.
+        Use it like:
+        ```py
+        mcp_server_plugin.use_tool(my_fn_definition)
+        ```
+
+        If you'd like to use that directly, you can call
+        ```py
+        @mcp_server_plugin.server.tool
+        def my_fn_definition(arg1: int, arg2: str): bool
+            ...
+        ```
+
+        Args:
+            function: The Teams AI function to register as an MCP tool
+
+        Returns:
+            Self for method chaining
+        """
+        try:
+            # Prepare parameter schema for FastMCP
+            parameter_schema = (
+                function.parameter_schema
+                if isinstance(function.parameter_schema, dict)
+                else function.parameter_schema.model_json_schema()
+            )
+
+            # Create wrapper handler that converts kwargs to the expected format
+            async def wrapped_handler(**kwargs: Any) -> Any:
+                try:
+                    if isinstance(function.parameter_schema, type):
+                        # parameter_schema is a Pydantic model class - instantiate it
+                        params = function.parameter_schema(**kwargs)
+                        result = function.handler(params)
+                    else:
+                        # parameter_schema is a dict - pass kwargs directly
+                        result = function.handler(**kwargs)
+
+                    # Handle both sync and async handlers
+                    if isawaitable(result):
+                        return await result
+                    return result
+                except Exception as e:
+                    self.logger.error(f"Function execution failed for '{function.name}': {e}")
+                    raise
+
+            function_tool = FunctionTool(
+                name=function.name, description=function.description, parameters=parameter_schema, fn=wrapped_handler
+            )
+            self.mcp_server.add_tool(function_tool)
+
+            self.logger.debug(f"Registered Teams AI function '{function.name}' as MCP tool")
+
+            return self
+        except Exception as e:
+            self.logger.error(f"Failed to register function '{function.name}' as MCP tool: {e}")
+            raise
+
+    async def on_start(self, event: PluginStartEvent) -> None:
+        """Start the plugin - mount MCP server on HTTP plugin."""
+
+        if self._mounted:
+            self.logger.warning("MCP server already mounted")
+            return
+
+        try:
+            # We mount the mcp server as a separate app at self.path
+            mcp_http_app = self.mcp_server.http_app(path=self.path, transport="http")
+            self.http.lifespans.append(mcp_http_app.lifespan)
+            self.http.app.mount("/", mcp_http_app)
+
+            self._mounted = True
+
+            self.logger.info(f"MCP server mounted at {self.path}")
+        except Exception as e:
+            self.logger.error(f"Failed to mount MCP server: {e}")
+            raise
+
+    async def on_stop(self) -> None:
+        """Stop the plugin - clean shutdown of MCP server."""
+        if self._mounted:
+            self.logger.info("MCP server shutting down")
+            self._mounted = False

microsoft_teams_mcpplugin-0.0.1a5/src/microsoft/teams/mcpplugin/transport.py

@@ -0,0 +1,69 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+import asyncio
+from contextlib import asynccontextmanager
+from typing import Awaitable, Callable, Dict, Mapping, Optional, Union
+
+from mcp.client.sse import sse_client
+from mcp.client.streamable_http import streamablehttp_client
+
+ValueOrFactory = Union[str, Callable[[], Union[str, Awaitable[str]]]]
+
+
+@asynccontextmanager
+async def create_streamable_http_transport(
+    url: str,
+    headers: Optional[Mapping[str, ValueOrFactory]] = None,
+):
+    """Create a streamable HTTP transport for MCP communication."""
+    resolved_headers: Dict[str, str] = {}
+    if headers:
+        for key, value in headers.items():
+            if callable(value):
+                resolved_value = value()
+                if asyncio.iscoroutine(resolved_value):
+                    resolved_value = await resolved_value
+                resolved_headers[key] = str(resolved_value)
+            else:
+                resolved_headers[key] = str(value)
+
+    async with streamablehttp_client(url, headers=resolved_headers) as (read_stream, write_stream, _):
+        yield read_stream, write_stream
+
+
+@asynccontextmanager
+async def create_sse_transport(
+    url: str,
+    headers: Optional[Mapping[str, ValueOrFactory]] = None,
+):
+    """Create an SSE transport for MCP communication."""
+    resolved_headers: Dict[str, str] = {}
+    if headers:
+        for key, value in headers.items():
+            if callable(value):
+                resolved_value = value()
+                if asyncio.iscoroutine(resolved_value):
+                    resolved_value = await resolved_value
+                resolved_headers[key] = str(resolved_value)
+            else:
+                resolved_headers[key] = str(value)
+
+    async with sse_client(url, headers=resolved_headers) as (read_stream, write_stream):
+        yield read_stream, write_stream
+
+
+def create_transport(
+    url: str,
+    transport_type: str = "streamable_http",
+    headers: Optional[Mapping[str, ValueOrFactory]] = None,
+):
+    """Create the appropriate transport based on transport type."""
+    if transport_type == "streamable_http":
+        return create_streamable_http_transport(url, headers)
+    elif transport_type == "sse":
+        return create_sse_transport(url, headers)
+    else:
+        raise ValueError(f"Unsupported transport type: {transport_type}")