matlab-simulink-mcp 0.1.0__py3-none-any.whl

matlab_simulink_mcp/functions.py

@@ -0,0 +1,194 @@
+import asyncio, tempfile
+from pathlib import Path
+from difflib import SequenceMatcher
+
+from fastmcp.exceptions import ToolError
+from fastmcp.utilities.types import Image
+from fastmcp.server.dependencies import get_context
+
+from matlab_simulink_mcp.state import logger
+from matlab_simulink_mcp.security import check_path, check_code
+
+# TODO: figure out how to undo stuff in simulink
+# TODO: maybe add system prompt as a server resource
+# TODO: Later implement a canvas based editor
+
+def _get_state() -> dict:
+    return get_context().request_context.lifespan_context
+
+def _get_engine():
+    eng = _get_state().eng
+    if eng is None:
+        raise ToolError("Could not access MATLAB. Run matlab.engine.shareEngine"
+        " in MATLAB, and then use access_matlab tool to reconnect.")
+    return eng 
+
+def _raise_error(e: Exception):
+    logger.exception(e) 
+    raise ToolError(str(e).strip().splitlines()[-1])
+
+def _clean_evalc(s: str) -> str:
+    return "\n".join(line.strip() for line in s.splitlines() if line.strip())
+
+def _get_image(path) -> Image:
+    path = Path(str(path))
+    data = path.read_bytes()
+    path.unlink(missing_ok=True)
+    return Image(data=data, format="png")
+
+
+async def access_matlab() -> str:
+    """Connect to MATLAB."""
+
+    try:
+        _get_engine()
+        return f"Already connected to MATLAB session: {_get_state().session}"
+    except ToolError:
+        try:
+            await asyncio.to_thread(_get_state().connect_engine)
+            _get_engine()
+            return f"Connected to MATLAB session: {_get_state().session}"
+        except ToolError as e:
+            raise
+    except Exception as e:
+        _raise_error(e)
+    
+
+async def read_simulink_system(path: str, detail: bool=False, open: bool=False) -> Image | dict:
+    """
+    View a Simulink system/subsystem as either a PNG image or a detailed dictionary (if detail=True).
+    Optionally open the object in MATLAB desktop.
+    Detail only recommended when exact port tags or other details are needed, as it can be verbose.
+    """
+
+    eng = _get_engine()
+    check_path(path)
+    
+    parent, _, rest = path.partition("/")
+    parent = parent.removesuffix(".slx")
+    path = parent if not rest else f"{parent}/{rest}"
+          
+    try:
+        if detail:
+            return await asyncio.to_thread(eng.describe_system, path, parent, open, nargout=1)
+        else:
+            ss_path = await asyncio.to_thread(eng.snapshot_system, path, parent, open, nargout=1)
+            return _get_image(ss_path)
+    except Exception as e:
+        _raise_error(e)
+
+  
+async def read_matlab_code(path: str, open: bool=False) -> str:
+    """
+    Read the contents of a MATLAB script (.m) or text file.
+    Optionally open the file in MATLAB desktop.
+    """
+
+    eng = _get_engine()
+    check_path(path)
+    
+    try:
+        if open:
+            await asyncio.to_thread(eng.edit, path, nargout=0)
+        return await asyncio.to_thread(eng.fileread, path, nargout=1)
+    except Exception as e:
+        _raise_error(e)   
+
+
+async def save_matlab_code(code: str, path: str, overwrite: bool=False) -> str:
+    """
+    Validate and save MATLAB code to a .m file.
+    Optionally overwrite if the file already exists.
+    """
+
+    eng = _get_engine()
+    check_path(path)
+    blacklist = _get_state().blacklist
+    check_code(code, blacklist)
+
+    mode = "w" if overwrite else "x"
+
+    try:
+        cwd = await asyncio.to_thread(eng.pwd, nargout=1)
+        abs_path = Path(str(cwd)) / path
+        abs_path.parent.mkdir(parents=True, exist_ok=True) 
+        with abs_path.open(mode) as f:
+            f.write(code)
+ 
+        issues = await asyncio.to_thread(eng.validate_code, path)
+        if issues:
+            return "Code saved but failed validation with errors:\n" + "\n".join(issues)
+        else:
+            return "Code saved and validated successfully."
+        
+    except Exception as e:
+        _raise_error(e) 
+
+
+async def run_matlab_code(code: str, get_images: bool=False) -> tuple[str, *tuple[Image, ...]]:
+    """
+    Execute MATLAB code and return command window output as a string and images (if asked).
+    Interact programatically with Simulink if the action is not covered by a tool.
+    """
+
+    eng = _get_engine()
+    blacklist = _get_state().blacklist
+    check_code(code, blacklist)
+
+    imgs: list[Image] = []
+
+    try:
+        if get_images:
+            await asyncio.to_thread(eng.close, 'all', nargout=0)
+
+        try:
+            cwd = await asyncio.to_thread(eng.pwd, nargout=1)
+            abs_path = Path(str(cwd)) / "canvas.m"
+            abs_path.parent.mkdir(parents=True, exist_ok=True) 
+            with abs_path.open("w") as f:
+                f.write(code)
+        except PermissionError:
+            with tempfile.NamedTemporaryFile("w", suffix=".m", delete=False) as f:
+                f.write(code)
+                abs_path = Path(f.name)
+            pretext = "Could not run from current working directory. Running from temporary directory:\n"
+    
+        text = _clean_evalc(await asyncio.to_thread(eng.evalc, f"run('{str(abs_path)}')", nargout=1))
+        if pretext:
+            text = pretext + text
+
+        abs_path.unlink(missing_ok=True)
+        
+        await asyncio.to_thread(eng.format_system, nargout=0)
+
+        img_paths = await asyncio.to_thread(eng.get_images, nargout=1)
+        imgs = [_get_image(p) for p in img_paths]
+
+        return (text, *imgs) 
+
+    except Exception as e:
+        _raise_error(e)
+            
+
+def search_library(query: str) -> list:
+    """
+    Search the Simulink block library for a block name and return matching source paths.
+    """
+
+    try: 
+        simlib = _get_state().simlib
+        candidates = [(name, path) for name, entry in simlib.items() for path in entry["paths"]]
+        ranked = sorted(
+            candidates,
+            key=lambda item: SequenceMatcher(None, query.lower(), item[0].lower()).ratio(),
+            reverse=True
+        )
+        return [path for _, path in ranked[:3]]
+    
+    except Exception as e:
+       _raise_error(e)
+    
+# TODO remember the newline thing for \n 
+# ['VehicleWithFourSpeedTransmission/Inertia', newline, 'Impeller']
+
+

