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

matlab_simulink_mcp/state.py

@@ -0,0 +1,106 @@
+import os, types, json, sys
+
+from pathlib import Path
+from importlib import resources
+from dataclasses import dataclass
+from dotenv import load_dotenv
+
+import matlab_simulink_mcp
+from matlab_simulink_mcp import data
+from matlab_simulink_mcp.log_utils import create_log_file, create_logger, create_console 
+
+
+def get_full_path(pkg: types.ModuleType, path: str | Path) -> Path:
+    if path is None:
+        return None
+    path = Path(path)
+    if path.is_absolute():
+        return path
+    return (Path(pkg.__file__).resolve().parent / path).resolve()
+
+load_dotenv()
+log_dir = get_full_path(matlab_simulink_mcp, os.getenv("LOG_DIR"))
+
+log_file = create_log_file(filename=matlab_simulink_mcp.__name__, dir=log_dir)
+log_console = create_console(log_file=log_file)
+logger = create_logger(name=matlab_simulink_mcp.__name__, log_file=log_file)
+
+
+@dataclass
+class EngineState:
+    installed: int = 0
+    session: str | None = None
+    eng = None # Don't put typehint here since engine may not be installed
+    helpers: Path | None = None
+    simlib: dict | None = None
+    blacklist: set[str] | None = None
+
+    def initialize(self):
+        self.ensure_engine()
+    
+        if self.installed == 1:
+            self.connect_engine()
+            self.load_data()
+
+            if self.eng is None:
+                logger.warning("Starting server without an engine. " \
+                "Run matlab.engine.shareEngine in MATLAB to share a session and access_matlab tool to reconnect.")
+            else:
+                logger.info(f"Connected to MATLAB session: {self.session}.")
+                logger.info(f"Logging to: {log_file}")
+
+    def load_data(self):
+        self.simlib = json.loads((resources.files(data) / "simlib_db.json").read_text())
+        self.blacklist = {
+            line.strip().lower()
+            for line in (resources.files(data) / "blacklist.txt").read_text().splitlines()
+            if line.strip() and not line.strip().startswith("#")
+            } 
+    
+    def connect_engine(self):
+        if self.installed == 1:
+            import matlab.engine
+            sessions = matlab.engine.find_matlab() or []
+            if sessions:
+                self.session = sessions[0]
+                self.eng = matlab.engine.connect_matlab(self.session)
+                self.helpers = self.add_helpers()
+
+    def add_helpers(self):
+        if getattr(sys, "frozen", False):
+            pth = Path(sys._MEIPASS) / "matlab_simulink_mcp" / "data/helpers"
+        else:
+            pth = get_full_path(matlab_simulink_mcp, "data/helpers")
+        self.eng.addpath(str(pth), nargout=0)
+        return Path(pth)
+    
+    def ensure_engine(self):
+        try:
+            import matlab.engine 
+        except ImportError:
+            logger.info("MATLAB Engine for Python package not found. Starting package installer...")
+            import matlab_simulink_mcp.installer.launcher as launcher
+            self.installed = launcher.run()
+            if self.installed == 1:
+                try:
+                    import matlab.engine
+                    logger.info("MATLAB engine package successfully installed.")
+                except ImportError:
+                    raise ImportError("MATLAB Engine package not available even after attempted install.")
+            elif self.installed != -1:
+                raise RuntimeError("Failed to install MATLAB engine package. " \
+                "This server requires MATLAB engine package to work.. " \
+                "You can try installing it manually from PyPi or your MATLAB installation.")
+            
+
+    
+    
+
+
+
+    
+
+
+
+
+

