matlab-mcp-python 1.0.0__py3-none-any.whl

matlab_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""MATLAB MCP Server — Expose MATLAB capabilities to AI agents via MCP."""
+__version__ = "0.1.0"

matlab_mcp/config.py

@@ -0,0 +1,212 @@
+"""Configuration system for MATLAB MCP Server.
+
+Loads YAML config, applies environment variable overrides (MATLAB_MCP_* prefix),
+and validates settings with Pydantic models.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import warnings
+from pathlib import Path
+from typing import List, Literal, Optional
+
+import yaml
+from pydantic import BaseModel, Field, model_validator
+
+logger = logging.getLogger(__name__)
+
+
+class ServerConfig(BaseModel):
+    name: str = "matlab-mcp-server"
+    transport: Literal["stdio", "sse"] = "stdio"
+    host: str = "0.0.0.0"
+    port: int = 8765
+    log_level: Literal["debug", "info", "warning", "error"] = "info"
+    log_file: str = "./logs/server.log"
+    result_dir: str = "./results"
+    drain_timeout_seconds: int = 300
+
+
+class PoolConfig(BaseModel):
+    min_engines: int = 2
+    max_engines: int = 10
+    scale_down_idle_timeout: int = 900
+    engine_start_timeout: int = 120
+    health_check_interval: int = 60
+    proactive_warmup_threshold: float = 0.8
+    queue_max_size: int = 50
+    matlab_root: Optional[str] = None
+
+
+class ExecutionConfig(BaseModel):
+    sync_timeout: int = 30
+    max_execution_time: int = 86400
+    workspace_isolation: bool = True
+    engine_affinity: bool = False
+    temp_dir: str = "./temp"
+    temp_cleanup_on_disconnect: bool = True
+
+
+class WorkspaceConfig(BaseModel):
+    default_paths: List[str] = Field(default_factory=list)
+    startup_commands: List[str] = Field(default_factory=lambda: ["format long"])
+
+
+class ToolboxesConfig(BaseModel):
+    mode: Literal["whitelist", "blacklist", "all"] = "whitelist"
+    list: List[str] = Field(default_factory=list)
+
+
+class CustomToolsConfig(BaseModel):
+    config_file: str = "./custom_tools.yaml"
+
+
+class SecurityConfig(BaseModel):
+    blocked_functions_enabled: bool = True
+    blocked_functions: List[str] = Field(
+        default_factory=lambda: [
+            "system", "unix", "dos", "!",
+            "eval", "feval", "evalc", "evalin", "assignin",
+            "perl", "python",
+        ]
+    )
+    max_upload_size_mb: int = 100
+    require_proxy_auth: bool = False
+
+
+class CodeCheckerConfig(BaseModel):
+    enabled: bool = True
+    auto_check_before_execute: bool = False
+    severity_levels: List[str] = Field(default_factory=lambda: ["error", "warning"])
+
+
+class OutputConfig(BaseModel):
+    plotly_conversion: bool = True
+    static_image_format: Literal["png", "jpg", "svg"] = "png"
+    static_image_dpi: int = 150
+    thumbnail_enabled: bool = True
+    thumbnail_max_width: int = 400
+    large_result_threshold: int = 10000
+    max_inline_text_length: int = 50000
+
+
+class SessionsConfig(BaseModel):
+    max_sessions: int = 50
+    session_timeout: int = 3600
+    job_retention_seconds: int = 86400
+
+
+class MonitoringConfig(BaseModel):
+    enabled: bool = True
+    sample_interval: int = 10
+    retention_days: int = 7
+    db_path: str = "./monitoring/metrics.db"
+    dashboard_enabled: bool = True
+    http_port: int = 8766
+
+
+class AppConfig(BaseModel):
+    server: ServerConfig = Field(default_factory=ServerConfig)
+    pool: PoolConfig = Field(default_factory=PoolConfig)
+    execution: ExecutionConfig = Field(default_factory=ExecutionConfig)
+    workspace: WorkspaceConfig = Field(default_factory=WorkspaceConfig)
+    toolboxes: ToolboxesConfig = Field(default_factory=ToolboxesConfig)
+    custom_tools: CustomToolsConfig = Field(default_factory=CustomToolsConfig)
+    security: SecurityConfig = Field(default_factory=SecurityConfig)
+    code_checker: CodeCheckerConfig = Field(default_factory=CodeCheckerConfig)
+    output: OutputConfig = Field(default_factory=OutputConfig)
+    sessions: SessionsConfig = Field(default_factory=SessionsConfig)
+    monitoring: MonitoringConfig = Field(default_factory=MonitoringConfig)
+
+    # Internal: stored after resolution so validators can use it
+    _config_dir: Optional[Path] = None
+
+    @model_validator(mode="after")
+    def validate_pool(self) -> "AppConfig":
+        if self.pool.min_engines > self.pool.max_engines:
+            raise ValueError(
+                f"pool.min_engines ({self.pool.min_engines}) must not exceed "
+                f"pool.max_engines ({self.pool.max_engines})"
+            )
+        if platform.system() == "Darwin" and self.pool.max_engines > 4:
+            warnings.warn(
+                f"pool.max_engines is {self.pool.max_engines} on macOS. "
+                "Running more than 4 matlab.engine instances in a single Python process "
+                "on macOS has known stability issues. Consider setting max_engines <= 4.",
+                stacklevel=2,
+            )
+        return self
+
+    def resolve_paths(self, base_dir: Path) -> None:
+        """Resolve all relative paths to absolute paths relative to base_dir."""
+
+        def _resolve(p: str) -> str:
+            path = Path(p)
+            if not path.is_absolute():
+                return str((base_dir / path).resolve())
+            return p
+
+        self.server.result_dir = _resolve(self.server.result_dir)
+        self.server.log_file = _resolve(self.server.log_file)
+        self.execution.temp_dir = _resolve(self.execution.temp_dir)
+        self.custom_tools.config_file = _resolve(self.custom_tools.config_file)
+        self.monitoring.db_path = _resolve(self.monitoring.db_path)
+
+
+def _apply_env_overrides(data: dict) -> dict:
+    """Apply MATLAB_MCP_* environment variable overrides.
+
+    Convention: MATLAB_MCP_SECTION_KEY maps to data[section][key].
+    E.g. MATLAB_MCP_POOL_MAX_ENGINES=20 → data["pool"]["max_engines"] = 20.
+    """
+    prefix = "MATLAB_MCP_"
+    for env_key, env_val in os.environ.items():
+        if not env_key.startswith(prefix):
+            continue
+        remainder = env_key[len(prefix):]  # e.g. "POOL_MAX_ENGINES"
+        parts = remainder.lower().split("_", 1)
+        if len(parts) != 2:
+            continue
+        section, key = parts  # e.g. ("pool", "max_engines")
+        if section not in data:
+            data[section] = {}
+
+        # Attempt type coercion: int → float → bool → str
+        coerced: object = env_val
+        try:
+            coerced = int(env_val)
+        except ValueError:
+            try:
+                coerced = float(env_val)
+            except ValueError:
+                if env_val.lower() in ("true", "false"):
+                    coerced = env_val.lower() == "true"
+
+        data[section][key] = coerced
+    return data
+
+
+def load_config(path: Optional[Path] = None) -> AppConfig:
+    """Load application config from a YAML file with env var overrides.
+
+    If *path* is None or the file does not exist, default values are used.
+    """
+    data: dict = {}
+    config_dir = Path.cwd()
+
+    if path is not None:
+        path = Path(path)
+        if path.exists():
+            with open(path, "r", encoding="utf-8") as fh:
+                loaded = yaml.safe_load(fh) or {}
+            data = loaded
+            config_dir = path.parent
+        else:
+            logger.warning("Config file not found: %s — using defaults", path)
+
+    data = _apply_env_overrides(data)
+    config = AppConfig.model_validate(data)
+    config.resolve_paths(config_dir)
+    return config

