paraview-mcp-python 0.1.1__tar.gz → 0.1.2__tar.gz

{paraview_mcp_python-0.1.1 → paraview_mcp_python-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paraview-mcp-python
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -31,50 +31,99 @@ Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.11; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# paraview-mcp-server
+# ParaView MCP Server
 
 **Control ParaView with AI assistants through the Model Context Protocol.**
 
-`paraview-mcp-server` is a two-process bridge that lets AI assistants such as Claude Desktop
-and Codex CLI open datasets, apply filters, color data, and export screenshots in ParaView
-using natural language.
+`paraview-mcp-python` provides an MCP server plus a ParaView-side bridge so
+AI assistants such as Codex CLI and Claude Desktop can inspect a ParaView
+session, open datasets, apply filters, color data, run ParaView Python, and
+export screenshots.
+
+The command installed for MCP clients is still:
+
+```bash
+paraview-mcp-server
+```
 
 ---
 
-## How it works
+## What Parts Are There?
+
+There are three moving pieces:
+
+| 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. |
+
+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`.
 
 ```
-MCP Client (Claude Desktop, Codex CLI, …)
-      ⇅  stdio
-paraview-mcp-server            ← thin MCP server, defines 31 tools
-      ⇅  JSON / TCP localhost:9876
-ParaView bridge (pvpython)     ← dispatches commands with paraview.simple
-      ⇅
-paraview.simple / servermanager
+┌──────────────────────────────┐      stdio      ┌────────────────────────┐
+│ MCP Client                   │ ◄──────────────► │ MCP Server             │
+│ Codex / Claude / other host  │                  │ paraview-mcp-server    │
+└──────────────────────────────┘                  └──────────┬─────────────┘
+                                                              │ JSON/TCP
+                                                              │ 127.0.0.1:9876
+                                                   ┌──────────▼─────────────┐
+                                                   │ ParaView Bridge        │
+                                                   │ live GUI process       │
+                                                   └──────────┬─────────────┘
+                                                              │
+                                                   ┌──────────▼─────────────┐
+                                                   │ paraview.simple        │
+                                                   │ ParaView runtime       │
+                                                   └────────────────────────┘
 ```
 
-- The **MCP server** is a normal Python package. It speaks MCP over stdio and forwards
-  every tool call as a JSON request to the bridge over a local TCP socket.
-- The **bridge** runs inside `pvpython`. It receives JSON commands, dispatches them through
-  a command registry, calls `paraview.simple`, and returns JSON results.
-- Neither process depends on the other's code at import time.
-- A **headless pvpython executor** lets the MCP server run scripts in a separate
-  `pvpython` process for long-running or async workflows (no bridge needed).
+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.
+
+For live GUI modification, use:
+
+```text
+Codex/Claude -> MCP server -> bridge inside open ParaView GUI -> live GUI session
+```
+
+For headless automation, use:
+
+```text
+Codex/Claude -> MCP server -> bridge inside pvpython -> headless ParaView runtime
+```
 
 See [`docs/architecture.md`](docs/architecture.md) for a full diagram, protocol reference,
 and tool namespace table.
 
 ---
 
-## Quick start
+## Install
 
-### 1. Install the MCP server
+### Option A: Install the MCP server from PyPI
+
+Use this when you only need the MCP server executable in your normal Python
+environment:
 
 ```bash
 pip install paraview-mcp-python
 ```
 
-For local development from this repository:
+This installs:
+
+```bash
+paraview-mcp-server
+```
+
+### Option B: Clone this repository for the ParaView bridge
+
+The bridge code must be available to ParaView's Python runtime. For live GUI
+control and local development, clone the repository:
 
 ```bash
 git clone https://github.com/djeada/paraview-mcp-server.git
@@ -84,18 +133,112 @@ source .venv/bin/activate          # Windows: .venv\Scripts\activate
 pip install -e .
 ```
 
-### 2. Start the ParaView bridge
+This creates:
+
+```bash
+.venv/bin/paraview-mcp-server
+```
+
+---
+
+## Start Everything
+
+Start the pieces in this order.
+
+### 1. Start the ParaView GUI Bridge
+
+Open ParaView, then run the GUI bridge script from the Python Shell:
+
+1. In ParaView, open **Tools -> Python Shell**.
+2. Click **Run Script**.
+3. Select:
+
+```text
+/absolute/path/to/paraview-mcp-server/scripts/start_paraview_gui_bridge.py
+```
+
+Expected output:
+
+```text
+ParaView MCP GUI bridge started on 127.0.0.1:9876
+```
+
+If `paraview-mcp-python` is installed into ParaView's Python environment, you
+can also start the live GUI bridge directly from the Python Shell:
+
+```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
 
-In a terminal that has `pvpython` on `PATH`:
+Use this only when you do not need to modify an already-open ParaView GUI:
 
 ```bash
+cd /path/to/paraview-mcp-server
 pvpython scripts/start_paraview_bridge.py
-# → ParaView bridge ready on 127.0.0.1:9876
 ```
 
-The bridge listens for JSON commands from the MCP server.
+Expected output:
+
+```text
+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
+
+Before involving an MCP client, send one raw bridge command:
+
+```bash
+python scripts/paraview_bridge_request.py scene.get_info
+```
+
+Expected response shape:
+
+```json
+{
+  "success": true,
+  "result": {
+    "source_count": 0,
+    "active_view_type": "RenderView"
+  }
+}
+```
+
+If this fails, fix the bridge before configuring Codex or Claude.
+
+### 4. Register the MCP Server with Codex CLI
+
+If you installed from PyPI:
+
+```bash
+codex mcp add paraview -- paraview-mcp-server
+codex mcp list
+```
+
+If you are using the local repository:
 
-### 3. Register the MCP server with your AI client
+```bash
+codex mcp add paraview -- /absolute/path/to/paraview-mcp-server/.venv/bin/paraview-mcp-server
+codex mcp list
+```
+
+Codex starts the MCP server automatically when needed. The ParaView bridge
+must already be running separately.
+
+### 5. Register with Claude Desktop
 
 **Claude Desktop** — add to `claude_desktop_config.json`:
 
@@ -109,12 +252,42 @@ The bridge listens for JSON commands from the MCP server.
 }
 ```
 
-**Codex CLI:**
+For a PyPI install, use the absolute path returned by:
 
 ```bash
-codex mcp add paraview -- /absolute/path/to/.venv/bin/paraview-mcp-server
+which paraview-mcp-server
 ```
 
+Restart Claude Desktop after editing the config.
+
+### 6. Verify Through Your MCP Client
+
+With the bridge still running, ask your MCP client:
+
+```text
+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`.
+
+---
+
+## What Can It Control?
+
+There are two levels of control:
+
+1. **Fixed MCP tools** for common workflows: scene inspection, loading data,
+   filters, display/coloring, camera, screenshots, data export, and animation
+   export.
+2. **Python execution** through `paraview_python_exec`, which can run trusted
+   local Python inside the ParaView bridge session. Use this for anything not
+   covered by a fixed tool, including arbitrary `paraview.simple` scripts.
+
+So the fixed tool list is intentionally finite, but the Python execution tool
+is the general escape hatch for the broader ParaView API.
+
 ---
 
 ## Example prompts
@@ -261,12 +434,12 @@ Async jobs run in a separate headless `pvpython` process via `HeadlessPvpythonEx
 
 ## Python execution trust model
 
-- **Trusted local execution** — `paraview_python_exec` can run arbitrary Python available to `pvpython`,
-  including imports and full `paraview.simple` workflows.
+- **Trusted local execution** — `paraview_python_exec` can run arbitrary Python available to the active
+  ParaView Python process, including imports and full `paraview.simple` workflows.
 - **Output bounding** — stdout/stderr capped at **50 KB**.
 - **Cooperative timeout** — default 30 seconds per script execution.
 - **Script path validation** — optionally restrict execution to approved root directories.
-- The bridge runs inside `pvpython` with the same trust level as a local ParaView session.
+- The bridge runs inside ParaView's Python runtime with the same trust level as that local session.
 - This is a local desktop automation tool — not a public API sandbox.
 
 ---
@@ -311,9 +484,11 @@ paraview-mcp-server/
 ├── bridge/
 │   ├── __init__.py
 │   ├── server.py                # TCP socket bridge server
+│   ├── gui_bridge.py            # Non-blocking live GUI bridge lifecycle
 │   ├── 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
 │   ├── paraview_bridge_request.py
 │   └── library/                 # Reusable pvpython snippets

{paraview_mcp_python-0.1.1 → paraview_mcp_python-0.1.2}/README.md

@@ -1,47 +1,96 @@
-# paraview-mcp-server
+# ParaView MCP Server
 
 **Control ParaView with AI assistants through the Model Context Protocol.**
 
-`paraview-mcp-server` is a two-process bridge that lets AI assistants such as Claude Desktop
-and Codex CLI open datasets, apply filters, color data, and export screenshots in ParaView
-using natural language.
+`paraview-mcp-python` provides an MCP server plus a ParaView-side bridge so
+AI assistants such as Codex CLI and Claude Desktop can inspect a ParaView
+session, open datasets, apply filters, color data, run ParaView Python, and
+export screenshots.
+
+The command installed for MCP clients is still:
+
+```bash
+paraview-mcp-server
+```
 
 ---
 
-## How it works
+## What Parts Are There?
+
+There are three moving pieces:
+
+| 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. |
+
+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`.
 
 ```
-MCP Client (Claude Desktop, Codex CLI, …)
-      ⇅  stdio
-paraview-mcp-server            ← thin MCP server, defines 31 tools
-      ⇅  JSON / TCP localhost:9876
-ParaView bridge (pvpython)     ← dispatches commands with paraview.simple
-      ⇅
-paraview.simple / servermanager
+┌──────────────────────────────┐      stdio      ┌────────────────────────┐
+│ MCP Client                   │ ◄──────────────► │ MCP Server             │
+│ Codex / Claude / other host  │                  │ paraview-mcp-server    │
+└──────────────────────────────┘                  └──────────┬─────────────┘
+                                                              │ JSON/TCP
+                                                              │ 127.0.0.1:9876
+                                                   ┌──────────▼─────────────┐
+                                                   │ ParaView Bridge        │
+                                                   │ live GUI process       │
+                                                   └──────────┬─────────────┘
+                                                              │
+                                                   ┌──────────▼─────────────┐
+                                                   │ paraview.simple        │
+                                                   │ ParaView runtime       │
+                                                   └────────────────────────┘
 ```
 
-- The **MCP server** is a normal Python package. It speaks MCP over stdio and forwards
-  every tool call as a JSON request to the bridge over a local TCP socket.
-- The **bridge** runs inside `pvpython`. It receives JSON commands, dispatches them through
-  a command registry, calls `paraview.simple`, and returns JSON results.
-- Neither process depends on the other's code at import time.
-- A **headless pvpython executor** lets the MCP server run scripts in a separate
-  `pvpython` process for long-running or async workflows (no bridge needed).
+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.
+
+For live GUI modification, use:
+
+```text
+Codex/Claude -> MCP server -> bridge inside open ParaView GUI -> live GUI session
+```
+
+For headless automation, use:
+
+```text
+Codex/Claude -> MCP server -> bridge inside pvpython -> headless ParaView runtime
+```
 
 See [`docs/architecture.md`](docs/architecture.md) for a full diagram, protocol reference,
 and tool namespace table.
 
 ---
 
-## Quick start
+## Install
 
-### 1. Install the MCP server
+### Option A: Install the MCP server from PyPI
+
+Use this when you only need the MCP server executable in your normal Python
+environment:
 
 ```bash
 pip install paraview-mcp-python
 ```
 
-For local development from this repository:
+This installs:
+
+```bash
+paraview-mcp-server
+```
+
+### Option B: Clone this repository for the ParaView bridge
+
+The bridge code must be available to ParaView's Python runtime. For live GUI
+control and local development, clone the repository:
 
 ```bash
 git clone https://github.com/djeada/paraview-mcp-server.git
@@ -51,18 +100,112 @@ source .venv/bin/activate          # Windows: .venv\Scripts\activate
 pip install -e .
 ```
 
-### 2. Start the ParaView bridge
+This creates:
+
+```bash
+.venv/bin/paraview-mcp-server
+```
+
+---
+
+## Start Everything
+
+Start the pieces in this order.
+
+### 1. Start the ParaView GUI Bridge
+
+Open ParaView, then run the GUI bridge script from the Python Shell:
+
+1. In ParaView, open **Tools -> Python Shell**.
+2. Click **Run Script**.
+3. Select:
+
+```text
+/absolute/path/to/paraview-mcp-server/scripts/start_paraview_gui_bridge.py
+```
+
+Expected output:
+
+```text
+ParaView MCP GUI bridge started on 127.0.0.1:9876
+```
+
+If `paraview-mcp-python` is installed into ParaView's Python environment, you
+can also start the live GUI bridge directly from the Python Shell:
+
+```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
 
-In a terminal that has `pvpython` on `PATH`:
+Use this only when you do not need to modify an already-open ParaView GUI:
 
 ```bash
+cd /path/to/paraview-mcp-server
 pvpython scripts/start_paraview_bridge.py
-# → ParaView bridge ready on 127.0.0.1:9876
 ```
 
-The bridge listens for JSON commands from the MCP server.
+Expected output:
+
+```text
+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
+
+Before involving an MCP client, send one raw bridge command:
+
+```bash
+python scripts/paraview_bridge_request.py scene.get_info
+```
+
+Expected response shape:
+
+```json
+{
+  "success": true,
+  "result": {
+    "source_count": 0,
+    "active_view_type": "RenderView"
+  }
+}
+```
+
+If this fails, fix the bridge before configuring Codex or Claude.
+
+### 4. Register the MCP Server with Codex CLI
+
+If you installed from PyPI:
+
+```bash
+codex mcp add paraview -- paraview-mcp-server
+codex mcp list
+```
+
+If you are using the local repository:
 
-### 3. Register the MCP server with your AI client
+```bash
+codex mcp add paraview -- /absolute/path/to/paraview-mcp-server/.venv/bin/paraview-mcp-server
+codex mcp list
+```
+
+Codex starts the MCP server automatically when needed. The ParaView bridge
+must already be running separately.
+
+### 5. Register with Claude Desktop
 
 **Claude Desktop** — add to `claude_desktop_config.json`:
 
@@ -76,12 +219,42 @@ The bridge listens for JSON commands from the MCP server.
 }
 ```
 
-**Codex CLI:**
+For a PyPI install, use the absolute path returned by:
 
 ```bash