matlab_simulink_mcp/installer/installer.py

@@ -0,0 +1,160 @@
+import sys, ctypes, platform, time, subprocess
+from pathlib import Path
+
+
+system = platform.system()
+
+def verify_matlab_path(user_input: str) -> Path | None:
+    """Validate that a user-specified directory contains MATLAB Engine setup."""
+    while True:
+        if not user_input:
+            print("Aborting installation operation.")
+            return None
+
+        path = Path(user_input).expanduser().resolve()
+        if path.is_dir():
+            setup_path = path / "extern" / "engines" / "python" / "setup.py"
+            if setup_path.exists():
+                return setup_path.parent
+            else:
+                user_input = input(
+                    f"MATLAB Python engine setup not found at {setup_path}.\n"
+                    f"Please enter a valid MATLAB installation directory or press Enter to abort: "
+                ).strip()
+        else:
+            user_input = input(
+                "Invalid directory. Please enter a correct path to a MATLAB installation, or press Enter to abort: "
+            ).strip()
+
+
+def get_matlab_path() -> Path | None:
+    system = platform.system()
+    if system == "Windows": 
+        parent = Path("C:/Program Files/MATLAB") 
+    elif system == "Linux": 
+        parent = Path("/usr/local/MATLAB") 
+    elif system == "Darwin": 
+        parent = Path("/Applications") 
+    else: 
+        raise OSError(f"Unsupported OS: {system}.")
+
+    installations = [p for p in parent.glob("R20[2-9][0-9][ab]*") if p.is_dir()]
+    installations.sort()
+
+    try:
+        if not installations:
+            print("No MATLAB installations found in default directories.")
+            choice = input("Please enter a path to MATLAB installation (or press Enter to abort): ").strip()
+            return verify_matlab_path(choice)
+
+        elif len(installations) == 1:
+            matlab_path = installations[0]
+            print(f"Found a MATLAB installation at {matlab_path}")
+            choice = input(
+                "Enter y to install MATLAB Engine from this installation (requires admin permissions), \n "
+                "or enter another path (or press Enter to abort): "
+            ).strip()
+            if choice.lower() == "y":
+                return verify_matlab_path(str(matlab_path))
+            else:
+                return verify_matlab_path(choice)
+
+        else:  # multiple installs
+            print("Multiple MATLAB installations found:")
+            for i, inst in enumerate(installations, 1):
+                print(f"[{i}] {inst}")
+
+            while True:
+                choice = input("Select installation by number (installing requires admin permissions), \n "
+                "Or, Enter another installation path (or press Enter to abort): ").strip()
+                if not choice:
+                    print("Aborting by user choice.")
+                    return None
+                if choice.isdigit():
+                    idx = int(choice)
+                    if 1 <= idx <= len(installations):
+                        return verify_matlab_path(str(installations[idx - 1]))
+                    else:
+                        print("Invalid selection.")
+                        continue
+                else:
+                    return verify_matlab_path(choice)
+
+    except KeyboardInterrupt:
+        print("Aborted by user (Ctrl+C).")
+        return None
+    
+
+from matlab_simulink_mcp.installer import win_elevate
+win_install_log = "install.log"
+
+def install_engine_win(setup_path: Path):
+    script = Path(win_elevate.__file__).resolve()
+    status = script.with_name(win_install_log)
+
+    args = subprocess.list2cmdline([str(script), str(setup_path)])
+    ret = ctypes.windll.shell32.ShellExecuteW(None, "runas", sys.executable, args, None, 1)
+    if ret <= 32:
+        raise RuntimeError("Installation failed due to permission issues or some other error.")
+    
+    for _ in range(15):
+        if status.exists():
+            lines = open(status).read().strip().splitlines()
+            if lines:
+                last = lines[-1]
+                if last == "0":
+                    #status.unlink() # had to comment because claude sends request twice in init so it couldnt delete this
+                    return 
+                elif last.isdigit():
+                    e = "\n".join(lines[:-1])
+                    #status.unlink()
+                    raise RuntimeError(f"Failed to install MATLAB engine. \n: {e}")
+        time.sleep(1)
+    raise TimeoutError("Installer did not finish in time.")
+
+
+def install_engine_mac_linux(setup_path: Path):
+    subprocess.run(
+        ["sudo", sys.executable, "setup.py", "install"],
+        cwd=setup_path,
+        check=True)
+
+
+def install_engine():
+    try: 
+        print("***MATLAB Engine for Python API Package Installer***")
+        print("This process will install the matlab.engine package from a MATLAB installation on this machine. \n")
+        setup_path = get_matlab_path()
+        if not setup_path:
+            sys.exit(1)
+
+        print(f"Installing MATLAB engine into current Python environment from: \n {setup_path}")
+
+        time.sleep(2) # Wait for a while so that user sees that they need to grant permission.
+
+        if system == "Windows":
+            install_engine_win(setup_path)
+        elif system in ["Linux", "Darwin"]:
+            install_engine_mac_linux(setup_path)
+        else:
+            raise OSError(f"Unsupported OS: {system}.")
+        
+        print(f"Installation completed successfully.")
+        sys.exit(0)
+
+    except KeyboardInterrupt:
+        print("Aborted by user (Ctrl+C).")
+        sys.exit(1)
+        
+    except Exception as e:
+        print(str(e))
+        quit = input("Press any key to close.")
+        if quit: 
+            sys.exit(1)
+
+if __name__ == "__main__":
+    install_engine()
+
+
+
+                

