itential-mcp 0.1.0__py3-none-any.whl

itential_mcp/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) 2025 Itential, Inc
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from importlib.metadata import version
+
+from .cli import run
+
+__version__ = version("itential_mcp")
+
+__all__ = ("run",)

itential_mcp/__main__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2025 Itential, Inc
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+import asyncio
+
+from .cli import run
+
+if __name__ == "__main__":
+    asyncio.run(run())

itential_mcp/cli.py

@@ -0,0 +1,162 @@
+# Copyright (c) 2025 Itential, Inc
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+import os
+import sys
+import asyncio
+import argparse
+
+from collections.abc import Sequence
+
+from typing import Any
+
+from . import server
+from . import env
+
+
+def parse_args(args: Sequence) -> dict[str, Any]:
+    """
+    Parses any arguments
+
+    This function will parse the arguments identified by the `args` argument
+    and return a Namespace object with the values.   Typically this is used
+    to parse command line arguments passed when the application starts.
+
+    Args:
+        args (Sequence): The list of arguments to parse
+
+    Returns:
+        dict[str, Any]: Returns a Python dict object that has parsed the args
+
+    Raises:
+        None
+    """
+    parser = argparse.ArgumentParser(prog="itential-mcp")
+
+    # MCP Server arguments
+    server_group = parser.add_argument_group("MCP Server")
+
+    server_group.add_argument(
+        "--transport",
+        default="stdio",
+        help="The MCP server transport to use (default=stdio)"
+    )
+
+    server_group.add_argument(
+        "--host",
+        default="localhost",
+        help="Address to listen for connections on (default=localhost)"
+    )
+
+    server_group.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port to listen for connections on (default=8000)",
+    )
+
+    server_group.add_argument(
+        "--log-level",
+        default="INFO",
+        help="Logging level.  One of DEBUG, INFO, WARNING, ERROR, CRITICAL.  (default=INFO)"
+    )
+
+    # Itential Platform arguments
+    platform_group = parser.add_argument_group("Itential Platform")
+
+    platform_group.add_argument(
+        "--platform-host",
+        default="localhost",
+        help="The host address of Itential Platform to connect to (default=localhost)"
+    )
+
+    platform_group.add_argument(
+        "--platform-port",
+        type=int,
+        default=0,
+        help="The port to use when connecting to Itential Platform (default=0)"
+    )
+
+    platform_group.add_argument(
+        "--platform-disable-tls",
+        action="store_true",
+        help="Disable using TLS to connect to the server (default=False)"
+    )
+
+    platform_group.add_argument(
+        "--platform-disable-verify",
+        action="store_true",
+        help="Disable certificate verification (default=False)",
+    )
+
+    platform_group.add_argument(
+        "--platform-user",
+        default="admin",
+        help="Username to use when authenticating to the server (default=admin)"
+    )
+
+    platform_group.add_argument(
+        "--platform-password",
+        default="admin",
+        help="Password to use when authenticating to the server (default=admin)"
+    )
+
+    platform_group.add_argument(
+        "--platform-client-id",
+        help="Client ID to use when authenticating to the server with OAuth",
+    )
+
+    platform_group.add_argument(
+        "--platform-client-secret",
+        help="Client secret to use when authenticating to the server with OAuth",
+    )
+
+    platform_group.add_argument(
+        "--platform-timeout",
+        type=int,
+        default=30,
+        help="Configure the connection timeout in seconds (default=30)",
+    )
+
+    args = parser.parse_args(args=args)
+
+    kwargs = {}
+
+    for key, value in dict(args._get_kwargs()).items():
+        envkey = f"ITENTIAL_MCP_{key}".upper()
+
+        if key.startswith("platform"):
+            if value is not None:
+                if envkey not in os.environ:
+                    os.environ[envkey] = str(value)
+        else:
+            if isinstance(value, bool):
+                v = env.getbool(envkey, default=value)
+            elif isinstance(value, int):
+                v = env.getint(envkey, default=value)
+            elif isinstance(value, str):
+                v = env.getstr(envkey, default=value)
+            else:
+                v = value
+            kwargs[key] = v
+
+    return kwargs
+
+
+def run() -> int:
+    """
+    Main entry point for the application
+
+    Args:
+        None
+
+    Returns:
+        int:
+
+    Raises:
+        None
+    """
+    try:
+        return asyncio.run(server.run(**parse_args(sys.argv[1:])))
+    except Exception:
+        sys.exit(1)