matlab_mcp/jobs/executor.py

@@ -0,0 +1,366 @@
+"""Job executor for MATLAB MCP Server.
+
+Orchestrates the full lifecycle of a MATLAB code execution request:
+1. Create a job in the tracker
+2. Acquire an engine from the pool
+3. Inject job context into the MATLAB workspace
+4. Execute code (sync or promoted to async)
+5. Build and return a structured result dict
+"""
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import io
+import logging
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+from matlab_mcp.jobs.models import Job
+from matlab_mcp.jobs.tracker import JobTracker
+
+logger = logging.getLogger(__name__)
+
+
+class JobExecutor:
+    """Executes MATLAB code jobs using a pool of engines.
+
+    Parameters
+    ----------
+    pool:
+        An :class:`~matlab_mcp.pool.manager.EnginePoolManager` instance
+        (or any object with async ``acquire()`` / ``release()`` methods).
+    tracker:
+        A :class:`JobTracker` instance for storing job state.
+    config:
+        The full :class:`~matlab_mcp.config.AppConfig` instance.
+    """
+
+    def __init__(self, pool: Any, tracker: JobTracker, config: Any, collector: Any = None) -> None:
+        self._pool = pool
+        self._tracker = tracker
+        self._config = config
+        self._collector = collector
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def execute(
+        self,
+        session_id: str,
+        code: str,
+        temp_dir: Optional[str] = None,
+    ) -> dict:
+        """Execute MATLAB code for a session.
+
+        Hybrid sync/async execution:
+        - Creates a job and acquires an engine.
+        - Injects job context into the MATLAB workspace.
+        - Starts background execution via ``engine.execute(code, background=True)``.
+        - Waits up to ``sync_timeout`` seconds.
+          - If the future completes: returns result inline (status="completed").
+          - If it times out: promotes to async background task (status="pending").
+        - On sync execution error: marks job failed and returns error result.
+
+        Returns a dict with at minimum ``status`` and ``job_id`` keys.
+        """
+        sync_timeout = self._config.execution.sync_timeout
+
+        # 1. Create job
+        job = self._tracker.create_job(session_id, code)
+        logger.info("[job %s] Created for session=%s  code=%s",
+                    job.job_id[:8], session_id[:8], repr(code[:120]))
+
+        # 2. Acquire engine
+        engine = await self._pool.acquire()
+        job.mark_running(engine.engine_id)
+        logger.info("[job %s] Acquired engine %s — executing", job.job_id[:8], engine.engine_id)
+
+        # 3. Inject job context
+        self._inject_job_context(engine, job, temp_dir)
+
+        # 4. Start background execution with stdout/stderr capture
+        job._stdout = io.StringIO()
+        job._stderr = io.StringIO()
+        try:
+            future = engine.execute(code, background=True,
+                                    stdout=job._stdout, stderr=job._stderr)
+            job.future = future
+        except Exception as exc:
+            logger.error("[job %s] Failed to start execution: %s: %s",
+                         job.job_id[:8], type(exc).__name__, exc)
+            job.mark_failed(
+                error_type=type(exc).__name__,
+                message=str(exc),
+            )
+            await self._pool.release(engine)
+            if self._collector:
+                self._collector.record_event("job_failed", {
+                    "job_id": job.job_id,
+                    "code": code[:500],
+                    "error": str(exc)[:500],
+                })
+            return self._error_result(job)
+
+        # 5. Wait for sync_timeout
+        if sync_timeout > 0:
+            try:
+                loop = asyncio.get_running_loop()
+                raw_result = await asyncio.wait_for(
+                    loop.run_in_executor(None, lambda: future.result(timeout=sync_timeout)),
+                    timeout=sync_timeout + 1,
+                )
+                # Completed within timeout
+                result = self._build_result(engine, raw_result, job, temp_dir)
+                job.mark_completed(result)
+                elapsed_ms = (job.completed_at - job.started_at) * 1000 if job.started_at and job.completed_at else 0
+                output_preview = (result.get("text") or "")[:200]
+                logger.info("[job %s] Completed in %.1fms  output=%s",
+                            job.job_id[:8], elapsed_ms, repr(output_preview))
+                await self._pool.release(engine)
+                if self._collector:
+                    self._collector.record_event("job_completed", {
+                        "job_id": job.job_id,
+                        "execution_ms": elapsed_ms,
+                        "code": code[:500],
+                        "output": (result.get("text") or "")[:2000],
+                    })
+                return {"status": "completed", "job_id": job.job_id, **result}
+            except (TimeoutError, concurrent.futures.TimeoutError, asyncio.TimeoutError):
+                # Promote to async
+                logger.info("[job %s] Sync timeout (%ds) — promoting to async background job",
+                            job.job_id[:8], sync_timeout)
+                asyncio.create_task(
+                    self._wait_for_completion(job, engine, future, temp_dir)
+                )
+                return {"status": "pending", "job_id": job.job_id}
+            except Exception as exc:
+                logger.error("[job %s] Execution failed: %s: %s",
+                             job.job_id[:8], type(exc).__name__, exc)
+                job.mark_failed(
+                    error_type=type(exc).__name__,
+                    message=str(exc),
+                )
+                await self._pool.release(engine)
+                if self._collector:
+                    self._collector.record_event("job_failed", {
+                        "job_id": job.job_id,
+                        "code": code[:500],
+                        "error": str(exc)[:500],
+                    })
+                return self._error_result(job)
+        else:
+            # sync_timeout == 0: immediately promote to async
+            asyncio.create_task(
+                self._wait_for_completion(job, engine, future, temp_dir)
+            )
+            return {"status": "pending", "job_id": job.job_id}
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _inject_job_context(
+        self,
+        engine: Any,
+        job: Job,
+        temp_dir: Optional[str],
+    ) -> None:
+        """Inject job metadata into the MATLAB workspace."""
+        try:
+            engine._engine.workspace["__mcp_job_id__"] = job.job_id
+        except Exception:
+            logger.debug("Could not inject __mcp_job_id__ into workspace")
+
+        if temp_dir is not None:
+            try:
+                engine._engine.workspace["__mcp_temp_dir__"] = str(temp_dir)
+            except Exception:
+                logger.debug("Could not inject __mcp_temp_dir__ into workspace")
+
+    async def _wait_for_completion(
+        self,
+        job: Job,
+        engine: Any,
+        future: Any,
+        temp_dir: Optional[str],
+    ) -> None:
+        """Background task that waits for an async job to complete."""
+        max_time = self._config.execution.max_execution_time
+        loop = asyncio.get_running_loop()
+        try:
+            raw_result = await asyncio.wait_for(
+                loop.run_in_executor(None, lambda: future.result(timeout=max_time)),
+                timeout=max_time + 1,
+            )
+            result = self._build_result(engine, raw_result, job, temp_dir)
+            job.mark_completed(result)
+            elapsed_ms = (job.completed_at - job.started_at) * 1000 if job.started_at and job.completed_at else 0
+            logger.info("[job %s] Async job completed in %.1fms", job.job_id[:8], elapsed_ms)
+            if self._collector:
+                self._collector.record_event("job_completed", {
+                    "job_id": job.job_id,
+                    "execution_ms": elapsed_ms,
+                    "code": job.code[:500] if job.code else "",
+                    "output": (result.get("text") or "")[:2000],
+                })
+        except asyncio.CancelledError:
+            logger.warning("[job %s] Async job cancelled", job.job_id[:8])
+            job.mark_cancelled()
+        except Exception as exc:
+            logger.error("[job %s] Async job failed: %s: %s",
+                         job.job_id[:8], type(exc).__name__, exc)
+            job.mark_failed(
+                error_type=type(exc).__name__,
+                message=str(exc),
+            )
+            if self._collector:
+                self._collector.record_event("job_failed", {
+                    "job_id": job.job_id,
+                    "code": job.code[:500] if job.code else "",
+                    "error": str(exc)[:500],
+                })
+        finally:
+            try:
+                await self._pool.release(engine)
+            except Exception:
+                logger.warning("Failed to release engine after async job %s", job.job_id)
+
+    def _build_result(
+        self,
+        engine: Any,
+        raw_result: Any,
+        job: Job,
+        temp_dir: Optional[str],
+    ) -> dict:
+        """Build a structured result dict from the engine's output.
+
+        Collects:
+        - text: captured stdout from the engine
+        - variables: key/value pairs from the workspace (excluding internal vars)
+        - figures: Plotly-converted figures if configured
+        - files: any files written to temp_dir
+        - warnings / errors: empty lists by default (extended by real engine)
+        """
+        # Capture text output from StringIO buffers
+        text = ""
+        try:
+            stdout_buf = getattr(job, "_stdout", None)
+            if stdout_buf is not None:
+                text = stdout_buf.getvalue()
+            stderr_buf = getattr(job, "_stderr", None)
+            if stderr_buf is not None:
+                err_text = stderr_buf.getvalue()
+                if err_text:
+                    text = text + "\n[stderr]\n" + err_text if text else err_text
+        except Exception:
+            pass
+
+        # Capture workspace variables (excluding internal MCP variables)
+        variables: dict = {}
+        try:
+            for k, v in engine._engine.workspace.items():
+                if not k.startswith("__mcp_"):
+                    variables[k] = self._safe_serialize(v)
+        except Exception:
+            pass
+
+        # Figures — extract properties and convert to Plotly
+        figures: list = []
+        if self._config.output.plotly_conversion and temp_dir is not None:
+            try:
+                import glob as glob_mod
+                from matlab_mcp.output.plotly_convert import load_plotly_json
+                from matlab_mcp.output.plotly_style_mapper import convert_figure
+
+                # Run MATLAB-side figure extraction
+                # Note: MATLAB eval() rejects identifiers starting with __
+                escaped_dir = str(temp_dir).replace("\\", "\\\\").replace("'", "''")
+                extract_code = (
+                    f"mcpFigs_ = findobj(0, 'Type', 'figure'); "
+                    f"for mcpIdx_ = 1:length(mcpFigs_), "
+                    f"mcp_extract_props(mcpFigs_(mcpIdx_), "
+                    f"fullfile('{escaped_dir}', sprintf('{job.job_id}_fig%d.json', mcpIdx_))); "
+                    f"close(mcpFigs_(mcpIdx_)); "
+                    f"end; "
+                    f"clear mcpFigs_ mcpIdx_;"
+                )
+                logger.debug("Figure extraction code: %r", extract_code)
+                try:
+                    engine.execute(extract_code, background=False)
+                except Exception as exc:
+                    logger.warning("Figure extraction failed: %s", exc)
+                    logger.debug("Extraction code was: %r", extract_code)
+
+                # Load and convert each figure JSON
+                fig_pattern = os.path.join(temp_dir, f"{job.job_id}_fig*.json")
+                for fig_file in sorted(glob_mod.glob(fig_pattern)):
+                    matlab_data = load_plotly_json(fig_file)
+                    if matlab_data:
+                        plotly_fig = convert_figure(matlab_data)
+                        figures.append(plotly_fig)
+                    try:
+                        os.remove(fig_file)
+                    except OSError:
+                        pass
+            except Exception as exc:
+                logger.warning("Figure conversion pipeline failed: %s", exc)
+
+        # Files in temp_dir
+        files: list = []
+        if temp_dir is not None:
+            try:
+                td = Path(temp_dir)
+                if td.exists():
+                    files = [str(p) for p in td.iterdir() if p.is_file()]
+            except Exception:
+                pass
+
+        return {
+            "text": text,
+            "variables": variables,
+            "figures": figures,
+            "files": files,
+            "warnings": [],
+            "errors": [],
+        }
+
+    @staticmethod
+    def _safe_serialize(value: Any) -> Any:
+        """Convert a MATLAB workspace value to a JSON-serializable Python type."""
+        if value is None or isinstance(value, (bool, int, float, str)):
+            return value
+        if isinstance(value, (list, tuple)):
+            return [JobExecutor._safe_serialize(v) for v in value]
+        if isinstance(value, dict):
+            return {k: JobExecutor._safe_serialize(v) for k, v in value.items()}
+        # numpy arrays
+        try:
+            import numpy as np
+            if isinstance(value, np.ndarray):
+                return value.tolist()
+            if isinstance(value, (np.integer, np.floating)):
+                return value.item()
+        except ImportError:
+            pass
+        # MATLAB arrays / matrices
+        try:
+            if hasattr(value, '_data'):
+                return list(value._data)
+            if hasattr(value, 'tolist'):
+                return value.tolist()
+        except Exception:
+            pass
+        # Fallback: repr
+        return repr(value)
+
+    @staticmethod
+    def _error_result(job: Job) -> dict:
+        """Return a failure result dict from a failed job."""
+        return {
+            "status": "failed",
+            "job_id": job.job_id,
+            "error": job.error,
+        }