-codex mcp add paraview -- /absolute/path/to/.venv/bin/paraview-mcp-server
+which paraview-mcp-server
 ```
 
+Restart Claude Desktop after editing the config.
+
+### 6. Verify Through Your MCP Client
+
+With the bridge still running, ask your MCP client:
+
+```text
+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`.
+
+---
+
+## What Can It Control?
+
+There are two levels of control:
+
+1. **Fixed MCP tools** for common workflows: scene inspection, loading data,
+   filters, display/coloring, camera, screenshots, data export, and animation
+   export.
+2. **Python execution** through `paraview_python_exec`, which can run trusted
+   local Python inside the ParaView bridge session. Use this for anything not
+   covered by a fixed tool, including arbitrary `paraview.simple` scripts.
+
+So the fixed tool list is intentionally finite, but the Python execution tool
+is the general escape hatch for the broader ParaView API.
+
 ---
 
 ## Example prompts
@@ -228,12 +401,12 @@ Async jobs run in a separate headless `pvpython` process via `HeadlessPvpythonEx
 
 ## Python execution trust model
 
-- **Trusted local execution** — `paraview_python_exec` can run arbitrary Python available to `pvpython`,
-  including imports and full `paraview.simple` workflows.
+- **Trusted local execution** — `paraview_python_exec` can run arbitrary Python available to the active
+  ParaView Python process, including imports and full `paraview.simple` workflows.
 - **Output bounding** — stdout/stderr capped at **50 KB**.
 - **Cooperative timeout** — default 30 seconds per script execution.
 - **Script path validation** — optionally restrict execution to approved root directories.