itential_mcp/client.py

@@ -0,0 +1,182 @@
+# Copyright (c) 2025 Itential, Inc
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+import ipsdk
+
+from ipsdk.platform import AsyncPlatform
+
+import httpx
+
+from . import config
+from . import response
+
+
+class PlatformClient(object):
+
+    def __init__(self):
+        self.client = self._init_client()
+
+    def _init_client(self) -> AsyncPlatform:
+        """
+        Initializes the client connection to Itential Platform
+
+        Args:
+            None
+
+        Returns:
+            AsyncPlatform: An instance of AsyncPlatform
+
+        Raises:
+            None
+        """
+        return ipsdk.platform_factory(want_async=True, **config.get())
+
+    async def _make_response(self, res: httpx.Response) -> response.Response:
+        """
+        Creates a response object and returns it
+
+        Args:
+            res (httpx.Response): The response object returned from the HTTP API
+                request
+
+        Returns:
+            Response: A HTTP Response object
+
+        Raises:
+            None
+        """
+        return response.Response(res)
+
+    async def send_request(
+        self,
+        method: str,
+        path: str,
+        params: dict = None,
+        json: str | bytes | dict | list | None = None
+    ) -> response.Response:
+        """
+        Send the request to the server and return the response
+
+        Args:
+            method (str): The HTTP method to invoke.  This should be one of
+                "GET", "POST", "PUT", "DELETE"
+
+            path (str): The full URL path to send the reques to
+
+            params (dict): A Python dict objec to be converted into a query
+                string and appeneded to the URL
+
+            json (str|bytes|dict|list): A Python object that can be serialized
+                into a JSON object.
+
+        Returns:
+            Response: The HTTP response from the server
+
+        Raises:
+            None
+        """
+        res = await self.client._send_request(method, path, params, json)
+        return await self._make_response(res)
+
+    async def get(
+        self,
+        path: str,
+        params: dict | None = None
+    ) -> response.Response:
+        """
+        Send a HTTP GET request to the server
+
+        Args:
+            path (str): The full path to send the HTTP request o
+
+            params (dict): A Python dict object to be converted to a query
+                string and appended to the path
+
+        Returns:
+            Response: An HTTP Response object from the server
+
+        Raises:
+            None
+        """
+        return await self.send_request(
+            method="GET", path=path, params=params
+        )
+
+    async def post(
+        self,
+        path: str,
+        params: dict | None = None,
+        json: str | dict | list | None = None,
+    ) -> response.Response:
+        """
+        Send a HTTP POST request to the server
+
+        Args:
+            path (str): The full path to send the HTTP request o
+
+            params (dict): A Python dict object to be converted to a query
+                string and appended to the path
+
+            json (str | dict | list): A Python object that can be serialized
+                to a JSON string and sent as the body of the request
+
+        Returns:
+            Response: An HTTP Response object from the server
+
+        Raises:
+            None
+        """
+        return await self.send_request(
+            method="POST", path=path, params=params, json=json
+        )
+
+    async def put(
+        self,
+        path: str,
+        params: dict | None = None,
+        json: str | dict | list | None = None,
+    ) -> response.Response:
+        """
+        Send a HTTP PUT request to the server
+        Args:
+            path (str): The full path to send the HTTP request o
+
+            params (dict): A Python dict object to be converted to a query
+                string and appended to the path
+
+            json (str | dict | list): A Python object that can be serialized
+                to a JSON string and sent as the body of the request
+        Returns:
+            Response: An HTTP Response object from the server
+
+        Raises:
+            None
+        """
+        return await self.send_request(
+            method="PUT", path=path, params=params, json=json
+        )
+
+    async def delete(
+        self,
+        path: str,
+        params: dict | None = None,
+    ) -> response.Response:
+        """
+        Send a HTTP DELETE request to the server
+        Args:
+            path (str): The full path to send the HTTP request o
+
+            params (dict): A Python dict object to be converted to a query
+                string and appended to the path
+
+            json (str | dict | list): A Python object that can be serialized
+                to a JSON string and sent as the body of the request
+        Returns:
+            Response: An HTTP Response object from the server
+
+        Raises:
+            None
+        """
+        return await self.send_request(
+            method="DELETE", path=path, params=params
+        )

