[Feature] New API to discover, fetch, and call tools from server extensions

jupyter_server/extension/manager.py

@@ -5,6 +5,7 @@
 import importlib
 from itertools import starmap
 
+import jsonschema
 from tornado.gen import multi
 from traitlets import Any, Bool, Dict, HasTraits, Instance, List, Unicode, default, observe
 from traitlets import validate as validate_trait
@@ -13,6 +14,37 @@
 from .config import ExtensionConfigManager
 from .utils import ExtensionMetadataError, ExtensionModuleNotFound, get_loader, get_metadata
 
+# probably this should go in it's own file? Not sure where though
+MCP_TOOL_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "name": {"type": "string"},
+        "description": {"type": "string"},
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "type": {"type": "string", "enum": ["object"]},
+                "properties": {"type": "object"},
+                "required": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": ["type", "properties"],
+        },
+        "annotations": {
+            "type": "object",
+            "properties": {
+                "title": {"type": "string"},
+                "readOnlyHint": {"type": "boolean"},
+                "destructiveHint": {"type": "boolean"},
+                "idempotentHint": {"type": "boolean"},
+                "openWorldHint": {"type": "boolean"},
+            },
+            "additionalProperties": True,
+        },
+    },
+    "required": ["name", "inputSchema"],
+    "additionalProperties": False,
+}
+
 
 class ExtensionPoint(HasTraits):
     """A simple API for connecting to a Jupyter Server extension
@@ -97,6 +129,29 @@ def module(self):
         """The imported module (using importlib.import_module)"""
         return self._module
 
+    @property
+    def tools(self):
+        """Structured tools exposed by this extension point, if any."""
+        loc = self.app or self.module
+        if not loc:
+            return {}
+
+        tools_func = getattr(loc, "jupyter_server_extension_tools", None)
+        if not callable(tools_func):
+            return {}
+
+        tools = {}
+        try:
+            definitions = tools_func()
+            for name, tool in definitions.items():
+                # not sure if we should just pick MCP schema or make the schema something the user can pass
+                jsonschema.validate(instance=tool["metadata"], schema=MCP_TOOL_SCHEMA)
+                tools[name] = tool
+        except Exception as e:
+            # not sure if this should fail quietly, raise an error, or log it?
+            print(f"[tool-discovery] Failed to load tools from {self.module_name}: {e}")
+        return tools
+
     def _get_linker(self):
         """Get a linker."""
         if self.app:
@@ -443,6 +498,22 @@ def load_all_extensions(self):
         for name in self.sorted_extensions:
             self.load_extension(name)
 
+    def get_tools(self) -> Dict[str, Any]:
+        """Aggregate tools from all extensions that expose them."""
+        all_tools = {}
+
+        for ext_name, ext_pkg in self.extensions.items():
+            if not ext_pkg.enabled:
+                continue
+
+            for point in ext_pkg.extension_points.values():
+                for name, tool in point.tools.items():  # <— new property!
+                    if name in all_tools:
+                        raise ValueError(f"Duplicate tool name detected: '{name}'")
+                    all_tools[name] = tool
+
+        return all_tools
+
     async def start_all_extensions(self):
         """Start all enabled extensions."""
         # Sort the extension names to enforce deterministic loading

jupyter_server/serverapp.py

@@ -2540,6 +2540,10 @@ def load_server_extensions(self) -> None:
         """
         self.extension_manager.load_all_extensions()
 
+    # is this how I would expose it? and Is this a good name?
+    def get_tools(self):
+        return self.extension_manager.get_tools()
+
     def init_mime_overrides(self) -> None:
         # On some Windows machines, an application has registered incorrect
         # mimetypes in the registry.

jupyter_server/services/contents/handlers.py

@@ -424,6 +424,14 @@ async def post(self, path=""):
         self.finish()
 
 
+# Somehow this doesn't feel like the right service for this to go in?
+class ListToolInfoHandler(APIHandler):
+    @web.authenticated
+    async def get(self):
+        tools = self.serverapp.extension_manager.discover_tools()
+        self.finish({"discovered_tools": tools})
+
+
 # -----------------------------------------------------------------------------
 # URL to handler mappings
 # -----------------------------------------------------------------------------
@@ -441,4 +449,5 @@ async def post(self, path=""):
     (r"/api/contents%s/trust" % path_regex, TrustNotebooksHandler),
     (r"/api/contents%s" % path_regex, ContentsHandler),
     (r"/api/notebooks/?(.*)", NotebooksRedirectHandler),
+    (r"/api/tools", ListToolInfoHandler),
 ]