matlab_simulink_mcp/installer/launcher.py

@@ -0,0 +1,45 @@
+import subprocess, sys, time, platform
+from pathlib import Path
+
+
+def run() -> int:
+    import matlab_simulink_mcp.installer.installer as installer
+
+    # Prevent multiple installation script launches
+    lockfile = Path.home() / ".matlab_engine_install.lock"
+    if lockfile.exists():   
+        return -1 # wait command, essentially proceed but wait.
+    lockfile.write_text("running")
+    
+    try: 
+        time.sleep(2)
+        # Launch installation process 
+        system = platform.system()
+        if system == "Windows": 
+            proc = subprocess.Popen(
+                [sys.executable, "-m", installer.__name__],
+                creationflags=subprocess.CREATE_NEW_CONSOLE
+            )
+        elif system == "Darwin": 
+            proc = subprocess.Popen(["open", "-a", "Terminal", sys.executable, "-m", installer.__name__])
+        elif system == "Linux":
+            proc = subprocess.Popen(["x-terminal-emulator", "-e", sys.executable, "-m", installer.__name__])
+
+        # Wait for installation to finish
+        ret = proc.wait()
+
+        time.sleep(2) # ensuring that installed package is now recognized
+
+        # Return installation status (ret returns 1 if error)
+        if ret == 1:
+            return 0
+        if ret == 0:
+            return 1
+    
+    finally:
+        if lockfile.exists():
+             lockfile.unlink()
+
+if __name__ == "__main__":
+    run()
+

