docs: improve docstrings across all modules + update README

Source code documentation:
- pool/engine.py, pool/manager.py: engine lifecycle, pool scaling
- jobs/executor.py, models.py, tracker.py: job state machine, pruning
- monitoring/collector.py, store.py, health.py, routes.py, dashboard.py
- output/plotly_style_mapper.py: style mapping tables
- tools/custom.py, monitoring.py: custom tool framework
- config.py: configuration loading and validation

README updates:
- Added Windows one-click installer section (install.bat)
- Updated MATLAB version requirement to R2022b+
- Added install.bat instructions for Windows 10/11

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: HanSur94

README.md

@@ -55,7 +55,8 @@ A Python MCP server that connects **any AI agent** (Claude, Cursor, Copilot, cus
 | Multi-user (SSE) | Session isolation with per-user workspaces |
 | Custom tools | Expose your `.m` functions as MCP tools via YAML |
 | Progress reporting | Long jobs report percentage back to the agent |
-| Cross-platform | Windows + macOS, MATLAB 2020b+ |
+| Cross-platform | Windows + macOS, MATLAB R2022b+ |
+| One-click Windows install | Offline `install.bat` — no admin rights needed |
 
 ## MATLAB Plot Conversion to Interactive Plotly
 
@@ -92,7 +93,7 @@ Line styles, colors, markers, legends, and axis labels are all preserved in the
 ### Prerequisites
 
 - **Python 3.10+**
-- **MATLAB 2020b+** with the [MATLAB Engine API for Python](https://www.mathworks.com/help/matlab/matlab-engine-for-python.html) installed
+- **MATLAB R2022b+** with the [MATLAB Engine API for Python](https://www.mathworks.com/help/matlab/matlab-engine-for-python.html) installed
 
 ```bash
 # Install MATLAB Engine API (from your MATLAB installation)
@@ -103,6 +104,18 @@ pip install .
 
 ### Install the server
 
+**Windows (one-click, no admin needed):**
+
+```cmd
+git clone https://github.com/HanSur94/matlab-mcp-server-python.git
+cd matlab-mcp-server-python
+install.bat
+```
+
+The installer auto-detects MATLAB, creates a virtual environment, and installs everything from bundled wheels — fully offline, no internet required. Works on Windows 10/11 with Python 3.10, 3.11, or 3.12.
+
+**macOS / Linux:**
+
 ```bash
 # Option 1: Install from PyPI
 pip install matlab-mcp-python
@@ -658,7 +671,7 @@ AI Agent (Claude, Cursor, etc.)
 └──────────┬──────────────────┘  └─────────┬──────────────┘
            │                               │
 ┌──────────▼──────────────────┐  ┌─────────▼──────────────┐
-│   MATLAB Engines (2020b+)    │  │  Dashboard (Starlette)  │
+│   MATLAB Engines (R2022b+)    │  │  Dashboard (Starlette)  │
 │   Engine 1 │ Engine 2 │ ... │  │  /health  /metrics      │
 │   Workspace isolation        │  │  /dashboard (Plotly.js) │
 └──────────────────────────────┘  └─────────────────────────┘

src/matlab_mcp/config.py

@@ -19,6 +19,8 @@
 
 
 class ServerConfig(BaseModel):
+    """General server settings (name, transport, host/port, logging, drain)."""
+
     name: str = "matlab-mcp-server"
     transport: Literal["stdio", "sse"] = "stdio"
     host: str = "0.0.0.0"
@@ -30,6 +32,8 @@ class ServerConfig(BaseModel):
 
 
 class PoolConfig(BaseModel):
+    """MATLAB engine pool sizing, timeouts, and auto-scaling thresholds."""
+
     min_engines: int = 2
     max_engines: int = 10
     scale_down_idle_timeout: int = 900
@@ -41,6 +45,8 @@ class PoolConfig(BaseModel):
 
 
 class ExecutionConfig(BaseModel):
+    """Code execution timeouts, workspace isolation, and temp directory."""
+
     sync_timeout: int = 30
     max_execution_time: int = 86400
     workspace_isolation: bool = True
@@ -50,20 +56,28 @@ class ExecutionConfig(BaseModel):
 
 
 class WorkspaceConfig(BaseModel):
+    """MATLAB workspace setup: default paths and startup commands."""
+
     default_paths: List[str] = Field(default_factory=list)
     startup_commands: List[str] = Field(default_factory=lambda: ["format long"])
 
 
 class ToolboxesConfig(BaseModel):
+    """Toolbox visibility: whitelist, blacklist, or expose all."""
+
     mode: Literal["whitelist", "blacklist", "all"] = "whitelist"
     list: List[str] = Field(default_factory=list)
 
 
 class CustomToolsConfig(BaseModel):
+    """Path to the YAML file defining user-provided custom MCP tools."""
+
     config_file: str = "./custom_tools.yaml"
 
 
 class SecurityConfig(BaseModel):
+    """Security controls: blocked MATLAB functions, upload limits, proxy auth."""
+
     blocked_functions_enabled: bool = True
     blocked_functions: List[str] = Field(
         default_factory=lambda: [
@@ -77,12 +91,16 @@ class SecurityConfig(BaseModel):
 
 
 class CodeCheckerConfig(BaseModel):
+    """Code linting (checkcode/mlint) toggle and severity filter."""
+
     enabled: bool = True
     auto_check_before_execute: bool = False
     severity_levels: List[str] = Field(default_factory=lambda: ["error", "warning"])
 
 
 class OutputConfig(BaseModel):
+    """Output formatting: Plotly conversion, image format, thumbnails, truncation."""
+
     plotly_conversion: bool = True
     static_image_format: Literal["png", "jpg", "svg"] = "png"
     static_image_dpi: int = 150
@@ -93,12 +111,16 @@ class OutputConfig(BaseModel):
 
 
 class SessionsConfig(BaseModel):
+    """Session limits, idle timeout, and finished-job retention."""
+
     max_sessions: int = 50
     session_timeout: int = 3600
     job_retention_seconds: int = 86400
 
 
 class MonitoringConfig(BaseModel):
+    """Monitoring subsystem: sampling interval, retention, DB path, dashboard."""
+
     enabled: bool = True
     sample_interval: int = 10
     retention_days: int = 7
@@ -108,6 +130,12 @@ class MonitoringConfig(BaseModel):
 
 
 class AppConfig(BaseModel):
+    """Top-level application configuration aggregating all sub-configs.
+
+    Relative filesystem paths are resolved to absolute paths via
+    :meth:`resolve_paths` after loading.
+    """
+
     server: ServerConfig = Field(default_factory=ServerConfig)
     pool: PoolConfig = Field(default_factory=PoolConfig)
     execution: ExecutionConfig = Field(default_factory=ExecutionConfig)
@@ -125,6 +153,12 @@ class AppConfig(BaseModel):
 
     @model_validator(mode="after")
     def validate_pool(self) -> "AppConfig":
+        """Validate pool constraints after model construction.
+
+        Raises ``ValueError`` if ``min_engines > max_engines`` and emits a
+        warning on macOS when ``max_engines > 4`` due to known stability
+        limitations.
+        """
         if self.pool.min_engines > self.pool.max_engines:
             raise ValueError(
                 f"pool.min_engines ({self.pool.min_engines}) must not exceed "
@@ -191,7 +225,10 @@ def _apply_env_overrides(data: dict) -> dict:
 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.
+    If *path* is ``None`` or the file does not exist, default values are
+    used.  After parsing, ``MATLAB_MCP_*`` environment variables are
+    applied (see :func:`_apply_env_overrides`) and relative paths are
+    resolved against the config file's parent directory.
     """
     data: dict = {}
     config_dir = Path.cwd()

src/matlab_mcp/jobs/executor.py

@@ -168,7 +168,12 @@ def _inject_job_context(
         job: Job,
         temp_dir: Optional[str],
     ) -> None:
-        """Inject job metadata into the MATLAB workspace."""
+        """Inject job metadata into the MATLAB workspace.
+
+        Sets ``__mcp_job_id__`` and optionally ``__mcp_temp_dir__`` as
+        workspace variables so that MATLAB scripts can reference them.
+        Failures are silently logged at DEBUG level.
+        """
         try:
             engine._engine.workspace["__mcp_job_id__"] = job.job_id
         except Exception:
@@ -187,7 +192,13 @@ async def _wait_for_completion(
         future: Any,
         temp_dir: Optional[str],
     ) -> None:
-        """Background task that waits for an async job to complete."""
+        """Background task that waits for an async job to complete.
+
+        Blocks (in a thread executor) until the MATLAB future resolves
+        or ``max_execution_time`` is exceeded.  On completion the job is
+        marked completed or failed, and the engine is released back to
+        the pool regardless of outcome.
+        """
         max_time = self._config.execution.max_execution_time
         loop = asyncio.get_running_loop()
         try:
@@ -329,7 +340,11 @@ def _build_result(
 
     @staticmethod
     def _safe_serialize(value: Any) -> Any:
-        """Convert a MATLAB workspace value to a JSON-serializable Python type."""
+        """Convert a MATLAB workspace value to a JSON-serializable Python type.
+
+        Handles primitives, nested lists/dicts, numpy arrays/scalars,
+        and MATLAB array types.  Falls back to ``repr()`` for unknown types.
+        """
         if value is None or isinstance(value, (bool, int, float, str)):
             return value
         if isinstance(value, (list, tuple)):

src/matlab_mcp/jobs/models.py

@@ -13,6 +13,11 @@
 
 
 class JobStatus(Enum):
+    """Lifecycle status of a MATLAB execution job.
+
+    Terminal statuses: COMPLETED, FAILED, CANCELLED.
+    """
+
     PENDING = "pending"
     RUNNING = "running"
     COMPLETED = "completed"
@@ -30,6 +35,27 @@ class Job:
         ID of the session that owns this job.
     code:
         MATLAB code to execute.
+
+    Attributes
+    ----------
+    job_id:
+        Auto-generated unique identifier (``j-<uuid>``).
+    status:
+        Current lifecycle status; starts as PENDING.
+    engine_id:
+        ID of the engine executing this job (set when RUNNING).
+    result:
+        Structured result dict populated on completion.
+    error:
+        Error details dict populated on failure.
+    created_at:
+        Epoch timestamp when the job was created.
+    started_at:
+        Epoch timestamp when execution began.
+    completed_at:
+        Epoch timestamp when the job reached a terminal state.
+    future:
+        Handle to the background MATLAB future, if applicable.
     """
 
     session_id: str

src/matlab_mcp/jobs/tracker.py

@@ -15,7 +15,11 @@
 
 
 class JobTracker:
-    """Tracks all jobs (active and historical) keyed by job_id.
+    """Thread-safe registry that tracks all jobs (active and historical) by job_id.
+
+    Jobs remain in the tracker after reaching a terminal state so that
+    clients can poll for results.  Call :meth:`prune` periodically to
+    evict stale terminal jobs.
 
     Parameters
     ----------

src/matlab_mcp/monitoring/collector.py

@@ -47,6 +47,12 @@ class MetricsCollector:
     """Collects, aggregates, and persists metrics for the MATLAB MCP Server."""
 
     def __init__(self, config: Any) -> None:
+        """Initialize the metrics collector.
+
+        Args:
+            config: Application configuration; uses ``config.monitoring``
+                for sample interval and retention settings.
+        """
         self._config = config
         self.start_time: float = time.time()
 

src/matlab_mcp/monitoring/dashboard.py

@@ -20,28 +20,52 @@
 
 
 def create_monitoring_app(state: Any) -> Starlette:
-    """Create a Starlette app for monitoring endpoints + dashboard."""
+    """Create a Starlette sub-application for monitoring endpoints and the dashboard.
+
+    Registers the following routes:
+
+    * ``/health`` -- JSON health status (200 or 503).
+    * ``/metrics`` -- Live metrics snapshot.
+    * ``/dashboard`` -- Static HTML dashboard page.
+    * ``/dashboard/api/current`` -- Current metrics JSON for the dashboard.
+    * ``/dashboard/api/history`` -- Historical time-series data.
+    * ``/dashboard/api/events`` -- Recent event log.
+    * ``/dashboard/static/`` -- Static file mount (CSS, JS, images).
+
+    Args:
+        state: A :class:`~matlab_mcp.server.MatlabMCPServer` instance
+            providing access to the collector and metrics store.
+    """
 
     # Cache index.html at startup to avoid blocking the event loop
     index_path = STATIC_DIR / "index.html"
     _cached_html = index_path.read_text() if index_path.exists() else None
 
     async def health_handler(request: Request) -> JSONResponse:
+        """Handle GET /health."""
         response = build_health_response(state)
         return JSONResponse(response, status_code=get_health_status_code(response))
 
     async def metrics_handler(request: Request) -> JSONResponse:
+        """Handle GET /metrics."""
         return JSONResponse(build_metrics_response(state))
 
     async def dashboard_handler(request: Request) -> HTMLResponse:
+        """Handle GET /dashboard -- serve the cached HTML page."""
         if _cached_html is not None:
             return HTMLResponse(_cached_html)
         return HTMLResponse("<h1>Dashboard not found</h1>", status_code=404)
 
     async def api_current(request: Request) -> JSONResponse:
+        """Handle GET /dashboard/api/current -- live metrics snapshot."""
         return JSONResponse(build_metrics_response(state))
 
     async def api_history(request: Request) -> JSONResponse:
+        """Handle GET /dashboard/api/history -- time-series history.
+
+        Query params: ``metric`` (default ``pool.utilization_pct``),
+        ``hours`` (default ``1``).
+        """
         metric = request.query_params.get("metric", "pool.utilization_pct")
         try:
             hours = float(request.query_params.get("hours", "1"))
@@ -54,6 +78,11 @@ async def api_history(request: Request) -> JSONResponse:
         return JSONResponse({"data": data})
 
     async def api_events(request: Request) -> JSONResponse:
+        """Handle GET /dashboard/api/events -- recent event log.
+
+        Query params: ``limit`` (default ``100``), ``type`` (optional
+        event type filter).
+        """
         try:
             limit = int(request.query_params.get("limit", "100"))
         except (ValueError, TypeError):

src/matlab_mcp/monitoring/health.py

@@ -4,6 +4,21 @@
 from typing import Any
 
 def evaluate_health(collector: Any) -> dict[str, Any]:
+    """Evaluate the overall health of the MATLAB MCP Server.
+
+    Inspects engine pool utilization, error rates, and health-check
+    counters to classify the server as ``"healthy"``, ``"degraded"``,
+    or ``"unhealthy"``.
+
+    Args:
+        collector: A :class:`~matlab_mcp.monitoring.collector.MetricsCollector`
+            instance with references to the engine pool, job tracker,
+            and session manager.
+
+    Returns:
+        A dict with keys ``status``, ``uptime_seconds``, ``issues``,
+        ``engines``, ``active_jobs``, and ``active_sessions``.
+    """
     issues: list[str] = []
     pool_status = collector.pool.get_status() if collector.pool else {}
     total = pool_status.get("total", 0)