matlab_simulink_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: matlab-simulink-mcp
+Version: 0.1.0
+Summary: An MCP server for allowing LLMs to interact with MATLAB and Simulink
+Author: Rohail
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=2.12.2
+Requires-Dist: platformdirs>=4.4.0
+
+# MATLAB Simulink MCP Server
+
+[![PyPI version](https://img.shields.io/pypi/v/matlab-simulink-mcp.svg)](https://pypi.org/project/matlab-simulink-mcp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/matlab-simulink-mcp.svg)](https://pypi.org/project/matlab-simulink-mcp/)
+
+This [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) server allows MCP clients (such as Claude Desktop or other LLM-based agents) to interact with **MATLAB** and **Simulink** in real time. It runs locally and is built on top of the [FastMCP 2.0](https://gofastmcp.com/getting-started/welcome) library.
+
+## Features
+
+- Read, write, and run MATLAB code and scripts
+- Parse and interact with Simulink files
+- Access MATLAB workspace variables and outputs (including visualizations)
+- Basic safety layer to prevent execution of unsafe commands (configurable)
+- Non-blocking execution (async MATLAB engine calls)
+- Automatic installation of MATLAB Engine package if unavailable
+
+## Requirements
+
+- **MATLAB** R2022b or later  
+- **Python** 3.10–3.12 (check MATLAB's [supported versions](https://www.mathworks.com/support/requirements/python-compatibility.html))
+
+## Installation
+
+### Option 1 — Download Binary (MATLAB R2025a only)
+
+If you don’t want to interact with Python at all, you can download a prebuilt **exe/app** from the [Releases](../../releases) page and run it directly. In that case you can skip the steps below.
+
+### Option 2 — From Source
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/rohailamalik/matlab-simulink-mcp
+   cd matlab-simulink-mcp
+
+2. Create a Python virtual environment (recommended: [uv](https://pypi.org/project/uv/0.1.32/)):
+
+    ```bash
+    uv venv --python 3.12           # match Python to your MATLAB-supported version
+    source .venv/Scripts/activate   # on macOS/Linux: source .venv/bin/activate
+    uv sync
+    ```
+
+    Without uv, first download a Python version manually:
+
+    ```bash
+    python3.12 -m venv .venv
+    source .venv/bin/activate
+    pip install -r requirements.txt
+    pip install .
+    ```
+
+3. Alternatively, skip step 1, create virtual environment and install directly via PyPI:
+
+    ```bash
+    uv pip install matlab-simulink-mcp
+    # or
+    pip install matlab-simulink-mcp
+    ```
+
+4. On first run, if the MATLAB Engine is not installed, the server will open a console window and guide you through installation.
+
+    - This requires admin permission and the server will request for it.
+    - If you prefer to install manually, install a [matching PyPi version](https://pypi.org/project/matlabengine/#history) or from your [MATLAB installation](https://www.mathworks.com/help/matlab/matlab_external/install-the-matlab-engine-for-python.html).
+
+## Configuration (Claude Desktop)
+
+1. Install [Claude Desktop](https://claude.ai/download).
+
+2. Open Settings → Developer → Edit Config.
+
+3. In the `claude_desktop_config.json`, add or update:
+
+    ```json
+    {
+    "mcpServers": {
+        "MATLAB_Simulink_MCP": {
+            "command": "C:/Data/Research/Doctoral/src/matlab-simulink-mcp/.venv/Scripts/python.exe",
+            "args": ["-m", "matlab_simulink_mcp"]
+            }
+        }
+    }
+    ```
+
+    On macOS/Linux, use `absolute-path-to/.venv/bin/python` in `command`.
+
+    If using the standalone exe/app, just put absolute path to it in `command` and omit args.
+
+    **Note**: Only use `/` or `\\` in the paths, not `\`.
+
+4. Save and restart Claude Desktop. (Ensure it is fully closed in Task Manager/Activity Monitor.)
+
+5. On first launch, the server may open multiple consoles to install MATLAB Engine. Interact with one, complete installation, then restart Claude if needed.
+
+6. Check running status in Settings → Developer, or click the equalizer button in the chat box.
+
+7. The server logs outputs and errors to both Claude's and its own log file. To keep a log file tracking console open, add `--console` in Claude config args.
+
+    - Claude MCP logs (Windows): `%APPDATA%\Claude\logs\mcp-server-MatlabMCP.log`
+    - Claude MCP logs (macOS): `~/Library/Logs/Claude/mcp-server-MatlabMCP.log`
+    - Server logs: written to your user log directory (or configured via `.env`).
+
+## Debugging
+
+FastMCP 2.0 includes an MCP Inspector for manual testing without an LLM client. This launches a UI to send dummy requests directly to the server.
+
+```bash
+cd scripts
+fastmcp dev debugger.py
+```
+
+## Repository Structure
+
+```txt
+
+matlab-simulink-mcp/
+├─ scripts
+│  ├─ debugger.py           # Entry point for MCP inspector
+├─ src/matlab_simulink_mcp/
+│  ├─ data/                 # Data files and resources
+│  ├─ installer/            # MATLAB Engine installer
+│  │  ├─ installer.py
+│  │  ├─ launcher.py
+│  │  └─ win_elevate.py
+│  ├─ functions.py          # Baseline MCP tool functions
+│  ├─ log_utils.py          # Logging utilities
+│  ├─ security.py           # Safety layer for code execution
+│  ├─ server.py             # Main server script
+│  ├─ state.py              # Server lifespan objects (logger, engine)
+│  ├─ __main__.py           # Main entry point
+├─ .env                     # Optional config (e.g. LOG_DIR)
+├─ pyproject.toml           # Project metadata and dependencies
+├─ requirements.txt         # Package dependencies for pip
+├─ uv.lock                  # Package dependencies for uv
+└─ README.md                # This file
+
+```
+
+## FAQ
+
+Q: Which Python version should I install?
+
+A: Match it to the highest Python version supported by your MATLAB release (see MathWorks docs).
+
+Q: The console disappears too quickly!
+
+A: Add `--console` in your Claude config args to keep the server console open.
+
+Q: Multiple installer consoles opened on first run.
+
+A: This is expected if Claude sends multiple startup requests. Complete one installation, then restart Claude Desktop.
+
+## Contributing
+
+Pull requests are welcome! Feel free to submit one or open an issue.

matlab_simulink_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+matlab_simulink_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+matlab_simulink_mcp/__main__.py,sha256=KpLGWl7NgBhLBVMIkOwETQoAsh-NXwO8OOVLjsBNBpE,332
+matlab_simulink_mcp/functions.py,sha256=SDZUnISiG8GVQ6uDLdzIasMiZPXA49wkuHFGlMwXlBo,6348
+matlab_simulink_mcp/log_utils.py,sha256=7fJWkTZdSzadPHmKNLzy6gmGWnOC8IGFYVYocuaZIZE,3450
+matlab_simulink_mcp/security.py,sha256=bqEHujIW3-URUrOPVvBOUmhPMdkCgKLwTUr-7SPOTIQ,2136
+matlab_simulink_mcp/server.py,sha256=nJhAxSa8MMxsXfGu5ygxm6fqunyyZk7rjhFOBkOOCrI,1287
+matlab_simulink_mcp/state.py,sha256=bT8Ud2E3W2eWxcqgSuRcuvj43O9BYERWciBYh82ey24,3696
+matlab_simulink_mcp/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+matlab_simulink_mcp/data/blacklist.txt,sha256=YXWTjcjFM-uTb3gD_pblEpPPGoIKjSHMFgZJdWfmuMw,656
+matlab_simulink_mcp/data/simlib_db.json,sha256=bni7DcGG6SofIcCMX5KSlaHOHOYsELT833reNhz4S5Q,538658
+matlab_simulink_mcp/installer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+matlab_simulink_mcp/installer/installer.py,sha256=0SHMTaqZjSvb9zKx4in67bS5xT4JcnsO2U2vYvmb968,5949
+matlab_simulink_mcp/installer/launcher.py,sha256=aGuxkXnLcb1OZ4P6rHvXFi8KZsDUZVQlo0rNvjdmFqA,1438
+matlab_simulink_mcp/installer/win_elevate.py,sha256=LyHHUh4vWmIlIXxrM9tOhQUvVeMxcVdXMzkC3vbGm3A,514
+matlab_simulink_mcp-0.1.0.dist-info/METADATA,sha256=gYmQ8SGHTA3mk-sg9loIb8DwK8kCg2yDojsMUtk8h6I,6604
+matlab_simulink_mcp-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+matlab_simulink_mcp-0.1.0.dist-info/entry_points.txt,sha256=0ba8PFlQcaWyAqKXRIVDfDvrifeD5LY60lV7i6ak9oE,74
+matlab_simulink_mcp-0.1.0.dist-info/top_level.txt,sha256=90gv-RNCWWS7E-JMiqwUf2TjB_B8Zb2B-crAeXaABqU,20
+matlab_simulink_mcp-0.1.0.dist-info/RECORD,,

matlab_simulink_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

matlab_simulink_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+matlab_simulink_mcp = matlab_simulink_mcp.__main__:main

matlab_simulink_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+matlab_simulink_mcp