-- The bridge runs inside `pvpython` with the same trust level as a local ParaView session.
+- The bridge runs inside ParaView's Python runtime with the same trust level as that local session.
 - This is a local desktop automation tool — not a public API sandbox.
 
 ---
@@ -278,9 +451,11 @@ paraview-mcp-server/
 ├── bridge/
 │   ├── __init__.py
 │   ├── server.py                # TCP socket bridge server
+│   ├── gui_bridge.py            # Non-blocking live GUI bridge lifecycle
 │   ├── 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
 │   ├── paraview_bridge_request.py
 │   └── library/                 # Reusable pvpython snippets

paraview_mcp_python-0.1.2/bridge/gui_bridge.py

@@ -0,0 +1,55 @@
+"""Helpers for starting the bridge from an already-open ParaView GUI session."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from bridge.server import HOST, PORT, ParaViewBridgeServer
+
+_SERVER: ParaViewBridgeServer | None = None
+
+
+def start_gui_bridge(host: str = HOST, port: int = PORT) -> dict[str, Any]:
+    """Start the bridge inside the current ParaView Python process.
+
+    This function is intentionally non-blocking so it can be called from the
+    ParaView GUI Python shell without freezing the application.
+    """
+    global _SERVER
+    if _SERVER is not None and _SERVER.is_running:
+        return {
+            "host": _SERVER.host,
+            "port": _SERVER.port,
+            "running": True,
+            "already_running": True,
+        }
+
+    server = ParaViewBridgeServer(host=host, port=port)
+    server.start()
+    _SERVER = server
+    return {
+        "host": server.host,
+        "port": server.port,
+        "running": True,
+        "already_running": False,
+    }
+
+
+def stop_gui_bridge() -> dict[str, Any]:
+    """Stop the bridge started by :func:`start_gui_bridge`."""
+    global _SERVER
+    if _SERVER is None:
+        return {"running": False, "stopped": False}
+
+    host = _SERVER.host
+    port = _SERVER.port
+    _SERVER.stop()
+    _SERVER = None
+    return {"host": host, "port": port, "running": False, "stopped": True}
+
+
+def gui_bridge_status() -> dict[str, Any]:
+    """Return the current GUI bridge status."""
+    if _SERVER is None or not _SERVER.is_running:
+        return {"running": False}
+    return {"host": _SERVER.host, "port": _SERVER.port, "running": True}

{paraview_mcp_python-0.1.1 → paraview_mcp_python-0.1.2}/bridge/models.py

@@ -1,7 +1,7 @@
 """Dependency-free bridge command parameter validation.
 
