Merge branch 'main' into dependabot/pip/cloud-infrastructure/compute-including-hpc/ai-infra-gpu/ai-infrastructure/bionemo/alphafold2-oke/helm/nbconvert-7.17.0

Author: Ainura-Djumagulov

ai/gen-ai-agents/mcp-oci-integration/files/consumption_utils.py

@@ -0,0 +1,184 @@
+"""
+File name: mcp_agenda.py
+Author: Luigi Saetta
+Date last modified: 2025-12-04
+Python Version: 3.11
+
+Description:
+    This module implements an MCP (Model Context Protocol) server for agenda and calendar management.
+    It provides tools to list events overlapping with a given time interval, create new events with automatic conflict detection,
+    and delete events by unique ID, using ISO date formats and structured JSON outputs for events and conflicts.
+
+Usage:
+    Import this module to use its tools or run it as a standalone MCP server.
+    Example:
+        from mcp_servers.mcp_agenda import create_event
+
+        event = create_event(title="Meeting", start_date="2025-12-05T10:00:00", end_date="2025-12-05T11:00:00")
+        # Or run the server: python mcp_agenda.py
+
+License:
+    This code is released under the MIT License.
+
+Notes:
+    This is part of the MCP-OCI integration framework and uses in-memory storage for events (persistent options can be added).
+    Tools return dictionaries with details like event IDs, conflicts, and messages for easy integration with MCP agents.
+
+Warnings:
+    This module is in development and may change in future versions. Ensure date inputs are in valid ISO formats to avoid errors,
+    and note that events are created even with conflicts—handle them appropriately in applications.
+"""
+
+from typing import List, Dict, Any, Optional
+from mcp_utils import create_server, run_server
+from agenda_utils import add_event, get_events, delete_event as delete_event_util
+from agenda_utils import init_random_events_for_current_week
+
+mcp = create_server("Agenda MCP")
+
+
+@mcp.tool()
+def list_events(start_date: str, end_date: str) -> Dict[str, Any]:
+    """
+    List all events in the agenda that overlap with the given interval.
+
+    Parameters
+    ----------
+    start_date : str
+        Start of the desired interval.
+        Accepted formats:
+        - 'YYYY-MM-DDTHH:MM:SS'
+        - 'YYYY-MM-DD HH:MM'
+        - 'YYYY-MM-DD'
+    end_date : str
+        End of the desired interval.
+        Same accepted formats as start_date.
+
+    Returns
+    -------
+    dict
+        JSON object with a single key "events":
+
+        {
+          "events": [
+            {
+              "id": int,
+              "title": str,
+              "start": str,  # ISO 8601
+              "end": str,     # ISO 8601
+              "notes": str
+            },
+            ...
+          ]
+        }
+
+    Notes
+    -----
+    - Use the 'id' field from each event when you need to delete it.
+    """
+    events = get_events(start_date, end_date)
+
+    return {"events": events}
+
+
+@mcp.tool()
+def create_event(
+    title: str,
+    start_date: str,
+    end_date: str,
+    notes: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Create a new event in the agenda and report any scheduling conflicts.
+
+    Parameters
+    ----------
+    title : str
+        Short human-readable title of the event.
+    start_date : str
+        Start of the event.
+        Accepted formats:
+        - 'YYYY-MM-DDTHH:MM:SS'
+        - 'YYYY-MM-DD HH:MM'
+        - 'YYYY-MM-DD'
+    end_date : str
+        End of the event.
+        Must be strictly after start_date.
+        Same accepted formats as start_date.
+    notes : str, optional
+        Optional longer description or notes for the event.
+
+    Returns
+    -------
+    dict
+        JSON object describing the created event and any conflicts:
+
+        {
+          "id": int,
+          "title": str,
+          "start": str,         # ISO 8601
+          "end": str,           # ISO 8601
+          "notes": str | None,
+          "has_conflict": bool,
+          "conflicts": [
+            {
+              "id": int,
+              "title": str,
+              "start": str,     # ISO 8601
+              "end": str,        # ISO 8601
+              "notes": str | None
+            },
+            ...
+          ]
+        }
+
+    Notes
+    -----
+    - The event is always created, even if there are conflicts.
+    - If dates are invalid or end_date <= start_date, a ValueError is raised.
+    - The returned 'id' is the unique identifier to use for deletion.
+    """
+    return add_event(title, start_date, end_date, notes=notes)
+
+
+@mcp.tool()
+def delete_event(event_id: int) -> Dict[str, Any]:
+    """
+    Delete a single event by its unique ID.
+
+    Parameters
+    ----------
+    event_id : int
+        The unique identifier of the event, as returned by create_event or
+        list_events (field 'id').
+
+    Returns
+    -------
+    dict
+        JSON-safe result object:
+
+        {
+          "deleted": bool,
+          "event": {
+              "id": int,
+              "title": str,
+              "start": str,  # ISO 8601
+              "end": str,     # ISO 8601
+              "notes": str | None
+          } | None,
+          "message": str
+        }
+
+    Notes
+    -----
+    - If no event with the given ID exists, 'deleted' will be False and
+      'event' will be null.
+    """
+    return delete_event_util(event_id)
+
+
+if __name__ == "__main__":
+    # initialise the agenda with some random events for the current week
+    init_random_events_for_current_week()
+
+    run_server(mcp)

ai/gen-ai-agents/mcp-oci-integration/files/mcp_servers/mcp_agenda.py

@@ -0,0 +1,169 @@
+"""
+File name: mcp_base.py
+Author: Luigi Saetta
+Date last modified: 2025-12-04
+Python Version: 3.11
+
+Description:
+    This module provides the base class for MCP (Model Context Protocol) servers.
+    It defines abstract methods and common functionality for server implementations,
+    such as handling requests, authentication, and error management in a distributed system.
+
+Usage:
+    Import this module and subclass MCPBase to create custom server implementations.
+    Example:
+        from mcp_servers.mcp_base import MCPBase
+
+        class MyServer(MCPBase):
+            def process_request(self, request_data):
+                # Implement custom logic here
+                pass
+
+License:
+    This code is released under the MIT License.
+
+Notes:
+    This is a foundational part of the MCP-OCI integration framework, designed for extensibility.
+    Subclasses should implement all abstract methods to ensure compatibility with MCP tools and APIs.
+
+Warnings:
+    This module is in development and may change in future versions. Ensure subclasses handle
+    potential breaking changes in abstract method signatures.
+"""
+
+from typing import Callable, Optional
+from functools import wraps
+
+from mcp_utils import create_server, run_server
+from utils import get_console_logger
+
+
+def expose_tool(name: Optional[str] = None, description: Optional[str] = None):
+    """
+    Marker decorator for instance methods to export as MCP tools.
+
+    Args:
+        name: Optional tool name; defaults to method name.
+        description: Optional doc override shown in MCP discovery.
+    """
+
+    def _decorator(fn: Callable):
+        setattr(fn, "_mcp_expose", True)
+        if name:
+            setattr(fn, "_mcp_tool_name", name)
+        if description:
+            setattr(fn, "_mcp_tool_desc", description)
+        return fn
+
+    return _decorator
+
+
+class BaseMCPServer:
+    """
+    Subclass and decorate instance methods with @expose_tool to export them.
+
+    Parameters
+    ----------
+    server_name : str
+        The MCP server name (surfaced in discovery).
+    debug : bool
+        Toggle extra logging.
+    wrap_result : bool
+        If True, wrap successful results as {"result": <value>}.
+    on_call : Optional[Callable[[str, tuple, dict], None]]
+        Optional hook invoked before each tool call with (tool_name, args, kwargs).
+    on_error : Optional[Callable[[str, Exception], None]]
+        Optional hook invoked when a tool raises.
+    """
+
+    def __init__(
+        self,
+        server_name: str,
+        *,
+        debug: bool = False,
+        wrap_result: bool = False,
+        on_call: Optional[Callable[[str, tuple, dict], None]] = None,
+        on_error: Optional[Callable[[str, Exception], None]] = None,
+    ):
+        self.server_name = server_name
+        self.debug = debug
+        self.wrap_result = wrap_result
+        self.on_call = on_call
+        self.on_error = on_error
+
+        self.logger = get_console_logger()
+        # SECURITY/JWT is handled entirely by create_server; nothing here.
+        self.mcp = create_server(server_name)
+
+        self._register_tools()
+
+    def _wrap_tool(self, method: Callable, tool_name: str, tool_desc: Optional[str]):
+        """
+        Wrap the bound method with logging, optional hooks, result wrapping, and error handling.
+        """
+
+        @wraps(method)
+        def _wrapped(*args, **kwargs):
+            if self.debug:
+                self.logger.info(
+                    "[%s] %s called | args=%s kwargs=%s",
+                    self.server_name,
+                    tool_name,
+                    args,
+                    kwargs,
+                )
+            if self.on_call:
+                try:
+                    self.on_call(tool_name, args, kwargs)
+                except Exception:
+                    # Never let hooks break the tool
+                    pass
+
+            try:
+                out = method(*args, **kwargs)
+                # Uniform, JSON-serializable success path
+                return {"result": out} if self.wrap_result else out
+            except Exception as e:
+                if self.on_error:
+                    try:
+                        self.on_error(tool_name, e)
+                    except Exception:
+                        pass
+                self.logger.exception(
+                    "[%s] %s error: %s", self.server_name, tool_name, e
+                )
+                # Always return a serializable error envelope
+                return {"error": str(e)}
+
+        # Description for MCP discovery
+        if tool_desc:
+            _wrapped.__doc__ = tool_desc
+        elif not getattr(_wrapped, "__doc__", None):
+            _wrapped.__doc__ = f"MCP tool: {tool_name}"
+
+        # Programmatic registration (same effect as @mcp.tool)
+        self.mcp.tool(_wrapped)
+        return _wrapped
+
+    def _register_tools(self):
+        """
+        Find and register all @expose_tool methods.
+        """
+        for attr_name in dir(self):
+            if attr_name.startswith("_"):
+                continue
+            method = getattr(self, attr_name)
+            if not callable(method):
+                continue
+            if getattr(method, "_mcp_expose", False):
+                tool_name = getattr(method, "_mcp_tool_name", attr_name)
+                tool_desc = getattr(method, "_mcp_tool_desc", None)
+                self._wrap_tool(method, tool_name, tool_desc)
+
+    def run(self):
+        """
+        Delegate to shared run_server (reads host/port etc. from CLI).
+        """
+        if self.debug:
+            self.logger.info("Starting MCP server '%s'...", self.server_name)
+        run_server(self.mcp)