matlab_mcp/jobs/models.py

@@ -0,0 +1,95 @@
+"""Job models for MATLAB MCP Server.
+
+Defines the Job data model and JobStatus enum used to track the lifecycle
+of MATLAB code execution requests.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class JobStatus(Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class Job:
+    """Represents a single MATLAB code execution job.
+
+    Parameters
+    ----------
+    session_id:
+        ID of the session that owns this job.
+    code:
+        MATLAB code to execute.
+    """
+
+    session_id: str
+    code: str
+    job_id: str = field(default_factory=lambda: f"j-{uuid.uuid4()}")
+    status: JobStatus = field(default=JobStatus.PENDING)
+    engine_id: Optional[str] = field(default=None)
+    result: Optional[Any] = field(default=None)
+    error: Optional[dict] = field(default=None)
+    created_at: float = field(default_factory=time.time)
+    started_at: Optional[float] = field(default=None)
+    completed_at: Optional[float] = field(default=None)
+    future: Optional[Any] = field(default=None)
+
+    # ------------------------------------------------------------------
+    # State transitions
+    # ------------------------------------------------------------------
+
+    def mark_running(self, engine_id: str) -> None:
+        """Transition job to RUNNING state."""
+        self.status = JobStatus.RUNNING
+        self.engine_id = engine_id
+        self.started_at = time.time()
+
+    def mark_completed(self, result: Any) -> None:
+        """Transition job to COMPLETED state with a result."""
+        self.status = JobStatus.COMPLETED
+        self.result = result
+        self.completed_at = time.time()
+
+    def mark_failed(
+        self,
+        error_type: str,
+        message: str,
+        matlab_id: Optional[str] = None,
+        stack_trace: Optional[str] = None,
+    ) -> None:
+        """Transition job to FAILED state with error details."""
+        self.status = JobStatus.FAILED
+        self.error = {
+            "type": error_type,
+            "message": message,
+            "matlab_id": matlab_id,
+            "stack_trace": stack_trace,
+        }
+        self.completed_at = time.time()
+
+    def mark_cancelled(self) -> None:
+        """Transition job to CANCELLED state."""
+        self.status = JobStatus.CANCELLED
+        self.completed_at = time.time()
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def elapsed_seconds(self) -> Optional[float]:
+        """Elapsed time in seconds since job started, or None if not started."""
+        if self.started_at is None:
+            return None
+        end = self.completed_at if self.completed_at is not None else time.time()
+        return end - self.started_at