paraview-mcp-python 0.1.3__tar.gz → 0.1.4__tar.gz

{paraview_mcp_python-0.1.3 → paraview_mcp_python-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paraview-mcp-python
-Version: 0.1.3
+Version: 0.1.4
 Summary: MCP server for controlling ParaView via AI assistants
 Project-URL: Homepage, https://github.com/djeada/paraview-mcp-server
 Project-URL: Repository, https://github.com/djeada/paraview-mcp-server
@@ -50,18 +50,21 @@ paraview-mcp-server
 
 ## What Parts Are There?
 
-There are three moving pieces:
+There are four moving pieces in the GUI workflow:
 
 | Part | Runs where | Purpose |
 |---|---|---|
 | **MCP client** | Codex CLI, Claude Desktop, or another MCP host | Starts the MCP server and calls tools. |
 | **MCP server** | Normal Python environment | Speaks MCP over stdio and forwards tool calls to ParaView over TCP. |
-| **ParaView GUI bridge** | Already-open ParaView GUI process | Receives TCP JSON commands and executes `paraview.simple` operations in that live GUI session. |
+| **ParaView bridge** | `pvpython` process | Receives TCP JSON commands and executes `paraview.simple` operations. |
+| **ParaView runtime** | `pvserver` plus a ParaView GUI client | Owns the shared ParaView session that the GUI and bridge both use. |
 
-The ParaView bridge is the ParaView-side component. It plays the same role as
-the Blender add-on in `blender-mcp-server`: it must run inside the application
-you want to control. For live GUI control, start the bridge from ParaView's
-Python Shell using `scripts/start_paraview_gui_bridge.py`.
+ParaView is not Blender: Python plugins and VTK timer callbacks are pipeline
+extension mechanisms, not a safe general-purpose remote-control hook for a live
+GUI process. The supported GUI workflow here uses ParaView's client/server
+model. `paraview-mcp-launch` starts a local `pvserver`, connects the ParaView
+GUI as the first client, then connects a `pvpython` bridge client to the same
+session.
 
 ```
 ┌──────────────────────────────┐      stdio      ┌────────────────────────┐
@@ -72,24 +75,24 @@ Python Shell using `scripts/start_paraview_gui_bridge.py`.
                                                               │ 127.0.0.1:9876
                                                    ┌──────────▼─────────────┐
                                                    │ ParaView Bridge        │
-                                                   │ live GUI process       │
+                                                   │ pvpython client        │
                                                    └──────────┬─────────────┘
-                                                              │
+                                                              │ ParaView client/server
                                                    ┌──────────▼─────────────┐
-                                                   │ paraview.simple        │
-                                                   │ ParaView runtime       │
+                                                   │ pvserver + GUI client  │
+                                                   │ shared ParaView state  │
                                                    └────────────────────────┘
 ```
 
 Why a ParaView-side bridge? ParaView's useful automation API is
 `paraview.simple`, and it must execute inside a ParaView Python runtime. The
-MCP server itself is only a protocol adapter; it cannot modify a ParaView GUI
-unless the bridge is running inside that GUI process.
+MCP server itself is only a protocol adapter; it cannot modify a ParaView
+session unless a ParaView-side bridge is running.
 
 For live GUI modification, use:
 
 ```text
-Codex/Claude -> MCP server -> bridge inside open ParaView GUI -> live GUI session
+Codex/Claude -> MCP server -> pvpython bridge -> pvserver <- ParaView GUI
 ```
 
 For headless automation, use:
@@ -118,6 +121,7 @@ This installs:
 
 ```bash
 paraview-mcp-server
+paraview-mcp-launch
 ```
 
 ### Option B: Clone this repository for the ParaView bridge
@@ -137,54 +141,37 @@ This creates:
 
 ```bash
 .venv/bin/paraview-mcp-server
+.venv/bin/paraview-mcp-launch
 ```
 
 ---
 
 ## Start Everything
 
-Start the pieces in this order.
+Start the ParaView side with one command:
 
-### 1. Start the ParaView GUI Bridge
-
-Open ParaView, then run the GUI bridge script from the Python Shell:
+```bash
+cd /path/to/paraview-mcp-server
+paraview-mcp-launch
+```
 
-1. In ParaView, open **Tools -> Python Shell**.
-2. Click **Run Script**.
-3. Select:
+For a local editable checkout:
 
-```text
-/absolute/path/to/paraview-mcp-server/scripts/start_paraview_gui_bridge.py
+```bash
+.venv/bin/paraview-mcp-launch
 ```
 
 Expected output:
 
 ```text
-ParaView MCP GUI bridge started on 127.0.0.1:9876
+ParaView MCP bridge ready on 127.0.0.1:9876
+Launching ParaView GUI connected to cs://127.0.0.1:11111
 ```
 
-Do not start the live GUI bridge with `paraview --script
-scripts/start_paraview_gui_bridge.py`. ParaView runs startup scripts before the
-embedded GUI Python environment is fully ready for pipeline edits. Use **Tools
--> Python Shell -> Run Script** for the live GUI bridge.
-
-If `paraview-mcp-python` is installed into ParaView's Python environment, you
-can also start the live GUI bridge directly from the Python Shell:
+Keep that terminal running. Closing it stops the GUI, bridge, and local
+`pvserver` session.
 
-```python
-from bridge.gui_bridge import start_gui_bridge, stop_gui_bridge
-start_gui_bridge()
-```
-
-Leave ParaView open. MCP commands now modify this live GUI session.
-
-To stop the bridge from the ParaView Python Shell:
-
-```python
-stop_gui_bridge()
-```
-
-### 2. Optional: Start a Headless `pvpython` Bridge
+### Optional: Start a Headless `pvpython` Bridge
 
 Use this only when you do not need to modify an already-open ParaView GUI:
 
@@ -202,7 +189,7 @@ ParaView bridge ready on 127.0.0.1:9876
 Keep that terminal running. This controls the `pvpython` session, not a GUI
 window opened separately.
 
-### 3. Verify the Bridge Directly
+### Verify the Bridge Directly
 
 Before involving an MCP client, send one raw bridge command:
 
@@ -224,7 +211,7 @@ Expected response shape:
 
 If this fails, fix the bridge before configuring Codex or Claude.
 
-### 4. Register the MCP Server with Codex CLI
+### Register the MCP Server with Codex CLI
 
 If you installed from PyPI:
 
@@ -243,7 +230,7 @@ codex mcp list
 Codex starts the MCP server automatically when needed. The ParaView bridge
 must already be running separately.
 
-### 5. Register with Claude Desktop
+### Register with Claude Desktop
 
 **Claude Desktop** — add to `claude_desktop_config.json`:
 
@@ -265,7 +252,7 @@ which paraview-mcp-server
 
 Restart Claude Desktop after editing the config.
 
-### 6. Verify Through Your MCP Client
+### Verify Through Your MCP Client
 
 With the bridge still running, ask your MCP client:
 
@@ -274,8 +261,8 @@ List all sources in the current ParaView session.
 ```
 
 The client should call `paraview_scene_list_sources` and return the current
-ParaView pipeline sources from the live GUI session if you started
-`start_paraview_gui_bridge.py`.
+ParaView pipeline sources from the server-backed GUI session started by
+`paraview-mcp-launch`.
 
 ---
 
@@ -485,16 +472,17 @@ paraview-mcp-server/
 │   └── paraview_mcp_server/
 │       ├── __init__.py          # Re-exports main()
 │       ├── server.py            # FastMCP stdio server (31 tools)
+│       ├── launcher.py          # Starts pvserver, GUI, and bridge together
 │       └── headless.py          # Headless pvpython executor + job manager
 ├── bridge/
 │   ├── __init__.py
 │   ├── server.py                # TCP socket bridge server
-│   ├── gui_bridge.py            # Non-blocking live GUI bridge lifecycle
+│   ├── gui_bridge.py            # Experimental in-GUI bridge helpers
 │   ├── command_handler.py       # Command registry + paraview.simple handlers (27 commands)
 │   └── execution.py             # trusted local python.execute helper
 ├── scripts/
-│   ├── start_paraview_gui_bridge.py
 │   ├── start_paraview_bridge.py
+│   ├── start_paraview_gui_bridge.py
 │   ├── paraview_bridge_request.py
 │   └── library/                 # Reusable pvpython snippets
 │       ├── open_dataset.py

{paraview_mcp_python-0.1.3 → paraview_mcp_python-0.1.4}/README.md

@@ -17,18 +17,21 @@ paraview-mcp-server
 
 ## What Parts Are There?
 
-There are three moving pieces:
+There are four moving pieces in the GUI workflow:
 
 | Part | Runs where | Purpose |
 |---|---|---|
 | **MCP client** | Codex CLI, Claude Desktop, or another MCP host | Starts the MCP server and calls tools. |
 | **MCP server** | Normal Python environment | Speaks MCP over stdio and forwards tool calls to ParaView over TCP. |
-| **ParaView GUI bridge** | Already-open ParaView GUI process | Receives TCP JSON commands and executes `paraview.simple` operations in that live GUI session. |
+| **ParaView bridge** | `pvpython` process | Receives TCP JSON commands and executes `paraview.simple` operations. |
+| **ParaView runtime** | `pvserver` plus a ParaView GUI client | Owns the shared ParaView session that the GUI and bridge both use. |
 
-The ParaView bridge is the ParaView-side component. It plays the same role as
-the Blender add-on in `blender-mcp-server`: it must run inside the application
-you want to control. For live GUI control, start the bridge from ParaView's
-Python Shell using `scripts/start_paraview_gui_bridge.py`.
+ParaView is not Blender: Python plugins and VTK timer callbacks are pipeline
+extension mechanisms, not a safe general-purpose remote-control hook for a live
+GUI process. The supported GUI workflow here uses ParaView's client/server
+model. `paraview-mcp-launch` starts a local `pvserver`, connects the ParaView
+GUI as the first client, then connects a `pvpython` bridge client to the same
+session.
 
 ```
 ┌──────────────────────────────┐      stdio      ┌────────────────────────┐
@@ -39,24 +42,24 @@ Python Shell using `scripts/start_paraview_gui_bridge.py`.
                                                               │ 127.0.0.1:9876
                                                    ┌──────────▼─────────────┐
                                                    │ ParaView Bridge        │
-                                                   │ live GUI process       │
+                                                   │ pvpython client        │
                                                    └──────────┬─────────────┘
-                                                              │
+                                                              │ ParaView client/server
                                                    ┌──────────▼─────────────┐
-                                                   │ paraview.simple        │
-                                                   │ ParaView runtime       │
+                                                   │ pvserver + GUI client  │
+                                                   │ shared ParaView state  │
                                                    └────────────────────────┘
 ```
 
 Why a ParaView-side bridge? ParaView's useful automation API is
 `paraview.simple`, and it must execute inside a ParaView Python runtime. The
-MCP server itself is only a protocol adapter; it cannot modify a ParaView GUI
-unless the bridge is running inside that GUI process.
+MCP server itself is only a protocol adapter; it cannot modify a ParaView
+session unless a ParaView-side bridge is running.
 
 For live GUI modification, use:
 
 ```text
-Codex/Claude -> MCP server -> bridge inside open ParaView GUI -> live GUI session
+Codex/Claude -> MCP server -> pvpython bridge -> pvserver <- ParaView GUI
 ```
 
 For headless automation, use:
@@ -85,6 +88,7 @@ This installs:
 
 ```bash
 paraview-mcp-server
+paraview-mcp-launch
 ```
 
 ### Option B: Clone this repository for the ParaView bridge
@@ -104,54 +108,37 @@ This creates:
 
 ```bash
 .venv/bin/paraview-mcp-server
+.venv/bin/paraview-mcp-launch
 ```
 
 ---
 
 ## Start Everything
 
-Start the pieces in this order.
+Start the ParaView side with one command:
 
-### 1. Start the ParaView GUI Bridge
-
-Open ParaView, then run the GUI bridge script from the Python Shell:
+```bash
+cd /path/to/paraview-mcp-server
+paraview-mcp-launch
+```
 
-1. In ParaView, open **Tools -> Python Shell**.
-2. Click **Run Script**.
-3. Select:
+For a local editable checkout:
 
-```text
-/absolute/path/to/paraview-mcp-server/scripts/start_paraview_gui_bridge.py
+```bash
+.venv/bin/paraview-mcp-launch
 ```
 
 Expected output:
 
 ```text
-ParaView MCP GUI bridge started on 127.0.0.1:9876
+ParaView MCP bridge ready on 127.0.0.1:9876
+Launching ParaView GUI connected to cs://127.0.0.1:11111
 ```
 
-Do not start the live GUI bridge with `paraview --script
-scripts/start_paraview_gui_bridge.py`. ParaView runs startup scripts before the
-embedded GUI Python environment is fully ready for pipeline edits. Use **Tools
--> Python Shell -> Run Script** for the live GUI bridge.
-
-If `paraview-mcp-python` is installed into ParaView's Python environment, you
-can also start the live GUI bridge directly from the Python Shell:
+Keep that terminal running. Closing it stops the GUI, bridge, and local
+`pvserver` session.
 
-```python
-from bridge.gui_bridge import start_gui_bridge, stop_gui_bridge
-start_gui_bridge()
-```
-
-Leave ParaView open. MCP commands now modify this live GUI session.
-
-To stop the bridge from the ParaView Python Shell:
-
-```python
-stop_gui_bridge()
-```
-
-### 2. Optional: Start a Headless `pvpython` Bridge
+### Optional: Start a Headless `pvpython` Bridge
 
 Use this only when you do not need to modify an already-open ParaView GUI:
 
@@ -169,7 +156,7 @@ ParaView bridge ready on 127.0.0.1:9876
 Keep that terminal running. This controls the `pvpython` session, not a GUI
 window opened separately.
 
-### 3. Verify the Bridge Directly
+### Verify the Bridge Directly
 
 Before involving an MCP client, send one raw bridge command:
 
@@ -191,7 +178,7 @@ Expected response shape:
 
 If this fails, fix the bridge before configuring Codex or Claude.
 
-### 4. Register the MCP Server with Codex CLI
+### Register the MCP Server with Codex CLI
 
 If you installed from PyPI:
 
@@ -210,7 +197,7 @@ codex mcp list
 Codex starts the MCP server automatically when needed. The ParaView bridge
 must already be running separately.
 
-### 5. Register with Claude Desktop
+### Register with Claude Desktop
 
 **Claude Desktop** — add to `claude_desktop_config.json`:
 
@@ -232,7 +219,7 @@ which paraview-mcp-server
 
 Restart Claude Desktop after editing the config.
 
-### 6. Verify Through Your MCP Client
+### Verify Through Your MCP Client
 
 With the bridge still running, ask your MCP client:
 
@@ -241,8 +228,8 @@ List all sources in the current ParaView session.
 ```
 
 The client should call `paraview_scene_list_sources` and return the current
-ParaView pipeline sources from the live GUI session if you started
-`start_paraview_gui_bridge.py`.
+ParaView pipeline sources from the server-backed GUI session started by
+`paraview-mcp-launch`.
 
 ---
 
@@ -452,16 +439,17 @@ paraview-mcp-server/
 │   └── paraview_mcp_server/
 │       ├── __init__.py          # Re-exports main()
 │       ├── server.py            # FastMCP stdio server (31 tools)
+│       ├── launcher.py          # Starts pvserver, GUI, and bridge together
 │       └── headless.py          # Headless pvpython executor + job manager
 ├── bridge/
 │   ├── __init__.py
 │   ├── server.py                # TCP socket bridge server
-│   ├── gui_bridge.py            # Non-blocking live GUI bridge lifecycle
+│   ├── gui_bridge.py            # Experimental in-GUI bridge helpers
 │   ├── command_handler.py       # Command registry + paraview.simple handlers (27 commands)
 │   └── execution.py             # trusted local python.execute helper
 ├── scripts/
-│   ├── start_paraview_gui_bridge.py
 │   ├── start_paraview_bridge.py
+│   ├── start_paraview_gui_bridge.py
 │   ├── paraview_bridge_request.py
 │   └── library/                 # Reusable pvpython snippets
 │       ├── open_dataset.py

{paraview_mcp_python-0.1.3 → paraview_mcp_python-0.1.4}/docs/architecture.md

@@ -19,16 +19,16 @@
            │ JSON / TCP localhost:9876
            │ (newline-delimited JSON)
 ┌──────────▼─────────────┐
-│  ParaView GUI bridge   │  Runs inside the open ParaView GUI
-│  bridge/               │  via scripts/start_paraview_gui_bridge.py
+│  ParaView bridge       │  Runs in pvpython
+│  bridge/               │  connected to pvserver
 │  · ParaViewBridgeServer│
 │  · CommandHandler      │  27 registered commands
 │  · execute_code()      │
 └──────────┬─────────────┘
-           │
+           │ ParaView client/server
 ┌──────────▼─────────────┐
-│  paraview.simple       │  Live ParaView GUI session
-│  servermanager         │
+│  pvserver              │  Shared ParaView state
+│  ParaView GUI client   │
 └────────────────────────┘
 ```
 
@@ -220,31 +220,32 @@ MCP client
 
 ## Lifecycle
 
-1. User starts the live GUI bridge from ParaView: **Tools → Python Shell → Run Script**,
-   selecting `scripts/start_paraview_gui_bridge.py`.
-2. Bridge server binds to `127.0.0.1:9876` and listens for TCP connections.
-3. User starts an MCP client (Claude Desktop, Codex CLI, etc.)
-4. MCP client spawns `paraview-mcp-server` over stdio.
-5. MCP server connects to bridge on startup (or lazy-connects on first tool call).
-6. User issues a natural language request → client calls an MCP tool → server
+1. User starts the ParaView side with `paraview-mcp-launch`.
+2. The launcher starts `pvserver --multi-clients`.
+3. The launcher connects the ParaView GUI as the first client.
+4. The launcher starts `pvpython scripts/start_paraview_bridge.py --server-host ...`,
+   which connects to the same `pvserver` and binds the MCP TCP bridge on
+   `127.0.0.1:9876`.
+5. User starts an MCP client (Claude Desktop, Codex CLI, etc.)
+6. MCP client spawns `paraview-mcp-server` over stdio.
+7. MCP server connects to bridge on startup (or lazy-connects on first tool call).
+8. User issues a natural language request → client calls an MCP tool → server
    forwards as JSON → bridge dispatches → returns result.
-7. User stops the GUI bridge with `stop_gui_bridge()` in ParaView's Python Shell.
-   Server reconnects on next call if the bridge restarts.
+9. User exits ParaView or presses Ctrl+C in the launcher terminal to stop the
+   GUI, bridge, and local `pvserver`.
 
 ---
 
 ## Configuration
 
-### Live GUI Bridge
+### Server-backed GUI launcher
 
-Run this from ParaView's Python Shell with **Run Script**:
-
-```text
-scripts/start_paraview_gui_bridge.py
+```bash
+paraview-mcp-launch
 ```
 
-The script starts a background TCP server in the open ParaView GUI process and
-returns immediately.
+This starts a local `pvserver`, connects the ParaView GUI, then connects a
+`pvpython` bridge client to the same server-backed ParaView session.
 
 ### Headless Bridge
 

{paraview_mcp_python-0.1.3 → paraview_mcp_python-0.1.4}/docs/python-execute-design.md

@@ -8,9 +8,10 @@ escape hatch for workflows that require more than the fixed tool set.
 Two transports are supported:
 
 1. **Bridge** (default) - code runs inside the active bridge process via exec().
-   For live GUI control, that process is the open ParaView GUI where
-   `scripts/start_paraview_gui_bridge.py` was run. For headless control, it is
-   the `pvpython scripts/start_paraview_bridge.py` process.
+   For GUI control started by `paraview-mcp-launch`, that process is a
+   `pvpython` client connected to the same `pvserver` as the ParaView GUI. For
+   headless control, it is the standalone `pvpython scripts/start_paraview_bridge.py`
+   process.
 2. **Headless** - code runs in a separate pvpython subprocess via HeadlessPvpythonExecutor.
 
 ---
@@ -71,7 +72,8 @@ Headless transport adds:
 ### Trusted local execution
 
 Bridge scripts run inside the local ParaView Python process and may import
-normal Python modules. In live GUI mode, that is the open ParaView GUI process.
+normal Python modules. In GUI mode, that is a `pvpython` bridge client attached
+to the same `pvserver` as the ParaView GUI.
 This is intentional: `paraview_python_exec` is the escape hatch for full
 ParaView automation when the fixed MCP tool set is too small.
 

{paraview_mcp_python-0.1.3 → paraview_mcp_python-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paraview-mcp-python"
-version = "0.1.3"
+version = "0.1.4"
 description = "MCP server for controlling ParaView via AI assistants"
 readme = "README.md"
 license = "MIT"
@@ -62,6 +62,7 @@ include = [
 
 [project.scripts]
 paraview-mcp-server = "paraview_mcp_server:main"
+paraview-mcp-launch = "paraview_mcp_server.launcher:main"
 
 [tool.pytest.ini_options]
 asyncio_mode = "strict"

{paraview_mcp_python-0.1.3 → paraview_mcp_python-0.1.4}/scripts/start_paraview_bridge.py

@@ -4,6 +4,7 @@
 Run this with pvpython:
 
     pvpython scripts/start_paraview_bridge.py [--host 127.0.0.1] [--port 9876]
+    pvpython scripts/start_paraview_bridge.py --server-host 127.0.0.1 --server-port 11111
 
 The bridge will listen for JSON commands from the paraview-mcp-server process.
 """
@@ -28,6 +29,8 @@ def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="Start the ParaView TCP bridge server.")
     parser.add_argument("--host", default="127.0.0.1", help="Host to bind to")
     parser.add_argument("--port", type=int, default=9876, help="Port to listen on")
+    parser.add_argument("--server-host", help="Optional pvserver host to connect to before starting the bridge")
+    parser.add_argument("--server-port", type=int, default=11111, help="pvserver port used with --server-host")
     return parser.parse_args()
 
 
@@ -43,13 +46,28 @@ def main() -> None:
 
     from bridge.server import ParaViewBridgeServer
 
+    process_server_events = None
+    if args.server_host:
+        from paraview.simple import Connect
+
+        logger.info("Connecting bridge runtime to pvserver at %s:%s.", args.server_host, args.server_port)
+        Connect(args.server_host, args.server_port)
+        try:
+            from paraview.collaboration import processServerEvents
+
+            process_server_events = processServerEvents
+        except ImportError:
+            process_server_events = None
+
     server = ParaViewBridgeServer(host=args.host, port=args.port)
     server.start()
 
     logger.info("ParaView bridge ready on %s:%s — press Ctrl+C to stop.", args.host, args.port)
     try:
         while True:
-            time.sleep(1)
+            if process_server_events is not None:
+                process_server_events()
+            time.sleep(0.1)
     except KeyboardInterrupt:
         logger.info("Shutting down ParaView bridge.")
         server.stop()

paraview_mcp_python-0.1.4/src/paraview_mcp_server/launcher.py

@@ -0,0 +1,151 @@
+"""Launch a server-backed ParaView GUI session with the MCP bridge attached."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+
+def _repo_root() -> Path:
+    package_root = Path(__file__).resolve().parents[2]
+    if (package_root / "scripts" / "start_paraview_bridge.py").is_file():
+        return package_root
+    return Path.cwd()
+
+
+def _wait_for_port(host: str, port: int, *, timeout: float, name: str) -> None:
+    deadline = time.monotonic() + timeout
+    last_error: OSError | None = None
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection((host, port), timeout=0.5):
+                return
+        except OSError as exc:
+            last_error = exc
+            time.sleep(0.2)
+    raise RuntimeError(f"Timed out waiting for {name} on {host}:{port}: {last_error}")
+
+
+def _wait_for_listen_port(port: int, *, timeout: float, name: str) -> None:
+    deadline = time.monotonic() + timeout
+    needle = f":{port:04X}"
+    while time.monotonic() < deadline:
+        try:
+            lines = Path("/proc/net/tcp").read_text(encoding="utf-8").splitlines()
+        except OSError:
+            lines = []
+        for line in lines[1:]:
+            columns = line.split()
+            if len(columns) >= 4 and columns[1].endswith(needle) and columns[3] == "0A":
+                return
+        time.sleep(0.2)
+    raise RuntimeError(f"Timed out waiting for {name} to listen on port {port}")
+
+
+def _terminate(proc: subprocess.Popen[bytes] | None) -> None:
+    if proc is None or proc.poll() is not None:
+        return
+    proc.terminate()
+    try:
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=5)
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Start pvserver, attach the ParaView MCP bridge, and launch a ParaView GUI "
+            "connected to the same server-backed session."
+        )
+    )
+    parser.add_argument("--paraview", default=os.environ.get("PARAVIEW_BIN", "paraview"), help="ParaView executable")
+    parser.add_argument("--pvserver", default=os.environ.get("PVSERVER_BIN", "pvserver"), help="pvserver executable")
+    parser.add_argument("--pvpython", default=os.environ.get("PVPYTHON_BIN", "pvpython"), help="pvpython executable")
+    parser.add_argument("--server-host", default="127.0.0.1", help="Host used by local clients to reach pvserver")
+    parser.add_argument("--server-port", type=int, default=11111, help="pvserver port")
+    parser.add_argument("--bridge-host", default="127.0.0.1", help="MCP bridge bind host")
+    parser.add_argument("--bridge-port", type=int, default=9876, help="MCP bridge bind port")
+    parser.add_argument(
+        "paraview_args",
+        nargs=argparse.REMAINDER,
+        help="Extra arguments passed to ParaView. Prefix them with --, for example: -- --data file.vtu",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    repo_root = _repo_root()
+    bridge_script = repo_root / "scripts" / "start_paraview_bridge.py"
+    if not bridge_script.is_file():
+        raise SystemExit(f"Could not find bridge script: {bridge_script}")
+
+    paraview = shutil.which(args.paraview) or args.paraview
+    pvserver = shutil.which(args.pvserver) or args.pvserver
+    pvpython = shutil.which(args.pvpython) or args.pvpython
+    extra_args = list(args.paraview_args)
+    if extra_args[:1] == ["--"]:
+        extra_args = extra_args[1:]
+
+    server_proc: subprocess.Popen[bytes] | None = None
+    bridge_proc: subprocess.Popen[bytes] | None = None
+    gui_proc: subprocess.Popen[bytes] | None = None
+
+    try:
+        server_proc = subprocess.Popen(
+            [
+                pvserver,
+                "--multi-clients",
+                f"--server-port={args.server_port}",
+                "--bind-address=127.0.0.1",
+            ]
+        )
+        _wait_for_listen_port(args.server_port, timeout=20, name="pvserver")
+
+        print(f"Launching ParaView GUI connected to cs://{args.server_host}:{args.server_port}", flush=True)
+        gui_proc = subprocess.Popen(
+            [
+                paraview,
+                "--server-url",
+                f"cs://{args.server_host}:{args.server_port}",
+                *extra_args,
+            ]
+        )
+        time.sleep(3)
+
+        bridge_proc = subprocess.Popen(
+            [
+                pvpython,
+                str(bridge_script),
+                "--host",
+                args.bridge_host,
+                "--port",
+                str(args.bridge_port),
+                "--server-host",
+                args.server_host,
+                "--server-port",
+                str(args.server_port),
+            ],
+            cwd=str(repo_root),
+        )
+        _wait_for_port(args.bridge_host, args.bridge_port, timeout=20, name="ParaView MCP bridge")
+        print(f"ParaView MCP bridge ready on {args.bridge_host}:{args.bridge_port}", flush=True)
+        return gui_proc.wait()
+    except KeyboardInterrupt:
+        return 130
+    finally:
+        _terminate(gui_proc)
+        _terminate(bridge_proc)
+        _terminate(server_proc)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

paraview_mcp_python-0.1.4/tests/test_launcher.py

@@ -0,0 +1,63 @@
+"""Tests for the ParaView MCP launcher."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from paraview_mcp_server import launcher
+
+
+def test_launcher_starts_gui_before_bridge():
+    calls = []
+
+    def fake_popen(cmd, **kwargs):
+        proc = MagicMock()
+        proc.poll.return_value = None
+        proc.wait.return_value = 0
+        proc.cmd = cmd
+        calls.append((cmd, kwargs, proc))
+        return proc
+
+    with (
+        patch("paraview_mcp_server.launcher._repo_root", return_value=Path.cwd()),
+        patch("paraview_mcp_server.launcher._wait_for_listen_port"),
+        patch("paraview_mcp_server.launcher._wait_for_port"),
+        patch("paraview_mcp_server.launcher.time.sleep"),
+        patch("paraview_mcp_server.launcher.subprocess.Popen", side_effect=fake_popen),
+        patch("paraview_mcp_server.launcher.shutil.which", side_effect=lambda value: value),
+    ):
+        result = launcher.main([])
+
+    assert result == 0
+    assert calls[0][0][0] == "pvserver"
+    assert "--multi-clients" in calls[0][0]
+    assert calls[1][0][0] == "paraview"
+    assert "--server-url" in calls[1][0]
+    assert calls[2][0][0] == "pvpython"
+    assert "--server-host" in calls[2][0]
+
+
+def test_launcher_strips_separator_from_paraview_args():
+    calls = []
+
+    def fake_popen(cmd, **kwargs):
+        proc = MagicMock()
+        proc.poll.return_value = None
+        proc.wait.return_value = 0
+        calls.append(cmd)
+        return proc
+
+    with (
+        patch("paraview_mcp_server.launcher._repo_root", return_value=Path.cwd()),
+        patch("paraview_mcp_server.launcher._wait_for_listen_port"),
+        patch("paraview_mcp_server.launcher._wait_for_port"),
+        patch("paraview_mcp_server.launcher.time.sleep"),
+        patch("paraview_mcp_server.launcher.subprocess.Popen", side_effect=fake_popen),
+        patch("paraview_mcp_server.launcher.shutil.which", side_effect=lambda value: value),
+    ):
+        launcher.main(["--", "--data", "disk.vtu"])
+
+    assert "--data" in calls[1]
+    assert "disk.vtu" in calls[1]
+    assert "--" not in calls[1]