itential_mcp/config.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2025 Itential, Inc
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from . import env
+
+
+def get() -> dict:
+    """
+    Load the configuration from the environment
+
+    This function will load the Platform configuration from the environment
+    and return it as a Python dict object.  The returned object can be passed
+    into the `platform_factory(...)` function to create a new instance.
+
+    Args:
+        None
+
+    Returns:
+        dict: Returns a Python dict object that represents the configuration
+
+    Raises:
+        None
+    """
+    return {
+        "host": env.getstr("ITENTIAL_MCP_PLATFORM_HOST", default="localhost"),
+        "port": env.getint("ITENTIAL_MCP_PLATFORM_PORT", default=0),
+
+        "use_tls": not env.getbool("ITENTIAL_MCP_PLATFORM_DISABLE_TLS", default=False),
+        "verify": not env.getbool("ITENTIAL_MCP_PLATFORM_DISABLE_VERIFY", default=False),
+        "timeout": env.getint("ITENTIAL_MCP_PLATFORM_TIMEOUT", default=30),
+
+        "user": env.getstr("ITENTIAL_MCP_PLATFORM_USER", default="admin"),
+        "password": env.getstr("ITENTIAL_MCP_PLATFORM_PASSWORD", default="admin"),
+
+        "client_id": env.getstr("ITENTIAL_MCP_PLATFORM_CLIENT_ID"),
+        "client_secret": env.getstr("ITENTIAL_MCP_PLATFORM_CLIENT_SECRET"),
+    }

itential_mcp/env.py

@@ -0,0 +1,39 @@
+# Copyright (c) 2025 Itential, Inc
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+import os
+
+from typing import Callable, Any
+
+from functools import partial
+
+from . import stringutils
+
+
+def get(f: Callable, key: str, default: Any | None=None) -> Any:
+    """
+    Get the value for key from the current environment
+
+    Args:
+        f (Callable): The function to transform the value
+        key (str): The key to looking in the environment
+        default (Any): The default value to use if the key doesn't exist
+
+    Returns:
+        Any: The transformed value from the environment or the default vaule
+            if the key doesn't exist
+
+    Raises:
+        None
+    """
+    return f(os.getenv(key, default=default))
+
+
+getstr = partial(get, stringutils.tostr)
+getstr.__doc__ = "Get a string value from the environment"
+
+getint = partial(get, stringutils.toint)
+getint.__doc__ = "Get a integer value from the envirnment"
+
+getbool = partial(get, stringutils.tobool)
+getbool.__doc__ = "Get a boolean value from the environment"

itential_mcp/response.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2025 Itential, Inc
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from typing import Any
+
+import httpx
+
+
+class Response(object):
+
+    def __init__(self, res: httpx.Response):
+        """
+        Initialize a new response instance
+
+        Args:
+            res: An instance of httpx.Response
+        """
+        self.response = res
+
+    @property
+    def status_code(self) -> int:
+        """
+        Returns the HTTP status code
+        """
+        return self.response.status_code
+
+    @property
+    def reason(self) -> str:
+        """
+        Returns the HTTP status code message
+        """
+        return self.response.reason_phrase
+
+    @property
+    def text(self) -> str:
+        """
+        Return the response body as text
+        """
+        return self.response.text
+
+    def json(self) -> Any:
+        """
+        Attempt to return the response body as a Python object
+
+        Args:
+            None
+
+        Returns:
+            Any: Returns the response text as a object
+
+        Raises:
+            None
+        """
+        return self.response.json()

itential_mcp/server.py

