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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paraview-mcp-python
-Version: 0.1.1
+Version: 0.1.3
 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`.
+
+```
+┌──────────────────────────────┐      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       │
+                                                   └────────────────────────┘
 ```
-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
+
+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
 ```
 
-- 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).
+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,117 @@ source .venv/bin/activate          # Windows: .venv\Scripts\activate
 pip install -e .
 ```
 
-### 2. Start the ParaView bridge
+This creates:
 
-In a terminal that has `pvpython` on `PATH`:
+```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
+```
+
+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:
+
+```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
+
+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 +257,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 +439,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 +489,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.3}/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`.
+
+```
+┌──────────────────────────────┐      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       │
+                                                   └────────────────────────┘
 ```
-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
+
+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
 ```
 
-- 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).
+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,117 @@ source .venv/bin/activate          # Windows: .venv\Scripts\activate
 pip install -e .
 ```
 
-### 2. Start the ParaView bridge
+This creates:
 
-In a terminal that has `pvpython` on `PATH`:
+```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
+```
+
+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:
+
+```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
+
+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 +224,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 +406,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 +456,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.3}/bridge/command_handler.py

@@ -8,6 +8,7 @@ is available.
 from __future__ import annotations
 
 import logging
+import os
 from typing import TYPE_CHECKING, Any
 
 from bridge.models import (
@@ -346,7 +347,8 @@ class CommandHandler:
             camera.SetViewUp(*params["view_up"])
         if "parallel_scale" in params:
             camera.SetParallelScale(params["parallel_scale"])
-        view.StillRender()
+        if os.environ.get("PARAVIEW_MCP_GUI_BRIDGE") != "1":
+            view.StillRender()
         pos = list(camera.GetPosition())
         fp = list(camera.GetFocalPoint())
         up = list(camera.GetViewUp())