matlab_simulink_mcp/installer/win_elevate.py

@@ -0,0 +1,18 @@
+import subprocess, sys, time
+from pathlib import Path
+
+def install(engine_dir):
+    log_file = Path(__file__).with_name("install.log")
+    with open(log_file, "w") as f:
+        proc = subprocess.run(
+            [sys.executable, "setup.py", "install"],
+            cwd=engine_dir,
+            stdout=f,
+            stderr=subprocess.STDOUT
+        )
+        f.write(f"\n{proc.returncode}\n")
+        time.sleep(2)  
+
+if __name__ == "__main__":
+    engine_dir = sys.argv[1]
+    install(engine_dir)

matlab_simulink_mcp/log_utils.py

@@ -0,0 +1,112 @@
+import sys, logging, platform, subprocess, shutil
+
+from pathlib import Path
+from platformdirs import user_log_dir
+from logging.handlers import RotatingFileHandler
+
+
+def create_log_file(filename: str, dir: Path | None) -> Path:
+    """Creates a log file in the given directory or user log directory (if former fails or isn't specified)."""
+
+    filename = Path(filename)
+    if filename.suffix != ".log":
+        filename = filename.with_suffix(".log")
+
+    if dir:
+        try:
+            dir = Path(dir)
+            dir.mkdir(parents=True, exist_ok=True)
+        except PermissionError:
+            dir = None
+
+    if dir is None:
+        dir = user_log_dir(filename.stem, appauthor=False)
+        dir.mkdir(parents=True, exist_ok=True)
+
+    return dir / filename
+
+
+def create_logger(name: str, log_file: Path) -> logging.Logger:
+    """Sets up a logger with stderr console and rotating file handlers."""
+    logger = logging.getLogger(name)
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(logging.DEBUG)
+    logger.propagate = False
+    fmt = logging.Formatter("%(asctime)s %(levelname)-7s %(message)s")
+
+    ch = logging.StreamHandler(sys.stderr)
+    ch.setLevel(logging.DEBUG)
+    ch.setFormatter(fmt)
+    logger.addHandler(ch)
+
+    fh = RotatingFileHandler(log_file, maxBytes=1_000_000, backupCount=3, encoding="utf-8")
+    fh.setLevel(logging.DEBUG)
+    fh.setFormatter(fmt)
+    logger.addHandler(fh)
+
+    return logger
+
+
+class TrailingConsole:
+    def __init__(self, log_file: Path):
+        self.log_file = str(log_file)
+        self.viewer_process = None
+
+    def open(self):
+        """Open a console window that tails the log file."""
+
+        if self.viewer_process and self.viewer_process.poll() is None:
+            return  # already open
+
+        system = platform.system()
+
+        if system == "Windows":
+            cmd = [
+                "powershell",
+                "-NoExit",
+                "-Command",
+                f'Get-Content -Path "{self.log_file}" -Wait -Tail 0'
+            ]
+            self.viewer_process = subprocess.Popen(
+                cmd, creationflags=subprocess.CREATE_NEW_CONSOLE
+            )
+
+            if self.viewer_process.poll() is not None:
+                raise RuntimeError("Failed to launch trailing console process")
+
+        elif system == "Linux":
+            candidates = [
+                "x-terminal-emulator",
+                "gnome-terminal",
+                "konsole",
+                "xfce4-terminal",
+                "xterm",
+            ]
+            terminal = next((t for t in candidates if shutil.which(t)), None)
+
+            if terminal is None:
+                return
+
+            self.viewer_process = subprocess.Popen([terminal, "-e", f"tail -n 0 -f '{self.log_file}'"])
+
+        elif system == "Darwin":  # macOS
+            full_cmd = f"tail -n 0 -f '{self.log_file}'"
+            subprocess.run([
+                "osascript", "-e",
+                f'tell application "Terminal" to do script "{full_cmd}"'
+            ])
+            self.viewer_process = None
+
+    def close(self):
+        if self.viewer_process and self.viewer_process.poll() is None:
+            self.viewer_process.terminate()
+            self.viewer_process = None
+
+
+def create_console(log_file: Path) -> TrailingConsole:
+    return TrailingConsole(log_file)
+
+    
+