@@ -0,0 +1,166 @@
+# Copyright (c) 2025 Itential, Inc
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+import os
+import sys
+import inspect
+import importlib.util
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager, AsyncExitStack
+
+from typing import Any, Literal
+
+from fastmcp import FastMCP
+
+from . import client
+
+
+@asynccontextmanager
+async def lifespan(mcp: FastMCP) -> AsyncGenerator[dict[str | Any], None]:
+    """
+    Manage the lifespan of Itential Platform servers
+
+    This function is responsible for creating the client connection to
+    Itential Platform and yielding it to FastMCP to be included in the
+    context.
+
+    Args:
+        mcp (FastMCP): An instance of FastMCP
+
+    Returns:
+        AsyncGenerator: Yields an AsyncGenerator with a dict object
+
+    Raises:
+        None
+    """
+    async with AsyncExitStack():
+        yield {
+            "client": client.PlatformClient()
+        }
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """
+    Register all functions in the tools folder with mcp
+
+    This function will recursively load all modules found in the `tools`
+    folder as long as they module name does not start with underscore (_).  It
+    will then inspect the module to find all public functions and attach
+    them to the instance of mcp as a tool.
+
+    Args:
+        mcp (FastMCP): An instance of FastMCP to attach tools to
+
+    Returns:
+        None
+
+    Raises:
+        None
+    """
+    path = os.path.join(os.path.dirname(os.path.realpath(__file__)), "tools")
+
+    # Get a list of all files in the directory
+    module_files = [f[:-3] for f in os.listdir(path) if f.endswith(".py") and f != "__init__.py"]
+
+    # Import the modules, add them to globals and mcp
+    for module_name in module_files:
+        if not module_name.startswith("_"):
+            spec = importlib.util.spec_from_file_location(module_name, os.path.join(path, f"{module_name}.py"))
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+
+            # Add the module to globals
+            globals()[module_name] = module
+
+            # Inspect the module to retreive all of the functions
+            for name, f in inspect.getmembers(module, inspect.isfunction):
+                if not name.startswith("_"):
+                    mcp.add_tool(f)
+
+
+async def run(
+    transport: str = "stdio",
+    host: str | None = "localhost",
+    port: int = 8000,
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | int = "INFO",
+) -> int:
+    """
+    Run the MCP server
+
+    This function will run the MCP server using the configured transport
+    option.
+
+    Args:
+        args (Sequence | None):
+        transport (str): Server transport to use.  Valid values for this
+            argument are `sse` or `stdio`.  The default value is `stdio`
+
+        host (str | None): The host to run the server on.  The default
+            value for host is "localhost"
+
+        port (int): The port on the host to listen for connections on.  The
+            default value for port is 0.
+
+    Returns:
+        int: Returns a int value as the return code from running the server
+            A value of 0 is success and any other value is an error
+
+    Raises:
+        ValueError: When the value of transport is not a valid value
+        ValueError: When the value of log_level is not a valid value
+    """
+    if transport not in ("stdio", "sse"):
+        raise ValueError("invalid setting for transport")
+
+    if isinstance(log_level, str):
+        if log_level.upper() not in ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"):
+            raise ValueError("invalid setting for log_level")
+
+
+
+    # Initialize FastMCP server
+    # Available keyword args:
+    #   - name
+    #   - instructions
+    #   - lifespan
+    #   - tags
+    #   - host
+    #   - port
+    #   - log_level
+    #   - on_duplicate_tools
+    #   - on_duplicate_resources
+    #   - on_duplicate_prompts
+    #
+    # The server settings can also be passed using env variables prefixed
+    # with FASTMCP_SERVER_
+    mcp = FastMCP(
+        name="Itential Platform MCP",
+        instructions="Itential tools and resources for interacting with Itential Platform",
+        lifespan=lifespan,
+        log_level=log_level.upper(),
+    )
+
+    try:
+        register_tools(mcp)
+    except Exception as exc:
+        print(f"ERROR: failed to  import tool: {str(exc)}", file=sys.stderr)
+        sys.exit(1)
+
+    kwargs = {
+        "transport": transport,
+    }
+
+    if transport == "sse":
+        kwargs.update({
+            "host": host,
+            "port": port,
+        })
+
+    try:
+        await mcp.run_async(**kwargs)
+    except KeyboardInterrupt:
+        sys.exit(0)
+    except Exception as exc:
+        print(f"ERROR: failed to  import tool: {str(exc)}", file=sys.stderr)
+        sys.exit(1)