-The bridge runs inside ParaView's ``pvpython``, which commonly does not have
-the MCP server's Python dependencies installed.  These classes intentionally
+The bridge runs inside ParaView's Python runtime, which commonly does not have
+the MCP server's Python dependencies installed. These classes intentionally
 provide the small ``model_validate(...).model_dump(...)`` surface used by the
 command handler without importing third-party packages.
 """

{paraview_mcp_python-0.1.1 → paraview_mcp_python-0.1.2}/bridge/server.py

@@ -33,6 +33,18 @@ class ParaViewBridgeServer:
         self._handler = CommandHandler()
         self._handler_lock = threading.Lock()
 
+    @property
+    def host(self) -> str:
+        return self._host
+
+    @property
+    def port(self) -> int:
+        return self._port
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
     def start(self):
         if self._running:
             return
@@ -40,6 +52,7 @@ class ParaViewBridgeServer:
         self._server_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
         self._server_socket.settimeout(1.0)
         self._server_socket.bind((self._host, self._port))
+        self._host, self._port = self._server_socket.getsockname()[:2]
         self._server_socket.listen(5)
         self._running = True
         self._thread = threading.Thread(target=self._accept_loop, daemon=True)

{paraview_mcp_python-0.1.1 → paraview_mcp_python-0.1.2}/docs/architecture.md

@@ -19,20 +19,26 @@
            │ JSON / TCP localhost:9876
            │ (newline-delimited JSON)
 ┌──────────▼─────────────┐
-│  ParaView bridge       │  Runs inside pvpython
-│  bridge/               │
+│  ParaView GUI bridge   │  Runs inside the open ParaView GUI
+│  bridge/               │  via scripts/start_paraview_gui_bridge.py
 │  · ParaViewBridgeServer│
 │  · CommandHandler      │  27 registered commands
 │  · execute_code()      │
 └──────────┬─────────────┘
            │
 ┌──────────▼─────────────┐
-│  paraview.simple       │  ParaView Python API
+│  paraview.simple       │  Live ParaView GUI session
 │  servermanager         │
 └────────────────────────┘
 ```
 
-Alternative headless transport (no bridge required):
+Alternative headless bridge:
+
+```
+MCP Client → paraview-mcp-server → pvpython scripts/start_paraview_bridge.py
+```
+
+Alternative headless script transport (no long-running bridge required):
 
 ```
 ┌────────────────────────┐
@@ -67,6 +73,7 @@ Alternative headless transport (no bridge required):
 | Module | Responsibility |
 |---|---|
 | `server.py` | Threaded TCP socket server, newline-delimited JSON framing |
+| `gui_bridge.py` | Non-blocking helpers for starting/stopping the bridge inside ParaView GUI |
 | `command_handler.py` | Command registry mapping 27 command names to `paraview.simple` calls |
 | `execution.py` | `execute_code()` — trusted local Python execution with timeout, output cap, and optional script path validation |
 | `__init__.py` | Package marker |
@@ -213,20 +220,33 @@ MCP client
 
 ## Lifecycle
 
-1. User starts the bridge: `pvpython scripts/start_paraview_bridge.py`
+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
    forwards as JSON → bridge dispatches → returns result.
-7. User stops the bridge with Ctrl+C. Server reconnects on next call if the bridge restarts.
+7. User stops the GUI bridge with `stop_gui_bridge()` in ParaView's Python Shell.
+   Server reconnects on next call if the bridge restarts.
 
 ---
 
 ## Configuration
 
-### Bridge
+### Live GUI Bridge
+
+Run this from ParaView's Python Shell with **Run Script**:
+
+```text
+scripts/start_paraview_gui_bridge.py
+```
+
+The script starts a background TCP server in the open ParaView GUI process and
+returns immediately.
+
+### Headless Bridge
 
 ```bash
 pvpython scripts/start_paraview_bridge.py --host 127.0.0.1 --port 9876

{paraview_mcp_python-0.1.1 → paraview_mcp_python-0.1.2}/docs/python-execute-design.md

@@ -7,7 +7,10 @@ escape hatch for workflows that require more than the fixed tool set.
 
 Two transports are supported:
 
-1. **Bridge** (default) - code runs inside the running pvpython bridge process via exec().
+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.
 2. **Headless** - code runs in a separate pvpython subprocess via HeadlessPvpythonExecutor.
 
 ---
@@ -67,9 +70,10 @@ Headless transport adds:
 
 ### Trusted local execution
 
-Bridge scripts run inside the local `pvpython` process and may import normal
-Python modules. This is intentional: `paraview_python_exec` is the escape hatch
-for full ParaView automation when the fixed MCP tool set is too small.
+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.
+This is intentional: `paraview_python_exec` is the escape hatch for full
+ParaView automation when the fixed MCP tool set is too small.
 
 ### Output bounding
 

{paraview_mcp_python-0.1.1 → paraview_mcp_python-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paraview-mcp-python"
-version = "0.1.1"
+version = "0.1.2"
 description = "MCP server for controlling ParaView via AI assistants"
 readme = "README.md"
 license = "MIT"
@@ -46,7 +46,7 @@ dev = [
 ]
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/paraview_mcp_server"]
+packages = ["src/paraview_mcp_server", "bridge"]
 
 [tool.hatch.build.targets.sdist]
 include = [

paraview_mcp_python-0.1.2/scripts/start_paraview_gui_bridge.py

@@ -0,0 +1,42 @@
+"""Start the MCP bridge inside an already-open ParaView GUI session.
+
+Run from ParaView:
+
+    Tools -> Python Shell -> Run Script
+
+Select this file. The script starts the TCP bridge in a background thread and
+returns immediately, so the ParaView GUI remains usable. MCP commands will then
+modify this open ParaView session.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s")
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if REPO_ROOT not in sys.path:
+    sys.path.insert(0, REPO_ROOT)
+
+from bridge.gui_bridge import gui_bridge_status, start_gui_bridge, stop_gui_bridge  # noqa: E402
+
+globals()["stop_gui_bridge"] = stop_gui_bridge
+globals()["gui_bridge_status"] = gui_bridge_status
+
+
+def main() -> None:
+    host = os.environ.get("PARAVIEW_MCP_HOST", "127.0.0.1")
+    port = int(os.environ.get("PARAVIEW_MCP_PORT", "9876"))
+    status = start_gui_bridge(host=host, port=port)
+    state = "already running" if status["already_running"] else "started"
+    print(f"ParaView MCP GUI bridge {state} on {status['host']}:{status['port']}")
+    print("Verify from a terminal with:")
+    print("  python scripts/paraview_bridge_request.py scene.get_info")
+    print("Stop from the ParaView Python Shell with:")
+    print("  stop_gui_bridge()")
+
+
+main()

