annotations as tool metadata (#164)

* Annotations as exposed as tool metadata.

Internal changes:

* Moving logic to run test server into utils. 
* Creating a way to run a server as a background task for the async test path.
* Adding this as an end to end test.

Author: eyurtsev

langchain_mcp_adapters/tools.py

@@ -53,7 +53,8 @@ def convert_mcp_tool_to_langchain_tool(
     Args:
         session: MCP client session
         tool: MCP tool to convert
-        connection: Optional connection config to use to create a new session if a `session` is not provided
+        connection: Optional connection config to use to create a new session
+                    if a `session` is not provided
 
     Returns:
         a LangChain tool
@@ -81,6 +82,7 @@ async def call_tool(
         args_schema=tool.inputSchema,
         coroutine=call_tool,
         response_format="content_and_artifact",
+        metadata=tool.annotations.model_dump() if tool.annotations else None,
     )
 
 
@@ -91,12 +93,9 @@ async def load_mcp_tools(
 ) -> list[BaseTool]:
     """Load all available MCP tools and convert them to LangChain tools.
 
-    Args:
-        session: MCP client session
-        connection: Optional connection config to use to create a new session if a `session` is not provided
-
     Returns:
-        a list of LangChain tools
+        list of LangChain tools. Tool annotations are returned as part
+        of the tool metadata object.
     """
     if session is None and connection is None:
         raise ValueError("Either a session or a connection config must be provided")
@@ -109,7 +108,8 @@ async def load_mcp_tools(
     else:
         tools = await session.list_tools()
 
-    return [
+    converted_tools = [
         convert_mcp_tool_to_langchain_tool(session, tool, connection=connection)
         for tool in tools.tools
     ]
+    return converted_tools

pyproject.toml

@@ -31,10 +31,15 @@ test = [
 
 [tool.pytest.ini_options]
 minversion = "8.0"
-addopts = "-ra -q -v"
+# -ra: Report all extra test outcomes (passed, skipped, failed, etc.)
+# -q: Enable quiet mode for less cluttered output
+# -v: Enable verbose output to display detailed test names and statuses
+# --durations=5: Show the 10 slowest tests after the run (useful for performance tuning)
+addopts = "-ra -q -v --durations=5"
 testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_functions = ["test_*"]
+asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 
 [tool.ruff]

tests/conftest.py

@@ -5,7 +5,7 @@
 
 import pytest
 
-from tests.utils.websocket import run_server
+from tests.utils import run_server
 
 
 @pytest.fixture

tests/test_tools.py

@@ -12,11 +12,13 @@
 )
 from mcp.types import Tool as MCPTool
 
+from langchain_mcp_adapters.client import MultiServerMCPClient
 from langchain_mcp_adapters.tools import (
     _convert_call_tool_result,
     convert_mcp_tool_to_langchain_tool,
     load_mcp_tools,
 )
+from tests.utils import run_streamable_http
 
 
 def test_convert_empty_text_content():
@@ -207,3 +209,44 @@ async def mock_call_tool(tool_name, arguments):
     assert result2 == ToolMessage(
         content="tool2 result with {'param1': 'test2', 'param2': 2}", name="tool2", tool_call_id="2"
     )
+
+
+@pytest.mark.asyncio
+async def test_load_mcp_tools_with_annotations(
+    socket_enabled,
+) -> None:
+    """Test load mcp tools with annotations."""
+    from mcp.server import FastMCP
+    from mcp.types import ToolAnnotations
+
+    server = FastMCP(port=8181)
+
+    @server.tool(
+        annotations=ToolAnnotations(title="Get Time", readOnlyHint=True, idempotentHint=False)
+    )
+    def get_time() -> str:
+        """Get current time"""
+        return "5:20:00 PM EST"
+
+    async with run_streamable_http(server):
+        # Initialize client without initial connections
+        client = MultiServerMCPClient(
+            {
+                "time": {
+                    "url": "http://localhost:8181/mcp/",
+                    "transport": "streamable_http",
+                },
+            }
+        )
+        # pass
+        tools = await client.get_tools(server_name="time")
+        assert len(tools) == 1
+        tool = tools[0]
+        assert tool.name == "get_time"
+        assert tool.metadata == {
+            "title": "Get Time",
+            "readOnlyHint": True,
+            "idempotentHint": False,
+            "destructiveHint": None,
+            "openWorldHint": None,
+        }

tests/utils/websocket.py tests/utils.pytests/utils/websocket.py renamed to tests/utils.py

@@ -1,6 +1,10 @@
+import asyncio
+import contextlib
 import time
+from typing import AsyncGenerator
 
 import uvicorn
+from mcp.server.fastmcp import FastMCP
 from mcp.server.websocket import websocket_server
 from starlette.applications import Starlette
 from starlette.routing import WebSocketRoute
@@ -34,3 +38,28 @@ def run_server(server_port: int) -> None:
     # Give server time to start
     while not server.started:
         time.sleep(0.5)
+
+
+@contextlib.asynccontextmanager
+async def run_streamable_http(server: FastMCP) -> AsyncGenerator[None, None]:
+    """Run the server in a separate task exposing a streamable HTTP endpoint.
+
+    The endpoint will be available at `http://localhost:{server.settings.port}/mcp/`.
+    """
+    app = server.streamable_http_app()
+    config = uvicorn.Config(
+        app,
+        host="localhost",
+        port=server.settings.port,
+    )
+    server = uvicorn.Server(config)
+    serve_task = asyncio.create_task(server.serve())
+
+    while not server.started:
+        await asyncio.sleep(0.1)
+
+    try:
+        yield
+    finally:
+        server.should_exit = True
+        await serve_task