matlab_simulink_mcp/security.py

@@ -0,0 +1,56 @@
+import re
+from pathlib import Path
+from fastmcp.exceptions import ToolError
+
+def strip_matlab_comments(code: str) -> str:
+    """Removes comments from MATLAB code which could then be checked."""
+    lines = []
+    for line in code.splitlines():
+        line = line.split("%", 1)[0]
+        lines.append(line)
+    return "\n".join(lines)
+
+def tokenize(code: str) -> list[str]:
+    """Tokenizes MATLAB code into commands and identifiers."""
+    return re.findall(r"[A-Za-z_]\w*|[^\s]", code)
+
+def check_for_commands(code: str, blacklist: set[str]):
+    """Checks code for forbidden commands and raises error if found."""
+    clean_code = strip_matlab_comments(code)
+    tokens = tokenize(clean_code)
+
+    for token in tokens:
+        if token in blacklist:
+            return f"Use of '{token}' command is not allowed."
+    return None
+
+def check_for_paths(code: str):
+    """Checks string literals in code for forbidden path usage and raises error if found."""
+    
+    literals = re.findall(r"(?:'[^']*'|\"[^\"]*\")", code)
+
+    for literal in literals:
+        path_str = literal[1:-1] 
+        if not path_str:
+            continue
+
+        path = Path(path_str)
+
+        if path.is_absolute():
+            return "Absolute paths are not allowed. Only files on MATLAB path are accessible."
+        if ".." in path.parts:
+            return "Paths with .. are not allowed. Only files on MATLAB path are accessible."
+        if "*" in path_str or "?" in path_str:
+            return "Paths with * or ? are not allowed."
+
+def check_code(code: str, blacklist: set[str]):
+    """Checks a given code for forbidden commands or paths and raises error if any found."""
+    issues = check_for_commands(code, blacklist) or check_for_paths(code)
+    if issues:
+        raise ToolError(issues)
+    
+def check_path(file: str):
+    """Checks a given file path for absolute or parent paths and raises error if found."""
+    f = Path(file)
+    if f.is_absolute() or ".." in f.parts:
+        raise ToolError("Access to absolute or parent paths is forbidden. Only files on MATLAB path are usable.")

matlab_simulink_mcp/server.py

@@ -0,0 +1,54 @@
+import inspect, time
+from fastmcp import FastMCP
+from contextlib import asynccontextmanager
+
+from matlab_simulink_mcp.state import EngineState, logger, log_console
+from matlab_simulink_mcp import functions
+
+console = False
+
+# Create lifespan function
+@asynccontextmanager
+async def lifespan(server): # do not remove server argument as it will break stuff
+    log_console.open()
+    time.sleep(1)
+
+    state = EngineState()
+    state.initialize()
+
+    if not console:
+        time.sleep(1)
+        log_console.close()
+
+    yield state
+    
+
+# Compile tools
+def collect_tools():
+    tools = []
+    for name, fn in inspect.getmembers(functions, inspect.isfunction):
+        if fn.__module__ == functions.__name__ and not name.startswith("_"):
+            tools.append(fn)
+    return tools
+
+# Define server
+mcp = FastMCP(
+    name="MATLAB_Simulink_MCP", 
+    lifespan=lifespan, 
+    tools=collect_tools()
+    )
+
+# Run server
+def run(console: bool=False):
+    try:
+        console = console
+        mcp.run(transport="stdio")
+    except Exception as e:
+        if hasattr(e, "exceptions"): 
+            for sub in e.exceptions:
+                logger.error(f"{sub}")
+        else:
+            logger.error(f"{e}")
+        #sys.exit(1)
+
+