paraview_mcp_python-0.1.2/tests/test_gui_bridge.py

@@ -0,0 +1,55 @@
+"""Tests for the ParaView GUI bridge lifecycle helpers."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from bridge import gui_bridge
+
+
+def teardown_function(_function):
+    gui_bridge.stop_gui_bridge()
+
+
+def test_start_gui_bridge_is_non_blocking_and_reports_status():
+    with patch("bridge.command_handler.CommandHandler", return_value=MagicMock()):
+        status = gui_bridge.start_gui_bridge(port=0)
+
+    assert status["running"] is True
+    assert status["already_running"] is False
+    assert status["host"] == "127.0.0.1"
+    assert status["port"] > 0
+    assert gui_bridge.gui_bridge_status() == {
+        "host": status["host"],
+        "port": status["port"],
+        "running": True,
+    }
+
+
+def test_start_gui_bridge_is_idempotent():
+    with patch("bridge.command_handler.CommandHandler", return_value=MagicMock()):
+        first = gui_bridge.start_gui_bridge(port=0)
+        second = gui_bridge.start_gui_bridge(port=0)
+
+    assert first["running"] is True
+    assert second == {
+        "host": first["host"],
+        "port": first["port"],
+        "running": True,
+        "already_running": True,
+    }
+
+
+def test_stop_gui_bridge_stops_running_server():
+    with patch("bridge.command_handler.CommandHandler", return_value=MagicMock()):
+        started = gui_bridge.start_gui_bridge(port=0)
+
+    stopped = gui_bridge.stop_gui_bridge()
+
+    assert stopped == {
+        "host": started["host"],
+        "port": started["port"],
+        "running": False,
+        "stopped": True,
+    }
+    assert gui_bridge.gui_bridge_status() == {"running": False}