add notebook support

README.md

@@ -88,6 +88,6 @@ class YourFrameworkAdapter(ToolAdapter):
 - [ ] support for swarm
 - [ ] support for crewAI?
 - [ ] support for remote MCP Servers via SSE
-- [ ] support for jupyter notebook
+- [x] support for jupyter notebook
 - [ ] add tests
 

examples/notebook_usage.ipynb

@@ -0,0 +1,149 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**important note** until this [issue](https://github.com/modelcontextprotocol/python-sdk/issues/156) is fixed stderr is not logged in jupyter environment this means that if your `mcp_server_parameters` have an error or the subprocess running the mcp server fail you won't know about it appart from the fact that the cell just hangs. For now the recommendation would be to try it in a regular python script or to temporarly change `mcp/client/stdio.py`:\n",
+    "\n",
+    "```python\n",
+    "process = await anyio.open_process(\n",
+    "        [server.command, *server.args],\n",
+    "        env=server.env if server.env is not None else get_default_environment(),\n",
+    "        stderr=None,\n",
+    " )\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Async Usage\n",
+    "\n",
+    "Async should just work and is the preferred approach if your agentic framework supports async.\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from typing import Any, Callable, Coroutine\n",
+    "\n",
+    "from mcpadapt.core import MCPAdapt, ToolAdapter\n",
+    "import mcp"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# define a dummy tool adapter that just returns the function for the example.\n",
+    "class DummyToolAdapter(ToolAdapter):\n",
+    "    def adapt(\n",
+    "        self,\n",
+    "        func: Callable[[dict | None], mcp.types.CallToolResult],\n",
+    "        mcp_tool: mcp.types.Tool,\n",
+    "    ):\n",
+    "        return func\n",
+    "\n",
+    "    def async_adapt(\n",
+    "        self,\n",
+    "        afunc: Callable[[dict | None], Coroutine[Any, Any, mcp.types.CallToolResult]],\n",
+    "        mcp_tool: mcp.types.Tool,\n",
+    "    ):\n",
+    "        return afunc"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# define the mcp server parameters to run\n",
+    "serverparams = mcp.StdioServerParameters(\n",
+    "    command=\"uv\",\n",
+    "    args=[\"--quiet\", \"run\", \"../src/echo.py\"],\n",
+    "    env={\"UV_PYTHON\": \"3.12\", **os.environ},\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "meta=None content=[TextContent(type='text', text='hello')] isError=False\n"
+     ]
+    }
+   ],
+   "source": [
+    "async with MCPAdapt(serverparams, adapter=DummyToolAdapter()) as tools:\n",
+    "    echo_tool = tools[0]\n",
+    "    response = await echo_tool({\"text\": \"hello\"})\n",
+    "    print(response)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Sync Usage\n",
+    "\n",
+    "Similary sync should just work as well with the same issues about stderr as above until resolution of the issue."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "meta=None content=[TextContent(type='text', text='hello')] isError=False\n"
+     ]
+    }
+   ],
+   "source": [
+    "with MCPAdapt(serverparams, adapter=DummyToolAdapter()) as tools:\n",
+    "    echo_tool = tools[0]\n",
+    "    response = echo_tool({\"text\": \"hello\"})\n",
+    "    print(response)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

pyproject.toml

@@ -29,6 +29,7 @@ build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
+    "jupyter>=1.1.1",
     "pre-commit>=4.0.1",
     "pytest>=8.3.4",
     "ruff>=0.9.1",