diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml
index fc709e1..6c7098d 100644
--- a/.github/workflows/claude-code-review.yml
+++ b/.github/workflows/claude-code-review.yml
@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read
+      pull-requests: write
       issues: read
       id-token: write
 
@@ -35,7 +35,31 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Check workflow parity with default branch
+        id: workflow-parity
+        run: |
+          DEFAULT_BRANCH="${{ github.event.repository.default_branch }}"
+          git fetch --depth=1 origin "${DEFAULT_BRANCH}"
+
+          if ! git cat-file -e "origin/${DEFAULT_BRANCH}:.github/workflows/claude-code-review.yml" 2>/dev/null; then
+            echo "can_run=false" >> "${GITHUB_OUTPUT}"
+            exit 0
+          fi
+
+          if git diff --quiet "origin/${DEFAULT_BRANCH}" -- .github/workflows/claude-code-review.yml; then
+            echo "can_run=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "can_run=false" >> "${GITHUB_OUTPUT}"
+          fi
+
+      - name: Skip Claude Code Review
+        if: steps.workflow-parity.outputs.can_run != 'true'
+        run: |
+          echo "Skipping Claude Code Review because this workflow file differs from the default branch."
+          echo "The Claude action cannot exchange its app token unless the workflow file matches the default branch exactly."
+
       - name: Run Claude Code Review
+        if: steps.workflow-parity.outputs.can_run == 'true'
         id: claude-review
         uses: anthropics/claude-code-action@v1
         with:
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index a6a556e..0ac68d1 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -42,9 +42,8 @@ jobs:
           python-version: "3.11"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v2
+        uses: astral-sh/setup-uv@v6
         with:
-          version: "0.5.13"
           enable-cache: true
 
       - name: Install dependencies
@@ -96,9 +95,8 @@ jobs:
           python-version: "3.11"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v2
+        uses: astral-sh/setup-uv@v6
         with:
-          version: "0.5.13"
           enable-cache: true
 
       - name: Install dependencies
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c6124be..3bf98a7 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -36,7 +36,7 @@ jobs:
         python-version: "3.11"
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v4
+      uses: astral-sh/setup-uv@v6
       with:
         enable-cache: true
 
@@ -45,6 +45,19 @@ jobs:
         uv build
         ls -la dist/
 
+    - name: Validate version matches tag
+      if: contains(github.ref, 'tags')
+      run: |
+        WHEEL=$(ls dist/*.whl | head -1)
+        WHEEL_VERSION=$(echo "$WHEEL" | sed -n 's/.*-\([0-9][0-9.]*\)-.*/\1/p')
+        TAG_VERSION="${GITHUB_REF_NAME#v}"
+        echo "Wheel version: $WHEEL_VERSION"
+        echo "Tag version: $TAG_VERSION"
+        if [ "$WHEEL_VERSION" != "$TAG_VERSION" ]; then
+          echo "ERROR: Version mismatch! Wheel=$WHEEL_VERSION Tag=$TAG_VERSION"
+          exit 1
+        fi
+
     - name: Check build artifacts
       run: |
         uv pip install --system twine
@@ -52,7 +65,7 @@ jobs:
 
     - name: Create GitHub Release
       if: contains(github.ref, 'tags') && !inputs.dry_run
-      uses: softprops/action-gh-release@v1
+      uses: softprops/action-gh-release@v2
       with:
         files: dist/*
         generate_release_notes: true
@@ -72,5 +85,5 @@ jobs:
         echo "🔍 Dry run complete - artifacts built but not published"
         echo "Built artifacts:"
         ls -la dist/
-        echo "Version info:"
-        cat dist/*.whl | head -c 500
+        echo "Wheel contents:"
+        ls -lh dist/
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 6eee297..1673de2 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -41,7 +41,7 @@ jobs:
         python-version: "3.11"
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v4
+      uses: astral-sh/setup-uv@v6
       with:
         enable-cache: true
         cache-suffix: "smoke"
@@ -51,9 +51,9 @@ jobs:
 
     - name: Install dependencies
       run: |
-        uv sync --extra test
+        uv sync --group testing
 
-    - name: Test with tox
+    - name: Run smoke tests
       uses: aganders3/headless-gui@v1
       with:
         run: uv run pytest tests/test_tools.py::test_all_tools_end_to_end -v -x
@@ -88,7 +88,6 @@ jobs:
       with:
         path: |
           .pytest_cache
-          .coverage.*
         key: test-cache-${{ matrix.os }}-py${{ matrix.python-version }}-${{ hashFiles('tests/**/*.py') }}
         restore-keys: |
           test-cache-${{ matrix.os }}-py${{ matrix.python-version }}-
@@ -113,14 +112,13 @@ jobs:
 
     - name: Install dependencies
       run: |
-        uv sync --all-extras
-        uv pip install pytest-qt pytest-asyncio pytest-xdist pytest-timeout
+        uv sync --all-extras --group testing
 
-    - name: Test with tox
+    - name: Run full test suite
       uses: aganders3/headless-gui@v1
       with:
         run: |
-          uv run pytest tests/ --verbose --dist loadscope --cov=napari_mcp --cov-report=xml --cov-report=term-missing --cov-fail-under=65 --durations=20 --timeout=60
+          uv run pytest tests/ --verbose --cov=napari_mcp --cov-report=xml --cov-report=term-missing --cov-fail-under=80 --durations=20 --timeout=60
 
     - name: Upload coverage
       if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
@@ -160,7 +158,7 @@ jobs:
 
     - name: Install dependencies
       run: |
-        uv pip install --system ruff mypy types-Pillow bandit "safety<4.0"
+        uv pip install --system ruff mypy types-Pillow types-toml
 
     - name: Run quality checks
       run: |
@@ -173,18 +171,37 @@ jobs:
         echo "::endgroup::"
 
         echo "::group::Type Checking"
-        mypy src/napari_mcp/ --ignore-missing-imports || true
+        mypy src/napari_mcp/ --ignore-missing-imports
         echo "::endgroup::"
 
-        echo "::group::Security Scan"
-        bandit -r src/ --skip B110,B101,B102,B307 -f json || true
-        safety check || true
-        echo "::endgroup::"
+  # Advisory security scan (non-blocking)
+  security:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    continue-on-error: true
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install security tools
+      run: pip install bandit "safety<4.0"
+
+    - name: Bandit scan
+      continue-on-error: true
+      run: bandit -r src/ --skip B110,B101 -f json
+
+    - name: Safety check
+      continue-on-error: true
+      run: safety check
 
   # Final status check
   test-status:
     if: always()
-    needs: [smoke-tests, test-all-platforms, quality]
+    needs: [smoke-tests, test-all-platforms, quality, security]
     runs-on: ubuntu-latest
     steps:
     - name: Check test status
@@ -195,4 +212,7 @@ jobs:
           echo "Tests failed!"
           exit 1
         fi
+        if [[ "${{ needs.security.result }}" == "failure" ]]; then
+          echo "::warning::Security checks failed (advisory)"
+        fi
         echo "All tests passed!"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 76333aa..c300416 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,7 +19,7 @@ Thank you for your interest in contributing to napari-mcp! This document provide
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 
    # Install in development mode
-   uv pip install -e ".[test]"
+   uv pip install -e ".[dev]"
    ```
 
 3. **Install pre-commit hooks**
@@ -35,7 +35,7 @@ Thank you for your interest in contributing to napari-mcp! This document provide
 uv run pytest
 
 # Run with coverage
-uv run pytest --cov=napari_mcp_server --cov-report=html
+uv run pytest --cov=src --cov-report=html
 
 # Run only fast tests (no GUI)
 uv run pytest -m "not realgui"
@@ -56,7 +56,7 @@ ruff format src/ tests/
 ruff check src/ tests/ --fix
 
 # Type checking
-mypy src/napari_mcp_server.py --ignore-missing-imports
+mypy src/napari_mcp/ --ignore-missing-imports
 
 # Security scanning
 bandit -r src/
@@ -174,32 +174,41 @@ Brief description of the changes
 ### Specific Guidelines
 
 ```python
-# ✅ Good: Clear function signature with type hints
-async def add_image(
-    path: str,
-    name: Optional[str] = None,
-    colormap: Optional[str] = None
-) -> Dict[str, Any]:
-    """Add an image layer from a file path.
-
-    Args:
-        path: Path to an image readable by imageio
-        name: Optional layer name
-        colormap: Optional napari colormap name
-
-    Returns:
-        Dict with status, name, and shape information
+# ✅ Good: Clear function signature with type hints and NumPy docstrings
+async def add_layer(
+    layer_type: str,
+    path: str | None = None,
+    name: str | None = None,
+    colormap: str | None = None,
+) -> dict[str, Any]:
+    """Add a layer to the viewer.
+
+    Parameters
+    ----------
+    layer_type : str
+        One of: "image", "labels", "points", "shapes", etc.
+    path : str | None, optional
+        Path to an image readable by imageio.
+    name : str | None, optional
+        Layer name.
+    colormap : str | None, optional
+        Napari colormap name.
+
+    Returns
+    -------
+    dict[str, Any]
+        Dict with status, name, and shape information.
     """
 
 # ❌ Bad: No type hints, unclear parameters
-def add_image(path, name=None, colormap=None):
+def add_layer(type, path=None, name=None):
     # Does stuff
     return result
 ```
 
 ### Naming Conventions
 
-- **Functions**: `snake_case` (e.g., `add_image`, `set_layer_properties`)
+- **Functions**: `snake_case` (e.g., `add_layer`, `set_layer_properties`)
 - **Variables**: `snake_case` (e.g., `layer_name`, `current_zoom`)
 - **Constants**: `UPPER_CASE` (e.g., `DEFAULT_TIMEOUT`)
 - **Classes**: `PascalCase` (e.g., `LayerManager`)
@@ -211,10 +220,22 @@ def add_image(path, name=None, colormap=None):
 ```python
 """
 tests/
-├── test_tools.py          # Main tool functionality tests
-├── test_tools_real.py     # Real napari GUI tests (marked as 'realgui')
-├── test_coverage.py       # Edge cases and error conditions
-└── test_edge_cases.py     # Additional edge cases
+├── test_tools.py          # E2E smoke test, server factory, tool registration
+├── test_server_tools.py   # Tool-by-tool unit tests, AUTO_DETECT, invalid inputs
+├── test_integration.py    # Multi-step workflows and concurrent tool calls
+├── test_bridge_server.py  # Bridge server and QtBridge tests
+├── test_widget.py         # MCP control widget tests
+├── test_qt_helpers.py     # Qt helper functions (ensure_qt_app, process_events)
+├── test_state.py          # ServerState and ViewerProtocol tests
+├── test_output_storage.py # Output truncation and storage tests
+├── test_timelapse.py      # Timelapse screenshot tests
+├── test_performance.py    # Benchmarks and performance regression tests
+├── test_external_viewer.py# External viewer detection and proxy tests
+├── test_property_based.py # Hypothesis property-based tests
+├── test_base_installer.py # CLI installer base class tests
+├── test_cli_installer.py  # CLI install command tests
+├── test_cli_utils.py      # CLI utility function tests
+└── test_cli_installers/   # Platform-specific installer tests
 """
 ```
 
@@ -222,16 +243,18 @@ tests/
 
 ```python
 import pytest
-from napari_mcp_server import add_image
+from napari_mcp import server as napari_mcp_server
 
 @pytest.mark.asyncio
-async def test_add_image_success():
-    """Test successful image addition."""
+async def test_add_layer_success():
+    """Test successful layer addition."""
     # Arrange
     test_image_path = "test_data/sample.png"
 
     # Act
-    result = await add_image(test_image_path, name="test_image")
+    result = await napari_mcp_server.add_layer(
+        layer_type="image", path=test_image_path, name="test_image"
+    )
 
     # Assert
     assert result["status"] == "ok"
@@ -240,8 +263,8 @@ async def test_add_image_success():
 
 @pytest.mark.realgui
 @pytest.mark.asyncio
-async def test_add_image_real_gui():
-    """Test image addition with real napari GUI."""
+async def test_add_layer_real_gui():
+    """Test layer addition with real napari GUI."""
     # This test requires RUN_REAL_NAPARI_TESTS=1
     # and will be skipped in headless CI
 ```
diff --git a/MANIFEST.in b/MANIFEST.in
index 47123bd..48d7091 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,6 +1,5 @@
 include LICENSE
 include README.md
-include CHANGELOG.md
 include pyproject.toml
 
 recursive-include src/napari_mcp *.yaml
diff --git a/README.md b/README.md
index 9e6b73e..35cb4be 100644
--- a/README.md
+++ b/README.md
@@ -22,10 +22,13 @@ pip install napari-mcp
 
 ```bash
 # For Claude Desktop
-napari-mcp-install claude-desktop
+napari-mcp-install install claude-desktop
+
+# Include a napari GUI backend in the uv environment
+napari-mcp-install install claude-desktop --backend pyqt6
 
 # For other applications (Claude Code, Cursor, Cline, etc.)
-napari-mcp-install --help  # See all options
+napari-mcp-install install --help  # See all options
 ```
 
 ### 3. Restart Your Application & Start Using
@@ -44,7 +47,7 @@ napari-mcp can also be used as a **napari plugin** for direct integration with a
 1. **Start napari** normally: `napari`
 2. **Open the widget**: Plugins → napari-mcp: MCP Server Control
 3. **Click "Start Server"** to expose your current session to AI assistants
-4. **Connect your AI app** using the standard installer: `napari-mcp-install <app>`
+4. **Connect your AI app** using the standard installer: `napari-mcp-install install <app>`
 
 This mode enables AI assistants to control your **current napari session** rather than starting a new viewer. Perfect for integrating with existing workflows!
 
@@ -85,27 +88,25 @@ Want to automate image processing with Python scripts? Use any LLM (OpenAI, Anth
 
 | Application | Command | Status |
 |-------------|---------|--------|
-| **Claude Desktop** | `napari-mcp-install claude-desktop` | ✅ Full Support |
-| **Claude Code** | `napari-mcp-install claude-code` | ✅ Full Support |
-| **Cursor IDE** | `napari-mcp-install cursor` | ✅ Full Support |
-| **Cline (VS Code)** | `napari-mcp-install cline-vscode` | ✅ Full Support |
-| **Cline (Cursor)** | `napari-mcp-install cline-cursor` | ✅ Full Support |
-| **Gemini CLI** | `napari-mcp-install gemini` | ✅ Full Support |
-| **Codex CLI** | `napari-mcp-install codex` | ✅ Full Support |
+| **Claude Desktop** | `napari-mcp-install install claude-desktop` | ✅ Full Support |
+| **Claude Code** | `napari-mcp-install install claude-code` | ✅ Full Support |
+| **Cursor IDE** | `napari-mcp-install install cursor` | ✅ Full Support |
+| **Cline (VS Code)** | `napari-mcp-install install cline-vscode` | ✅ Full Support |
+| **Cline (Cursor)** | `napari-mcp-install install cline-cursor` | ✅ Full Support |
+| **Gemini CLI** | `napari-mcp-install install gemini` | ✅ Full Support |
+| **Codex CLI** | `napari-mcp-install install codex` | ✅ Full Support |
 
 **→ See [Integration Guides](docs/integrations/index.md) for application-specific instructions**
 
 ## 🛠 Available MCP Tools
 
-The server exposes 20+ tools for complete napari control:
+The server exposes 16 tools for complete napari control:
 
 ### Core Functions
-- **Session Management**: `detect_viewers`, `init_viewer`, `close_viewer`, `session_information`
-- **Layer Operations**: `add_image`, `add_labels`, `add_points`, `list_layers`, `remove_layer`
-- **Viewer Controls**: `set_camera`, `reset_view`, `set_ndisplay`, `set_dims_current_step`
-- **Utilities**: `screenshot`, `execute_code`, `install_packages`
-
-**→ See [API Reference](docs/api/index.md) for complete documentation**
+- **Session Management**: `init_viewer`, `close_viewer`, `session_information`
+- **Layer Operations**: `add_layer`, `list_layers`, `get_layer`, `remove_layer`, `set_layer_properties`, `reorder_layer`, `apply_to_layers`, `save_layer_data`
+- **Viewer Controls**: `configure_viewer`
+- **Utilities**: `screenshot`, `execute_code`, `install_packages`, `read_output`
 
 ## ⚠️ Security Notice
 
@@ -115,6 +116,9 @@ The server exposes 20+ tools for complete napari control:
     - **`execute_code()`** - Runs Python code in the server environment
     - **`install_packages()`** - Installs packages via pip
 
+    The bridge server binds to `127.0.0.1` (localhost only) with no authentication.
+    Any local process can invoke these tools.
+
     **Use only with trusted AI assistants on local networks.**
     Never expose to public internet without proper sandboxing.
 
@@ -125,7 +129,7 @@ The server exposes 20+ tools for complete napari control:
 - **[Integration Guides](docs/integrations/index.md)** - Setup for specific AI applications
 - **[Python Examples](docs/examples/README.md)** - Automate workflows with custom scripts
 - **[Troubleshooting](docs/guides/troubleshooting.md)** - Common issues and solutions
-- **[API Reference](docs/api/index.md)** - Complete tool documentation
+- **[API Reference](https://royerlab.github.io/napari-mcp/api/)** - Complete tool documentation
 
 ## 🧪 Development Setup
 
@@ -136,7 +140,7 @@ git clone https://github.com/royerlab/napari-mcp.git
 cd napari-mcp
 
 # Install with development dependencies
-pip install -e ".[test,dev]"
+pip install -e ".[dev]"
 
 # Run tests
 pytest -m "not realgui"  # Skip GUI tests
@@ -157,11 +161,13 @@ Contributions are welcome! Please:
 
 ## 📋 Architecture
 
-- **FastMCP Server**: Handles MCP protocol communication
-- **Napari Integration**: Manages viewer lifecycle and operations
-- **Qt Event Loop**: Asynchronous GUI event processing
-- **Tool Layer**: Exposes napari functionality as MCP tools
-- **External Bridge**: Optional connection to existing napari viewers
+- **`state.py`** — `ServerState` holding all mutable state (viewer, locks, execution namespace)
+- **`server.py`** — `create_server(state)` factory; tools defined as closures over state
+- **`qt_helpers.py`** — Qt application and viewer lifecycle management
+- **`output.py`** — Output truncation utility
+- **`bridge_server.py`** — Plugin bridge server (overrides 3 tools for Qt thread safety)
+- **`viewer_protocol.py`** — `ViewerProtocol` for typed viewer backends
+- **`cli/`** — `napari-mcp-install` CLI for configuring AI applications
 
 Key features:
 - **Thread-safe**: All napari operations are serialized
diff --git a/codecov.yml b/codecov.yml
index 9f1c118..d33cdde 100644
--- a/codecov.yml
+++ b/codecov.yml
@@ -3,12 +3,12 @@ coverage:
     project:
       default:
         target: auto  # Use base commit coverage as target
-        threshold: 10%  # Allow coverage to drop by up to 10%
+        threshold: 2%  # Allow coverage to drop by up to 2%
         if_ci_failed: error
     patch:
       default:
         target: auto  # Use base commit coverage as target for patches
-        threshold: 10%  # Allow patch coverage to drop by up to 10%
+        threshold: 2%  # Allow patch coverage to drop by up to 2%
         if_ci_failed: error
 
 comment:
diff --git a/docs/examples/README.md b/docs/examples/README.md
index 9df8d14..9bc00c0 100644
--- a/docs/examples/README.md
+++ b/docs/examples/README.md
@@ -19,7 +19,7 @@ export OPENAI_API_KEY="your-key-here"
 python openai_integration.py
 
 # Or with uv (zero-install)
-uv run --with openai --with mcp python openai_integration.py
+uv run --with napari-mcp --with openai --with mcp python openai_integration.py
 ```
 
 **What it does:**
@@ -45,7 +45,7 @@ export ANTHROPIC_API_KEY="your-key-here"
 python anthropic_integration.py
 
 # Or with uv (zero-install)
-uv run --with anthropic --with mcp python anthropic_integration.py
+uv run --with napari-mcp --with anthropic --with mcp python anthropic_integration.py
 ```
 
 **What it does:**
@@ -68,7 +68,7 @@ uv run --with anthropic --with mcp python anthropic_integration.py
 python direct_mcp_client.py
 
 # Or with uv
-uv run --with mcp python direct_mcp_client.py
+uv run --with napari-mcp --with mcp python direct_mcp_client.py
 ```
 
 **What it does:**
diff --git a/docs/examples/anthropic_integration.py b/docs/examples/anthropic_integration.py
index 8ea6d7e..89dc854 100644
--- a/docs/examples/anthropic_integration.py
+++ b/docs/examples/anthropic_integration.py
@@ -42,7 +42,7 @@ async def main():
 
             # Use Claude to interact with napari
             message = client.messages.create(
-                model="claude-3-5-sonnet-20241022",
+                model="claude-sonnet-4-6",
                 max_tokens=1024,
                 tools=tools,
                 messages=[
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
index cadcc79..c6b4570 100644
--- a/docs/getting-started/index.md
+++ b/docs/getting-started/index.md
@@ -31,7 +31,7 @@ Two simple ways to set up napari MCP:
 pip install napari-mcp
 
 # 2. Auto-configure your application
-napari-mcp-install claude-desktop  # or claude-code, cursor, etc.
+napari-mcp-install install claude-desktop  # or claude-code, cursor, etc.
 
 # 3. Restart application and start using!
 ```
@@ -67,14 +67,14 @@ The CLI installer supports:
 
 | Application | Command | Platform |
 |-------------|---------|----------|
-| **Claude Desktop** | `napari-mcp-install claude-desktop` | macOS, Windows, Linux |
-| **Claude Code** | `napari-mcp-install claude-code` | macOS, Windows, Linux |
-| **Cursor IDE** | `napari-mcp-install cursor` | macOS, Windows, Linux |
-| **Cline (VS Code)** | `napari-mcp-install cline-vscode` | macOS, Windows, Linux |
-| **Cline (Cursor)** | `napari-mcp-install cline-cursor` | macOS, Windows, Linux |
-| **Gemini CLI** | `napari-mcp-install gemini` | macOS, Windows, Linux |
-| **Codex CLI** | `napari-mcp-install codex` | macOS, Windows, Linux |
-| **All** | `napari-mcp-install all` | Install for all apps |
+| **Claude Desktop** | `napari-mcp-install install claude-desktop` | macOS, Windows, Linux |
+| **Claude Code** | `napari-mcp-install install claude-code` | macOS, Windows, Linux |
+| **Cursor IDE** | `napari-mcp-install install cursor` | macOS, Windows, Linux |
+| **Cline (VS Code)** | `napari-mcp-install install cline-vscode` | macOS, Windows, Linux |
+| **Cline (Cursor)** | `napari-mcp-install install cline-cursor` | macOS, Windows, Linux |
+| **Gemini CLI** | `napari-mcp-install install gemini` | macOS, Windows, Linux |
+| **Codex CLI** | `napari-mcp-install install codex` | macOS, Windows, Linux |
+| **All** | `napari-mcp-install install all` | Install for all apps |
 
 **→ See [Integration Guides](../integrations/index.md) for app-specific details**
 
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 887d886..21f3406 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -11,7 +11,7 @@ The easiest way is using the automated installer:
 
 ```bash
 pip install napari-mcp
-napari-mcp-install <application>
+napari-mcp-install install <application>
 ```
 
 **→ See [Quick Start](quickstart.md) for step-by-step instructions**
@@ -152,9 +152,15 @@ Run napari MCP without permanent installation using `uv`:
 ```bash
 # Direct execution (for testing)
 uv run --with napari-mcp napari-mcp
+
+# Add a napari GUI backend when needed
+uv run --with napari-mcp --with napari[pyqt6] napari-mcp
 ```
 
-The configuration files use `uv` automatically. See **[Zero Install Guide](zero-install.md)** for details.
+The configuration files use `uv` automatically. You can also ask `napari-mcp-install`
+to include a backend with `--backend all`, `--backend pyqt5`, `--backend pyqt6`,
+`--backend pyside`, `--backend none`, or a custom value.
+See **[Zero Install Guide](zero-install.md)** for details.
 
 ---
 
@@ -170,17 +176,17 @@ git clone https://github.com/royerlab/napari-mcp.git
 cd napari-mcp
 
 # Install in editable mode with dev dependencies
-pip install -e ".[test,dev]"
+pip install -e ".[dev]"
 
 # Or with uv (recommended)
-uv pip install -e ".[test,dev]"
+uv pip install -e ".[dev]"
 ```
 
 ### Configure for Development
 
 ```bash
 # Configure to use your development installation
-napari-mcp-install claude-desktop --persistent
+napari-mcp-install install claude-desktop --persistent
 
 # This will use your local Python with the editable installation
 ```
@@ -231,7 +237,7 @@ napari-mcp-env\Scripts\activate
 pip install napari-mcp
 
 # Configure
-napari-mcp-install <app> --persistent
+napari-mcp-install install <app> --persistent
 ```
 
 ### Using conda
@@ -247,7 +253,7 @@ conda activate napari-mcp
 pip install napari-mcp
 
 # Configure
-napari-mcp-install <app> --persistent
+napari-mcp-install install <app> --persistent
 ```
 
 ---
@@ -278,7 +284,7 @@ napari-mcp can also be used as a **napari plugin** for direct integration with a
 
 4. **Configure your AI app**:
    ```bash
-   napari-mcp-install <app>
+   napari-mcp-install install <app>
    ```
    The installer auto-configures to detect your bridge server.
 
@@ -380,7 +386,7 @@ napari-mcp-install list
 python -m json.tool < config-file.json
 
 # Force reinstall
-napari-mcp-install <app> --force
+napari-mcp-install install <app> --force
 ```
 
 ### Python Environment Issues
@@ -393,7 +399,7 @@ python --version  # Should be 3.10+
 python -c "import napari_mcp; print('OK')"
 
 # Use specific Python
-napari-mcp-install <app> --python-path $(which python)
+napari-mcp-install install <app> --python-path $(which python)
 ```
 
 **→ See [Troubleshooting Guide](../guides/troubleshooting.md) for comprehensive help**
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 69fe913..d7264a8 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -28,20 +28,20 @@ The CLI installer automatically configures your AI application with the correct
 ### For Claude Desktop
 
 ```bash
-napari-mcp-install claude-desktop
+napari-mcp-install install claude-desktop
 ```
 
 ### For Other Applications
 
 ```bash
 # Claude Code CLI
-napari-mcp-install claude-code
+napari-mcp-install install claude-code
 
 # Cursor IDE
-napari-mcp-install cursor
+napari-mcp-install install cursor
 
 # Cline in VS Code
-napari-mcp-install cline-vscode
+napari-mcp-install install cline-vscode
 
 # See all options
 napari-mcp-install --help
@@ -58,13 +58,13 @@ napari-mcp-install --help
 
 ```bash
 # Preview changes without applying
-napari-mcp-install claude-desktop --dry-run
+napari-mcp-install install claude-desktop --dry-run
 
 # Use your Python environment instead of uv
-napari-mcp-install claude-desktop --persistent
+napari-mcp-install install claude-desktop --persistent
 
 # Install for all supported applications at once
-napari-mcp-install all
+napari-mcp-install install all
 ```
 
 ## Step 3: Restart & Test (30 seconds)
@@ -181,7 +181,7 @@ If you want to use an existing Python environment instead of uv:
 pip install napari-mcp
 
 # Configure to use your Python
-napari-mcp-install claude-desktop --persistent
+napari-mcp-install install claude-desktop --persistent
 ```
 
 This will use your Python interpreter directly: `python -m napari_mcp.server`
diff --git a/docs/getting-started/zero-install.md b/docs/getting-started/zero-install.md
index 425094d..7206eb6 100644
--- a/docs/getting-started/zero-install.md
+++ b/docs/getting-started/zero-install.md
@@ -40,7 +40,7 @@ The CLI installer handles everything:
 pip install napari-mcp
 
 # Auto-configure your application
-napari-mcp-install claude-desktop  # or claude-code, cursor, etc.
+napari-mcp-install install claude-desktop  # or claude-code, cursor, etc.
 ```
 
 This creates a configuration file with:
@@ -167,7 +167,7 @@ The CLI installer supports both zero-install and persistent modes:
 ### Zero Install (Default)
 
 ```bash
-napari-mcp-install claude-desktop
+napari-mcp-install install claude-desktop
 ```
 
 Creates configuration using `uv run` (zero-install mode).
@@ -179,7 +179,7 @@ Creates configuration using `uv run` (zero-install mode).
 pip install napari-mcp
 
 # Then configure with persistent mode
-napari-mcp-install claude-desktop --persistent
+napari-mcp-install install claude-desktop --persistent
 ```
 
 This uses your Python environment instead of uv:
@@ -280,7 +280,7 @@ uv run --with napari-mcp --with napari --help
     3. Use persistent mode instead:
        ```bash
        pip install napari-mcp
-       napari-mcp-install <app> --persistent
+       napari-mcp-install install <app> --persistent
        ```
 
 ### Cache Issues
@@ -303,13 +303,13 @@ uv run --with napari-mcp --with napari --help
 napari-mcp-install list
 
 # Switch to zero-install mode
-napari-mcp-install <app>
+napari-mcp-install install <app>
 
 # Switch to persistent mode
-napari-mcp-install <app> --persistent
+napari-mcp-install install <app> --persistent
 
 # Preview changes
-napari-mcp-install <app> --dry-run
+napari-mcp-install install <app> --dry-run
 ```
 
 ---
diff --git a/docs/guides/napari-plugin.md b/docs/guides/napari-plugin.md
index 6cbba6f..7585941 100644
--- a/docs/guides/napari-plugin.md
+++ b/docs/guides/napari-plugin.md
@@ -98,12 +98,12 @@ Run the standard installer:
 
 ```bash
 # For Claude Desktop
-napari-mcp-install claude-desktop
+napari-mcp-install install claude-desktop
 
 # For other applications
-napari-mcp-install claude-code    # Claude Code
-napari-mcp-install cursor         # Cursor IDE
-napari-mcp-install cline-vscode   # Cline in VS Code
+napari-mcp-install install claude-code    # Claude Code
+napari-mcp-install install cursor         # Cursor IDE
+napari-mcp-install install cline-vscode   # Cline in VS Code
 ```
 
 The installer automatically configures the AI app to detect and connect to your bridge server.
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index e0a2f2d..bd61bcc 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -46,7 +46,7 @@ The `napari-mcp-install` CLI tool automates configuration. Here are common issue
     **Solutions:**
     1. **Check what would be created:**
        ```bash
-       napari-mcp-install <app> --dry-run
+       napari-mcp-install install <app> --dry-run
        ```
 
     2. **Verify installer detected correct path:**
@@ -72,7 +72,7 @@ The `napari-mcp-install` CLI tool automates configuration. Here are common issue
        mkdir -p ~/.config/Claude
 
        # Then retry
-       napari-mcp-install claude-desktop
+       napari-mcp-install install claude-desktop
        ```
 
 !!! failure "Config exists but server not configured"
@@ -84,7 +84,7 @@ The `napari-mcp-install` CLI tool automates configuration. Here are common issue
     napari-mcp-install list
 
     # Force reinstall
-    napari-mcp-install <app> --force
+    napari-mcp-install install <app> --force
 
     # Or manually check/edit config
     cat ~/.config/Claude/claude_desktop_config.json
@@ -122,10 +122,10 @@ The `napari-mcp-install` CLI tool automates configuration. Here are common issue
     pip install napari-mcp
 
     # Then configure
-    napari-mcp-install <app> --persistent
+    napari-mcp-install install <app> --persistent
 
     # Or specify exact Python path
-    napari-mcp-install <app> --python-path /full/path/to/python
+    napari-mcp-install install <app> --python-path /full/path/to/python
     ```
 
 ### Verification Commands
@@ -135,14 +135,14 @@ The `napari-mcp-install` CLI tool automates configuration. Here are common issue
 napari-mcp-install list
 
 # Preview what would be installed
-napari-mcp-install <app> --dry-run
+napari-mcp-install install <app> --dry-run
 
 # Check installer version
 napari-mcp-install --version
 
 # Get help
 napari-mcp-install --help
-napari-mcp-install <command> --help
+napari-mcp-install install --help
 ```
 
 ---
@@ -172,7 +172,7 @@ napari-mcp-install <command> --help
     pip install -e . --force-reinstall
 
     # Or use Python module directly
-    python -m napari_mcp_server
+    python -m napari_mcp.server
 
     # Check if it's in your PATH
     which napari-mcp
@@ -183,11 +183,11 @@ napari-mcp-install <command> --help
 
     **Solution:**
     ```bash
-    # Make file executable
-    chmod +x napari_mcp_server.py
+    # Reinstall the package
+    pip install --force-reinstall napari-mcp
 
-    # Or run with Python directly
-    python napari_mcp_server.py
+    # Or run with Python module directly
+    python -m napari_mcp.server
     ```
 
 ### Napari GUI Issues
@@ -216,7 +216,7 @@ napari-mcp-install <command> --help
     echo $DISPLAY
 
     # Test basic Qt
-    python -c "from PyQt6.QtWidgets import QApplication; app = QApplication([]); print('Qt works')"
+    python -c "from qtpy.QtWidgets import QApplication; app = QApplication([]); print('Qt works')"
 
     # Test napari
     python -c "import napari; viewer = napari.Viewer(); print('Napari works')"
@@ -263,11 +263,11 @@ napari-mcp-install <command> --help
 
     3. **File paths absolute?**
        ```json
-       // Wrong - relative path
-       "args": ["fastmcp", "run", "napari_mcp_server.py"]
+       // Wrong - missing package specifier
+       "args": ["run", "napari-mcp"]
 
-       // Correct - absolute path
-       "args": ["fastmcp", "run", "/full/path/to/napari_mcp_server.py"]
+       // Correct - full uv invocation
+       "args": ["run", "--with", "napari-mcp", "napari-mcp"]
        ```
 
     4. **Claude Desktop restarted?**
@@ -280,31 +280,30 @@ napari-mcp-install <command> --help
     **Debug steps:**
     ```bash
     # Test server starts manually
-    uv run --with fastmcp fastmcp run napari_mcp_server.py
+    napari-mcp
 
-    # Check for error messages
-    # Look for FastMCP startup banner
+    # Or via uv
+    uv run --with napari-mcp napari-mcp
 
-    # Test MCP protocol
-    echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}' | \
-      uv run --with fastmcp fastmcp run napari_mcp_server.py
+    # Check for error messages in verbose mode
+    MCP_LOG_LEVEL=DEBUG napari-mcp
     ```
 
 ### Cursor & Claude Code
 
-!!! failure "FastMCP CLI installation failed"
-    **Problem:** `fastmcp install` command fails.
+!!! failure "CLI installer failed"
+    **Problem:** `napari-mcp-install` command fails.
 
     **Solutions:**
     ```bash
-    # Update fastmcp
-    pip install --upgrade fastmcp
+    # Reinstall napari-mcp
+    pip install --upgrade napari-mcp
 
     # Check installation
-    fastmcp --version
+    napari-mcp-install --version
 
-    # Manual installation
-    fastmcp install cursor napari_mcp_server.py --with napari --with imageio
+    # Manual installation for a specific app
+    napari-mcp-install install cursor
     ```
 
 !!! failure "Server not appearing in IDE"
@@ -312,12 +311,11 @@ napari-mcp-install <command> --help
 
     **Debug:**
     ```bash
-    # Check installation location
-    fastmcp list
+    # Check current installations
+    napari-mcp-install list
 
-    # Reinstall for specific IDE
-    fastmcp uninstall cursor napari
-    fastmcp install cursor napari_mcp_server.py --with napari
+    # Force reinstall for specific IDE
+    napari-mcp-install install cursor --force
     ```
 
 ## 📦 Dependency Issues
@@ -334,9 +332,8 @@ napari-mcp-install <command> --help
     source fresh-env/bin/activate
     pip install -e .
 
-    # Or specify versions
-    uv run --with "napari>=0.5.5" --with "PyQt6>=6.5.0" \
-      fastmcp run napari_mcp_server.py
+    # Or use uv with specific versions
+    uv run --with "napari>=0.5.5" --with "PyQt6>=6.5.0" --with napari-mcp napari-mcp
     ```
 
 !!! failure "Qt backend conflicts"
@@ -393,7 +390,7 @@ napari-mcp-install <command> --help
     napari-mcp  # Faster than uv run
 
     # Check startup time
-    time uv run --with napari fastmcp run napari_mcp_server.py
+    time uv run --with napari-mcp napari-mcp
     ```
 
 ### Memory Issues
@@ -407,7 +404,7 @@ napari-mcp-install <command> --help
     ps aux | grep napari
 
     # Python memory profiling
-    python -m memory_profiler napari_mcp_server.py
+    python -m memory_profiler -m napari_mcp.server
     ```
 
     **Solutions:**
@@ -425,8 +422,9 @@ napari-mcp-install <command> --help
 
     **Solution:**
     ```bash
-    # Remove quarantine attribute
-    xattr -d com.apple.quarantine napari_mcp_server.py
+    # If installed via pip, this shouldn't occur.
+    # For uv-cached files, try:
+    pip install --force-reinstall napari-mcp
 
     # Or allow in System Preferences > Security & Privacy
     ```
@@ -454,7 +452,7 @@ napari-mcp-install <command> --help
     Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
     # Or run directly
-    python napari_mcp_server.py
+    python -m napari_mcp.server
     ```
 
 !!! failure "Path length limitations"
@@ -474,7 +472,7 @@ napari-mcp-install <command> --help
     ```bash
     # Virtual display
     sudo apt-get install xvfb
-    xvfb-run -a python napari_mcp_server.py
+    xvfb-run -a napari-mcp
 
     # Or use offscreen
     export QT_QPA_PLATFORM=offscreen
@@ -487,13 +485,12 @@ napari-mcp-install <command> --help
 ```bash
 # Enable verbose logging
 export MCP_LOG_LEVEL=DEBUG
-export NAPARI_ASYNC=1
 
-# Python debugging
-python -u napari_mcp_server.py  # Unbuffered output
+# Run with debug output
+napari-mcp
 
-# FastMCP debugging
-fastmcp run --debug napari_mcp_server.py
+# Or via Python module directly
+python -u -m napari_mcp.server  # Unbuffered output
 ```
 
 ### Testing Commands
@@ -506,7 +503,7 @@ python -c "import napari; print('✅ napari works')"
 python -c "import fastmcp; print('✅ FastMCP works')"
 
 # Test Qt
-python -c "from PyQt6.QtWidgets import QApplication; app = QApplication([]); print('✅ Qt works')"
+python -c "from qtpy.QtWidgets import QApplication; app = QApplication([]); print('✅ Qt works')"
 
 # Full integration test
 python -c "
diff --git a/docs/index.md b/docs/index.md
index 0d2ba74..445ee07 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -55,12 +55,12 @@ pip install napari-mcp
 
 ```bash
 # For Claude Desktop
-napari-mcp-install claude-desktop
+napari-mcp-install install claude-desktop
 
 # For other applications
-napari-mcp-install claude-code    # Claude Code CLI
-napari-mcp-install cursor         # Cursor IDE
-napari-mcp-install cline-vscode   # Cline in VS Code
+napari-mcp-install install claude-code    # Claude Code CLI
+napari-mcp-install install cursor         # Cursor IDE
+napari-mcp-install install cline-vscode   # Cline in VS Code
 napari-mcp-install --help         # See all options
 ```
 
@@ -99,15 +99,14 @@ Restart your AI application and try:
 
 ## 🛠️ Available Tools
 
-The server exposes 20+ MCP tools for complete napari control:
+The server exposes 16 MCP tools for complete napari control:
 
 | Category | Tools | Description |
 |----------|-------|-------------|
-| **Session** | `detect_viewers`, `init_viewer`, `close_viewer`, `session_information` | Viewer lifecycle management |
-| **Layers** | `add_image`, `add_labels`, `add_points`, `list_layers` | Layer creation and management |
-| **Properties** | `set_layer_properties`, `reorder_layer`, `set_active_layer` | Layer customization |
-| **Navigation** | `set_camera`, `reset_view`, `set_ndisplay`, `set_dims_current_step` | Viewer navigation |
-| **Utilities** | `screenshot`, `timelapse_screenshot`, `execute_code`, `install_packages` | Advanced functionality |
+| **Session** | `init_viewer`, `close_viewer`, `session_information` | Viewer lifecycle management |
+| **Layers** | `add_layer`, `list_layers`, `get_layer`, `remove_layer`, `set_layer_properties`, `reorder_layer`, `apply_to_layers`, `save_layer_data` | Layer CRUD and batch ops |
+| **Navigation** | `configure_viewer` | Camera, dims, grid, display modes |
+| **Utilities** | `screenshot`, `execute_code`, `install_packages`, `read_output` | Screenshots, code, packages |
 
 **→ See the [API Reference](api/index.md) for complete documentation**
 
@@ -117,13 +116,13 @@ The server exposes 20+ MCP tools for complete napari control:
 
 | Application | Command | Status |
 |-------------|---------|--------|
-| **Claude Desktop** | `napari-mcp-install claude-desktop` | ✅ Full Support |
-| **Claude Code** | `napari-mcp-install claude-code` | ✅ Full Support |
-| **Cursor IDE** | `napari-mcp-install cursor` | ✅ Full Support |
-| **Cline (VS Code)** | `napari-mcp-install cline-vscode` | ✅ Full Support |
-| **Cline (Cursor)** | `napari-mcp-install cline-cursor` | ✅ Full Support |
-| **Gemini CLI** | `napari-mcp-install gemini` | ✅ Full Support |
-| **Codex CLI** | `napari-mcp-install codex` | ✅ Full Support |
+| **Claude Desktop** | `napari-mcp-install install claude-desktop` | ✅ Full Support |
+| **Claude Code** | `napari-mcp-install install claude-code` | ✅ Full Support |
+| **Cursor IDE** | `napari-mcp-install install cursor` | ✅ Full Support |
+| **Cline (VS Code)** | `napari-mcp-install install cline-vscode` | ✅ Full Support |
+| **Cline (Cursor)** | `napari-mcp-install install cline-cursor` | ✅ Full Support |
+| **Gemini CLI** | `napari-mcp-install install gemini` | ✅ Full Support |
+| **Codex CLI** | `napari-mcp-install install codex` | ✅ Full Support |
 
 **→ See [Integration Guides](integrations/index.md) for application-specific setup**
 
@@ -176,7 +175,7 @@ The server exposes 20+ MCP tools for complete napari control:
 ## 🎉 Ready to Start?
 
 1. **Install the package** - `pip install napari-mcp`
-2. **Configure your AI app** - `napari-mcp-install <app-name>`
+2. **Configure your AI app** - `napari-mcp-install install <app-name>`
 3. **Start exploring** - Load images, analyze data, take screenshots
 4. **Share your workflows** - Document and reproduce your analysis
 
diff --git a/docs/integrations/chatgpt.md b/docs/integrations/chatgpt.md
index 3e12c00..d97fc9d 100644
--- a/docs/integrations/chatgpt.md
+++ b/docs/integrations/chatgpt.md
@@ -28,7 +28,7 @@ OpenAI's Codex CLI **does support MCP** and works with napari-mcp:
 
 ```bash
 pip install napari-mcp
-napari-mcp-install codex
+napari-mcp-install install codex
 ```
 
 **→ See [Other LLMs Guide](other-llms.md#codex-cli) for setup instructions**
@@ -39,7 +39,7 @@ Cursor IDE supports MCP and uses OpenAI models under the hood:
 
 ```bash
 pip install napari-mcp
-napari-mcp-install cursor --global
+napari-mcp-install install cursor --global
 ```
 
 **→ See [Cursor Integration Guide](cursor.md) for complete setup**
@@ -50,7 +50,7 @@ While not OpenAI, Claude Desktop has excellent MCP support and is the most popul
 
 ```bash
 pip install napari-mcp
-napari-mcp-install claude-desktop
+napari-mcp-install install claude-desktop
 ```
 
 **→ See [Claude Desktop Integration Guide](claude-desktop.md) for setup**
@@ -125,7 +125,7 @@ Choose one of the supported options:
 pip install napari-mcp
 
 # 2. Configure Codex CLI
-napari-mcp-install codex
+napari-mcp-install install codex
 
 # 3. Use with Codex
 # (Codex will now have access to napari MCP tools)
@@ -138,7 +138,7 @@ napari-mcp-install codex
 pip install napari-mcp
 
 # 2. Configure Cursor
-napari-mcp-install cursor --global
+napari-mcp-install install cursor --global
 
 # 3. Open Cursor IDE
 # (Cursor AI will now have napari MCP access)
@@ -151,7 +151,7 @@ napari-mcp-install cursor --global
 pip install napari-mcp
 
 # 2. Configure Claude Desktop
-napari-mcp-install claude-desktop
+napari-mcp-install install claude-desktop
 
 # 3. Restart Claude Desktop
 # (Claude will now have napari MCP access)
diff --git a/docs/integrations/claude-code.md b/docs/integrations/claude-code.md
index f7505b1..8ca91a8 100644
--- a/docs/integrations/claude-code.md
+++ b/docs/integrations/claude-code.md
@@ -9,7 +9,7 @@ Setup guide for using napari MCP server with Claude Code - perfect for developme
 pip install napari-mcp
 
 # 2. Auto-configure Claude Code
-napari-mcp-install claude-code
+napari-mcp-install install claude-code
 
 # 3. Restart Claude Code (if running)
 ```
@@ -102,7 +102,7 @@ If needed, manually edit `~/.claude.json`:
 napari-mcp-install list
 
 # Update configuration
-napari-mcp-install claude-code --force
+napari-mcp-install install claude-code --force
 
 # Uninstall
 napari-mcp-install uninstall claude-code
@@ -127,7 +127,7 @@ napari-mcp-install uninstall claude-code
 
     3. Reinstall:
        ```bash
-       napari-mcp-install claude-code --force
+       napari-mcp-install install claude-code --force
        ```
 
 ### Environment Issues
@@ -143,7 +143,7 @@ napari-mcp-install uninstall claude-code
     pip install napari-mcp
 
     # Configure with persistent mode
-    napari-mcp-install claude-code --persistent
+    napari-mcp-install install claude-code --persistent
     ```
 
 ## 📚 Next Steps
diff --git a/docs/integrations/claude-desktop.md b/docs/integrations/claude-desktop.md
index d49b4d0..32bff60 100644
--- a/docs/integrations/claude-desktop.md
+++ b/docs/integrations/claude-desktop.md
@@ -11,7 +11,7 @@ Complete setup guide for using napari MCP server with Claude Desktop - the most
 pip install napari-mcp
 
 # 2. Auto-configure Claude Desktop
-napari-mcp-install claude-desktop
+napari-mcp-install install claude-desktop
 
 # 3. Restart Claude Desktop
 ```
@@ -31,23 +31,23 @@ The installer automatically detects your platform and configures:
 ### Basic Installation
 
 ```bash
-napari-mcp-install claude-desktop
+napari-mcp-install install claude-desktop
 ```
 
 ### Advanced Options
 
 ```bash
 # Preview changes without applying
-napari-mcp-install claude-desktop --dry-run
+napari-mcp-install install claude-desktop --dry-run
 
 # Use your Python environment instead of uv
-napari-mcp-install claude-desktop --persistent
+napari-mcp-install install claude-desktop --persistent
 
 # Custom Python path
-napari-mcp-install claude-desktop --python-path /path/to/python
+napari-mcp-install install claude-desktop --python-path /path/to/python
 
 # Force update without prompts
-napari-mcp-install claude-desktop --force
+napari-mcp-install install claude-desktop --force
 ```
 
 ## 🧪 Testing the Integration
@@ -173,7 +173,7 @@ napari-mcp-install list
 ### Update Configuration
 
 ```bash
-napari-mcp-install claude-desktop --force
+napari-mcp-install install claude-desktop --force
 ```
 
 ### Uninstall
@@ -209,7 +209,7 @@ napari-mcp-install uninstall claude-desktop
 
     4. **Reinstall:**
        ```bash
-       napari-mcp-install claude-desktop --force
+       napari-mcp-install install claude-desktop --force
        ```
 
 ### Napari Window Doesn't Appear
diff --git a/docs/integrations/cline.md b/docs/integrations/cline.md
index fb4db5f..acca725 100644
--- a/docs/integrations/cline.md
+++ b/docs/integrations/cline.md
@@ -11,7 +11,7 @@ Setup guide for using napari MCP server with Cline - the powerful AI coding assi
 pip install napari-mcp
 
 # 2. Auto-configure Cline in VS Code
-napari-mcp-install cline-vscode
+napari-mcp-install install cline-vscode
 
 # 3. Restart VS Code (or reload window)
 ```
@@ -23,7 +23,7 @@ napari-mcp-install cline-vscode
 pip install napari-mcp
 
 # 2. Auto-configure Cline in Cursor
-napari-mcp-install cline-cursor
+napari-mcp-install install cline-cursor
 
 # 3. Restart Cursor
 ```
@@ -141,7 +141,7 @@ You can pre-approve specific tools to skip confirmation prompts:
     "napari-mcp": {
       "command": "python",
       "args": ["-m", "napari_mcp.server"],
-      "always Allow": [],
+      "alwaysAllow": [],
       "disabled": false
     }
   }
@@ -171,10 +171,10 @@ Cline supports configuring which tools can be called without confirmation:
 napari-mcp-install list
 
 # Update VS Code configuration
-napari-mcp-install cline-vscode --force
+napari-mcp-install install cline-vscode --force
 
 # Update Cursor configuration
-napari-mcp-install cline-cursor --force
+napari-mcp-install install cline-cursor --force
 
 # Uninstall
 napari-mcp-install uninstall cline-vscode
@@ -208,9 +208,9 @@ napari-mcp-install uninstall cline-cursor
 
     5. **Reinstall:**
        ```bash
-       napari-mcp-install cline-vscode --force
+       napari-mcp-install install cline-vscode --force
        # or
-       napari-mcp-install cline-cursor --force
+       napari-mcp-install install cline-cursor --force
        ```
 
 ### Wrong IDE Detected
@@ -225,7 +225,7 @@ napari-mcp-install uninstall cline-cursor
     napari-mcp-install uninstall cline-vscode
 
     # Install correct one
-    napari-mcp-install cline-cursor
+    napari-mcp-install install cline-cursor
     ```
 
 ### VS Code Insiders
diff --git a/docs/integrations/cursor.md b/docs/integrations/cursor.md
index 7ece2ce..6b7d317 100644
--- a/docs/integrations/cursor.md
+++ b/docs/integrations/cursor.md
@@ -9,10 +9,10 @@ Setup guide for using napari MCP server with Cursor - AI-powered coding with ful
 pip install napari-mcp
 
 # 2. Auto-configure Cursor (global)
-napari-mcp-install cursor --global
+napari-mcp-install install cursor --global
 
 # OR configure for specific project
-napari-mcp-install cursor --project /path/to/project
+napari-mcp-install install cursor --project /path/to/project
 
 # 3. Restart Cursor
 ```
@@ -89,7 +89,7 @@ Take screenshots at each processing step for my documentation
 Best for most users:
 
 ```bash
-napari-mcp-install cursor --global
+napari-mcp-install install cursor --global
 ```
 
 Creates: `~/.cursor/mcp.json`
@@ -100,7 +100,7 @@ For project-specific setups:
 
 ```bash
 cd /path/to/your/project
-napari-mcp-install cursor --project .
+napari-mcp-install install cursor --project .
 ```
 
 Creates: `.cursor/mcp.json` in project directory
@@ -140,10 +140,10 @@ Edit the appropriate config file:
 napari-mcp-install list
 
 # Update global configuration
-napari-mcp-install cursor --global --force
+napari-mcp-install install cursor --global --force
 
 # Update project configuration
-napari-mcp-install cursor --project . --force
+napari-mcp-install install cursor --project . --force
 
 # Uninstall
 napari-mcp-install uninstall cursor
@@ -171,7 +171,7 @@ napari-mcp-install uninstall cursor
 
     4. **Reinstall:**
        ```bash
-       napari-mcp-install cursor --global --force
+       napari-mcp-install install cursor --global --force
        ```
 
 ### Project vs Global Confusion
@@ -183,14 +183,14 @@ napari-mcp-install uninstall cursor
 
     - **Use global for all projects:**
       ```bash
-      napari-mcp-install cursor --global
+      napari-mcp-install install cursor --global
       # Remove project configs
       rm .cursor/mcp.json
       ```
 
     - **Use project-specific for this project:**
       ```bash
-      napari-mcp-install cursor --project .
+      napari-mcp-install install cursor --project .
       ```
 
 ### Configuration File Not Found
diff --git a/docs/integrations/index.md b/docs/integrations/index.md
index b56dfd6..7974231 100644
--- a/docs/integrations/index.md
+++ b/docs/integrations/index.md
@@ -11,18 +11,18 @@ All integrations use the same simple command:
 pip install napari-mcp
 
 # Auto-configure your application
-napari-mcp-install <application-name>
+napari-mcp-install install <application-name>
 ```
 
 ## Supported Platforms
 
 | Platform | Command | Status | Guide |
 |----------|---------|--------|-------|
-| **Claude Desktop** | `napari-mcp-install claude-desktop` | ✅ Full Support | [Setup →](claude-desktop.md) |
-| **Claude Code** | `napari-mcp-install claude-code` | ✅ Full Support | [Setup →](claude-code.md) |
-| **Cursor IDE** | `napari-mcp-install cursor` | ✅ Full Support | [Setup →](cursor.md) |
-| **Cline** | `napari-mcp-install cline-vscode` or `cline-cursor` | ✅ Full Support | [Setup →](cline.md) |
-| **Gemini / Codex** | `napari-mcp-install gemini` or `codex` | ✅ Full Support | [Setup →](other-llms.md) |
+| **Claude Desktop** | `napari-mcp-install install claude-desktop` | ✅ Full Support | [Setup →](claude-desktop.md) |
+| **Claude Code** | `napari-mcp-install install claude-code` | ✅ Full Support | [Setup →](claude-code.md) |
+| **Cursor IDE** | `napari-mcp-install install cursor` | ✅ Full Support | [Setup →](cursor.md) |
+| **Cline** | `napari-mcp-install install cline-vscode` or `cline-cursor` | ✅ Full Support | [Setup →](cline.md) |
+| **Gemini / Codex** | `napari-mcp-install install gemini` or `codex` | ✅ Full Support | [Setup →](other-llms.md) |
 | **Python** | Custom script | ✅ Full Support | [Guide →](python.md) |
 | **ChatGPT** | N/A | ❌ Not Supported | [Why? →](chatgpt.md) |
 
@@ -31,7 +31,7 @@ napari-mcp-install <application-name>
 | Feature | Claude Desktop | Claude Code | Cursor | Cline | Gemini/Codex |
 |---------|----------------|-------------|--------|-------|--------------|
 | **Visual napari window** | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
-| **All MCP tools** | ✅ 20+ tools | ✅ 20+ tools | ✅ 20+ tools | ✅ 20+ tools | ✅ 20+ tools |
+| **All MCP tools** | ✅ 16 tools | ✅ 16 tools | ✅ 16 tools | ✅ 16 tools | ✅ 16 tools |
 | **File system access** | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
 | **Code execution** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
 | **Package installation** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
@@ -50,13 +50,13 @@ pip install napari-mcp
 
 ```bash
 # For your specific application
-napari-mcp-install <app-name>
+napari-mcp-install install <app-name>
 
 # See all options
-napari-mcp-install --help
+napari-mcp-install install --help
 
 # Preview changes before applying
-napari-mcp-install <app-name> --dry-run
+napari-mcp-install install <app-name> --dry-run
 ```
 
 ### Step 3: Restart & Test
@@ -71,19 +71,19 @@ The CLI installer supports several options:
 
 ```bash
 # Use your Python environment instead of uv
-napari-mcp-install claude-desktop --persistent
+napari-mcp-install install claude-desktop --persistent
 
 # Custom Python path
-napari-mcp-install claude-desktop --python-path /path/to/python
+napari-mcp-install install claude-desktop --python-path /path/to/python
 
 # Preview changes only
-napari-mcp-install claude-desktop --dry-run
+napari-mcp-install install claude-desktop --dry-run
 
 # Force update without prompts
-napari-mcp-install claude-desktop --force
+napari-mcp-install install claude-desktop --force
 
 # Install for all applications
-napari-mcp-install all
+napari-mcp-install install all
 ```
 
 ## Management Commands
@@ -125,7 +125,7 @@ All platforms support environment variables for advanced configuration:
 
 ```bash
 export QT_QPA_PLATFORM=offscreen  # For headless servers
-export NAPARI_ASYNC=1             # Enable async operations
+
 export MCP_LOG_LEVEL=INFO         # Debug MCP communication
 ```
 
@@ -145,7 +145,7 @@ export MCP_LOG_LEVEL=INFO         # Debug MCP communication
 !!! failure "Configuration not detected"
     ```bash
     # List what would be configured
-    napari-mcp-install <app> --dry-run
+    napari-mcp-install install <app> --dry-run
 
     # Check current installations
     napari-mcp-install list
diff --git a/docs/integrations/other-llms.md b/docs/integrations/other-llms.md
index dbb63d9..19e93ea 100644
--- a/docs/integrations/other-llms.md
+++ b/docs/integrations/other-llms.md
@@ -13,10 +13,10 @@ Setup guide for Google's Gemini CLI with napari MCP server.
 pip install napari-mcp
 
 # 2. Auto-configure Gemini CLI (global)
-napari-mcp-install gemini --global
+napari-mcp-install install gemini --global
 
 # OR configure for specific project
-napari-mcp-install gemini --project /path/to/project
+napari-mcp-install install gemini --project /path/to/project
 ```
 
 ### Configuration Locations
@@ -28,16 +28,16 @@ napari-mcp-install gemini --project /path/to/project
 
 ```bash
 # Global installation (recommended)
-napari-mcp-install gemini --global
+napari-mcp-install install gemini --global
 
 # Project-specific installation
-napari-mcp-install gemini --project .
+napari-mcp-install install gemini --project .
 
 # Preview changes
-napari-mcp-install gemini --dry-run
+napari-mcp-install install gemini --dry-run
 
 # Use persistent Python
-napari-mcp-install gemini --persistent
+napari-mcp-install install gemini --persistent
 ```
 
 ### Manual Configuration
@@ -70,7 +70,7 @@ Gemini CLI supports additional configuration options:
 napari-mcp-install list
 
 # Update configuration
-napari-mcp-install gemini --global --force
+napari-mcp-install install gemini --global --force
 
 # Uninstall
 napari-mcp-install uninstall gemini
@@ -82,7 +82,7 @@ napari-mcp-install uninstall gemini
     1. Verify installation: `napari-mcp-install list`
     2. Check config file exists: `cat ~/.gemini/settings.json`
     3. Restart Gemini CLI
-    4. Reinstall: `napari-mcp-install gemini --global --force`
+    4. Reinstall: `napari-mcp-install install gemini --global --force`
 
 ---
 
@@ -97,7 +97,7 @@ Setup guide for OpenAI's Codex CLI with napari MCP server.
 pip install napari-mcp
 
 # 2. Auto-configure Codex CLI
-napari-mcp-install codex
+napari-mcp-install install codex
 
 # 3. Restart Codex CLI
 ```
@@ -113,16 +113,16 @@ napari-mcp-install codex
 
 ```bash
 # Basic installation
-napari-mcp-install codex
+napari-mcp-install install codex
 
 # Preview changes
-napari-mcp-install codex --dry-run
+napari-mcp-install install codex --dry-run
 
 # Use persistent Python
-napari-mcp-install codex --persistent
+napari-mcp-install install codex --persistent
 
 # Force update
-napari-mcp-install codex --force
+napari-mcp-install install codex --force
 ```
 
 ### Manual Configuration
@@ -150,7 +150,7 @@ args = ["-m", "napari_mcp.server"]
 napari-mcp-install list
 
 # Update configuration
-napari-mcp-install codex --force
+napari-mcp-install install codex --force
 
 # Uninstall
 napari-mcp-install uninstall codex
@@ -163,12 +163,12 @@ napari-mcp-install uninstall codex
     2. Check config file: `cat ~/.codex/config.toml`
     3. Validate TOML syntax: `python -c "import toml; toml.load(open('.codex/config.toml'))"`
     4. Restart Codex CLI
-    5. Reinstall: `napari-mcp-install codex --force`
+    5. Reinstall: `napari-mcp-install install codex --force`
 
 !!! failure "TOML syntax errors"
-    The installer requires the `toml` package. Install it:
+    The `toml` package is included as a dependency of napari-mcp. If it's missing, reinstall:
     ```bash
-    pip install toml
+    pip install --upgrade napari-mcp
     ```
 
 ---
@@ -178,7 +178,7 @@ napari-mcp-install uninstall codex
 You can install napari-mcp for all supported platforms at once:
 
 ```bash
-napari-mcp-install all
+napari-mcp-install install all
 ```
 
 This installs for:
@@ -191,7 +191,7 @@ This installs for:
 
 Use `--dry-run` to preview:
 ```bash
-napari-mcp-install all --dry-run
+napari-mcp-install install all --dry-run
 ```
 
 ---
diff --git a/docs/integrations/python.md b/docs/integrations/python.md
index 06e6933..c38e855 100644
--- a/docs/integrations/python.md
+++ b/docs/integrations/python.md
@@ -28,7 +28,7 @@ napari-mcp is an MCP server that can be integrated into Python scripts, allowing
 - Python 3.10+
 - napari-mcp installed: `pip install napari-mcp`
 - An LLM provider SDK: `pip install openai` or `pip install anthropic`
-- MCP client library: `pip install mcp` (or use `uv run --with openai --with mcp`)
+- MCP client library: `pip install mcp` (or use `uv run --with napari-mcp --with openai --with mcp`)
 
 ## Example: OpenAI with napari MCP
 
@@ -116,7 +116,7 @@ if __name__ == "__main__":
 python script.py
 
 # Or use uv for zero-install
-uv run --with openai --with mcp python script.py
+uv run --with napari-mcp --with openai --with mcp python script.py
 ```
 
 **→ See [OpenAI MCP Documentation](https://platform.openai.com/docs/guides/tools-connectors-mcp) for more details**
@@ -168,7 +168,7 @@ async def main():
 
             # Use Claude to interact with napari
             message = client.messages.create(
-                model="claude-3-5-sonnet-20241022",
+                model="claude-sonnet-4-6",
                 max_tokens=1024,
                 tools=tools,
                 messages=[
@@ -197,7 +197,7 @@ if __name__ == "__main__":
 python script.py
 
 # Or use uv for zero-install
-uv run --with anthropic --with mcp python script.py
+uv run --with napari-mcp --with anthropic --with mcp python script.py
 ```
 
 ## Example: Simple Napari MCP Client
@@ -260,7 +260,7 @@ if __name__ == "__main__":
 python script.py
 
 # Or with uv
-uv run --with mcp python script.py
+uv run --with napari-mcp --with mcp python script.py
 ```
 
 ## Available MCP Tools
@@ -273,17 +273,18 @@ All napari-mcp tools are available in your Python integration. Common ones inclu
 - `close_viewer()` - Close viewer
 
 ### Layer Operations
-- `add_image(path, name?, colormap?)` - Add image layer
-- `add_labels(path, name?)` - Add labels layer
-- `add_points(points, name?, size?)` - Add points
+- `add_layer(layer_type, path?, data?, data_var?, name?, ...)` - Add any layer type
 - `list_layers()` - List all layers
+- `get_layer(name, include_data?, slicing?)` - Get layer info and data
 - `remove_layer(name)` - Remove layer
+- `set_layer_properties(name, visible?, opacity?, ...)` - Set properties
+- `reorder_layer(name, index?, before?, after?)` - Reorder layers
+- `apply_to_layers(filter_type?, filter_pattern?, properties)` - Batch update
+- `save_layer_data(name, path)` - Export layer data
 
 ### Viewer Controls
-- `set_camera(center?, zoom?, angle?)` - Control camera
-- `reset_view()` - Reset view
-- `set_ndisplay(2|3)` - Switch 2D/3D
-- `screenshot(canvas_only?)` - Capture screenshot
+- `configure_viewer(zoom?, center?, ndisplay?, dims_axis?, grid?, ...)` - All viewer settings
+- `screenshot(canvas_only?, save_path?, axis?, slice_range?)` - Screenshot or timelapse
 
 ### Advanced
 - `execute_code(code)` - Run Python code
@@ -305,7 +306,7 @@ async def analyze_images(image_paths):
 
             for path in image_paths:
                 # Load image
-                await session.call_tool("add_image", {"path": path})
+                await session.call_tool("add_layer", {"layer_type": "image", "path": path})
 
                 # Process
                 code = """
@@ -349,7 +350,7 @@ Embed napari in larger applications:
 
 ```python
 try:
-    result = await session.call_tool("add_image", {"path": "/invalid/path.tif"})
+    result = await session.call_tool("add_layer", {"layer_type": "image", "path": "/invalid/path.tif"})
 except Exception as e:
     print(f"Error: {e}")
 ```
diff --git a/docs/scripts/gen_ref_pages.py b/docs/scripts/gen_ref_pages.py
index fc14204..6cf403b 100644
--- a/docs/scripts/gen_ref_pages.py
+++ b/docs/scripts/gen_ref_pages.py
@@ -1,93 +1,50 @@
-"""Generate API reference pages from source code."""
+"""Generate API reference pages by parsing tool function ASTs from server.py.
 
+Since tools are closures inside create_server(), mkdocstrings cannot
+introspect them directly. Instead, we parse the AST to extract function
+signatures and docstrings, then generate markdown pages.
+"""
+
+from __future__ import annotations
+
+import ast
 from pathlib import Path
 
 import mkdocs_gen_files
 
-# Define the source file
-src_file = Path("src/napari_mcp/server.py")
+# ---------------------------------------------------------------------------
+# Tool categories
+# ---------------------------------------------------------------------------
 
-# Function categories for organization
 function_categories = {
     "session": [
-        "detect_viewers",
         "init_viewer",
         "close_viewer",
         "session_information",
     ],
     "layer_management": [
         "list_layers",
-        "add_image",
-        "add_labels",
-        "add_points",
+        "get_layer",
+        "add_layer",
         "remove_layer",
         "set_layer_properties",
         "reorder_layer",
-        "set_active_layer",
+        "apply_to_layers",
+        "save_layer_data",
     ],
     "viewer_controls": [
-        "reset_view",
-        "set_camera",
-        "set_ndisplay",
-        "set_dims_current_step",
-        "set_grid",
+        "configure_viewer",
     ],
     "utilities": [
         "screenshot",
-        "timelapse_screenshot",
         "execute_code",
         "install_packages",
         "read_output",
     ],
 }
 
-# Generate main API reference page
-with mkdocs_gen_files.open("api/reference.md", "w") as f:
-    print("# Complete API Reference", file=f)
-    print("", file=f)
-    print("Auto-generated documentation for all napari MCP server functions.", file=f)
-    print("", file=f)
-    print('!!! info "Documentation Structure"', file=f)
-    print(
-        "    This page shows both the **MCP tool interface** (what you call from AI assistants) "
-        "and the **implementation** (NapariMCPTools class methods).",
-        file=f,
-    )
-    print(
-        "    All functions use NumPy-style docstrings with detailed parameter and "
-        "return information.",
-        file=f,
-    )
-    print("", file=f)
-
-    # Show the wrapper functions (MCP tool interface)
-    print("## MCP Tool Interface (server.py wrappers)", file=f)
-    print("", file=f)
-    print("These are the functions exposed as MCP tools:", file=f)
-    print("", file=f)
-    print("::: napari_mcp.server", file=f)
-    print("    options:", file=f)
-    print("      members_order: source", file=f)
-    print("      show_root_toc_entry: false", file=f)
-    print("      show_source: true", file=f)
-    print("      filters:", file=f)
-    print("        - '!^_'", file=f)
-    print("        - '!^NapariMCPTools$'", file=f)
-    print("", file=f)
-
-    # Show the implementation class
-    print("## Implementation (NapariMCPTools class)", file=f)
-    print("", file=f)
-    print("The actual implementation behind the MCP tools:", file=f)
-    print("", file=f)
-    print("::: napari_mcp.server.NapariMCPTools", file=f)
-    print("    options:", file=f)
-    print("      members_order: source", file=f)
-    print("      show_root_toc_entry: false", file=f)
-    print("      show_source: true", file=f)
-    print("      heading_level: 3", file=f)
+ALL_TOOLS = [fn for fns in function_categories.values() for fn in fns]
 
-# Generate category-specific pages
 category_titles = {
     "session": "Session & Viewer Controls",
     "layer_management": "Layer Management",
@@ -112,7 +69,108 @@
     ),
 }
 
-for category, functions in function_categories.items():
+# ---------------------------------------------------------------------------
+# AST extraction
+# ---------------------------------------------------------------------------
+
+src_file = Path("src/napari_mcp/server.py")
+
+
+def _extract_tool_functions(source: str) -> dict[str, dict]:
+    """Parse server.py and extract tool function signatures + docstrings.
+
+    Looks for ``async def <name>(...)`` inside ``create_server()`` that are
+    decorated with ``@_register``.
+    """
+    tree = ast.parse(source)
+    tools: dict[str, dict] = {}
+
+    # Find the create_server function
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.name == "create_server":
+                # Walk its body for @_register decorated functions
+                for child in ast.walk(node):
+                    if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        if child.name in ALL_TOOLS:
+                            docstring = ast.get_docstring(child) or ""
+                            sig = _format_signature(child)
+                            tools[child.name] = {
+                                "signature": sig,
+                                "docstring": docstring,
+                                "lineno": child.lineno,
+                            }
+                break
+    return tools
+
+
+def _format_signature(func_node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    """Format an AST function node into a human-readable signature string."""
+    args = func_node.args
+    params = []
+
+    # positional + keyword args
+    all_args = args.args
+    defaults = args.defaults
+    n_no_default = len(all_args) - len(defaults)
+
+    for i, arg in enumerate(all_args):
+        annotation = ""
+        if arg.annotation:
+            annotation = f": {ast.unparse(arg.annotation)}"
+
+        if i >= n_no_default:
+            default = ast.unparse(defaults[i - n_no_default])
+            params.append(f"{arg.arg}{annotation} = {default}")
+        else:
+            params.append(f"{arg.arg}{annotation}")
+
+    # keyword-only args
+    for i, arg in enumerate(args.kwonlyargs):
+        annotation = ""
+        if arg.annotation:
+            annotation = f": {ast.unparse(arg.annotation)}"
+        default = ""
+        if args.kw_defaults[i] is not None:
+            default = f" = {ast.unparse(args.kw_defaults[i])}"
+        params.append(f"{arg.arg}{annotation}{default}")
+
+    ret = ""
+    if func_node.returns:
+        ret = f" -> {ast.unparse(func_node.returns)}"
+
+    return f"({', '.join(params)}){ret}"
+
+
+def _render_tool_markdown(name: str, info: dict) -> str:
+    """Render a single tool as markdown."""
+    lines = []
+    lines.append(f"### `{name}`")
+    lines.append("")
+    lines.append(f"```python")
+    lines.append(f"async def {name}{info['signature']}")
+    lines.append(f"```")
+    lines.append("")
+    if info["docstring"]:
+        lines.append(info["docstring"])
+        lines.append("")
+    lines.append(
+        f'<small>[Source: server.py:{info["lineno"]}]'
+        f"(https://github.com/royerlab/napari-mcp/blob/main/src/napari_mcp/server.py#L{info['lineno']})</small>"
+    )
+    lines.append("")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Generate pages
+# ---------------------------------------------------------------------------
+
+source = src_file.read_text()
+tools = _extract_tool_functions(source)
+
+# --- Category pages ---
+for category, func_names in function_categories.items():
     filename = f"api/{category.replace('_', '-')}.md"
     title = category_titles[category]
     description = category_descriptions[category]
@@ -123,33 +181,62 @@
         print(description, file=f)
         print("", file=f)
 
-        for func in functions:
-            print(f"## {func}", file=f)
-            print("", file=f)
-
-            # Show the wrapper function (MCP tool interface)
-            print("### MCP Tool Interface", file=f)
-            print("", file=f)
-            print(f"::: napari_mcp.server.{func}", file=f)
-            print("    options:", file=f)
-            print("      show_root_toc_entry: false", file=f)
-            print("      show_source: true", file=f)
-            print("", file=f)
-
-            # Show the actual implementation (NapariMCPTools class method)
-            print("### Implementation", file=f)
-            print("", file=f)
-            print(f"::: napari_mcp.server.NapariMCPTools.{func}", file=f)
-            print("    options:", file=f)
-            print("      show_root_toc_entry: false", file=f)
-            print("      show_source: true", file=f)
-            print("      heading_level: 4", file=f)
-            print("", file=f)
-
-# Generate navigation file
+        for func_name in func_names:
+            if func_name in tools:
+                print(_render_tool_markdown(func_name, tools[func_name]), file=f)
+            else:
+                print(f"### `{func_name}`", file=f)
+                print("", file=f)
+                print("*Documentation not available (function not found in AST).*", file=f)
+                print("", file=f)
+
+# --- Complete reference page ---
+with mkdocs_gen_files.open("api/reference.md", "w") as f:
+    print("# Complete API Reference", file=f)
+    print("", file=f)
+    print(
+        "Auto-generated documentation for all 16 napari MCP server tools, "
+        "extracted from source code.",
+        file=f,
+    )
+    print("", file=f)
+
+    for category, func_names in function_categories.items():
+        title = category_titles[category]
+        print(f"## {title}", file=f)
+        print("", file=f)
+        for func_name in func_names:
+            if func_name in tools:
+                print(_render_tool_markdown(func_name, tools[func_name]), file=f)
+
+# --- Supporting modules (these can use mkdocstrings directly) ---
+with mkdocs_gen_files.open("api/modules.md", "w") as f:
+    print("# Supporting Modules", file=f)
+    print("", file=f)
+    print("## ServerState", file=f)
+    print("", file=f)
+    print("::: napari_mcp.state.ServerState", file=f)
+    print("    options:", file=f)
+    print("      show_root_toc_entry: false", file=f)
+    print("      members_order: source", file=f)
+    print("", file=f)
+    print("## Output Utilities", file=f)
+    print("", file=f)
+    print("::: napari_mcp.output", file=f)
+    print("    options:", file=f)
+    print("      show_root_toc_entry: false", file=f)
+    print("", file=f)
+    print("## Shared Helpers", file=f)
+    print("", file=f)
+    print("::: napari_mcp._helpers", file=f)
+    print("    options:", file=f)
+    print("      show_root_toc_entry: false", file=f)
+    print("      members_order: source", file=f)
+
+# --- Index page ---
 nav_content = """# API Reference
 
-This section contains comprehensive documentation for all napari MCP server functions.
+This section contains comprehensive documentation for all napari MCP server tools.
 
 ## Organization
 
@@ -159,6 +246,7 @@
 - **[Layer Management](layer-management.md)** - Creating and managing layers
 - **[Viewer Controls](viewer-controls.md)** - Camera and navigation controls
 - **[Utilities](utilities.md)** - Advanced features and tools
+- **[Supporting Modules](modules.md)** - ServerState, helpers, and utilities
 
 ## Complete Reference
 
@@ -168,15 +256,15 @@
 
 | Category | Functions | Description |
 |----------|-----------|-------------|
-| **Session** | 4 functions | Viewer creation, detection, and session info |
-| **Layers** | 8 functions | Image, label, point layers with full control |
-| **Navigation** | 5 functions | Camera, dimensions, display modes |
-| **Utilities** | 5 functions | Screenshots, timelapse, code execution, packages |
+| **Session** | 3 functions | Viewer creation and session info |
+| **Layers** | 8 functions | All layer types with full CRUD |
+| **Navigation** | 1 function | Camera, dimensions, display modes |
+| **Utilities** | 4 functions | Screenshots, code execution, packages |
 
-**Total: 22 MCP tools available**
+**Total: 16 MCP tools available**
 """
 
 with mkdocs_gen_files.open("api/index.md", "w") as f:
     print(nav_content, file=f)
 
-print("✅ API documentation pages generated successfully!")
+print(f"API docs generated: {len(tools)}/{len(ALL_TOOLS)} tools extracted from AST")
diff --git a/mkdocs.yml b/mkdocs.yml
index 8ef1450..6d8da37 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -111,9 +111,11 @@ nav:
         - Python Scripts: integrations/python.md
   - API Reference:
       - api/index.md
-      - Session & Viewer: api/viewer-controls.md
+      - Session & Viewer: api/session.md
       - Layer Management: api/layer-management.md
+      - Viewer Controls: api/viewer-controls.md
       - Utilities: api/utilities.md
+      - Supporting Modules: api/modules.md
       - Complete Reference: api/reference.md
   - User Guide:
       - guides/index.md
@@ -145,4 +147,4 @@ extra_css:
   - stylesheets/extra.css
 
 copyright: >
-  Copyright &copy; 2025 Ilan Theodoro
+  Copyright &copy; 2025-2026 Ilan Theodoro
diff --git a/pyproject.toml b/pyproject.toml
index 3b839f9..5383810 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -27,7 +27,6 @@ classifiers = [
 dependencies = [
   "fastmcp>=2.10.3",
   "napari>=0.5.5",
-  "pyqt6>=6.5.0",
   "qtpy>=2.4.1",
   "Pillow>=10.3.0",
   "imageio>=2.34.0",
@@ -35,6 +34,7 @@ dependencies = [
   "typer>=0.9.0",
   "rich>=13.0.0",
   "toml>=0.10.2",
+  'tomli>=2.0; python_version < "3.11"',
 ]
 
 [project.urls]
@@ -42,24 +42,8 @@ Homepage = "https://github.com/royerlab/napari-mcp"
 Repository = "https://github.com/royerlab/napari-mcp"
 Documentation = "https://royerlab.github.io/napari-mcp/"
 "Bug Tracker" = "https://github.com/royerlab/napari-mcp/issues"
-Changelog = "https://github.com/royerlab/napari-mcp/blob/main/CHANGELOG.md"
 
 [project.optional-dependencies]
-test = [
-  "pytest>=8.4.0",
-  "pytest-asyncio>=0.23.0",
-  "pytest-cov>=4.0.0",
-  "pytest-qt>=4.0.0",
-  "pytest-xdist>=3.5.0",
-  "pytest-timeout>=2.2.0",
-  "pytest-benchmark>=4.0.0",
-  "pytest-mock>=3.12.0",
-  "pytest-random-order>=1.1.0",
-  "pytest-forked>=1.6.0",
-  "hypothesis>=6.100.0",
-  "napari[testing,pyqt6]",
-  "tox",
-]
 dev = [
   "ruff>=0.12.10",
   "mypy>=1.17.0",
@@ -67,9 +51,8 @@ dev = [
   "types-Pillow>=10.0.0",
   "pre-commit>=4.3.0",
   "bandit>=1.8.6",
-  "black>=24.0.0",
 ]
-all = ["napari-mcp[test,dev]"]
+all = ["napari-mcp[dev]"]
 
 [project.scripts]
 napari-mcp = "napari_mcp.server:main"
@@ -118,10 +101,13 @@ markers = [
   "unit: marks unit tests",
   "smoke: marks smoke tests for quick validation",
   "isolated: marks tests that must run in complete isolation",
+  "benchmark: marks performance benchmark tests",
 ]
 filterwarnings = [
-  "ignore::DeprecationWarning",
-  "ignore::PendingDeprecationWarning",
+  "ignore::DeprecationWarning:napari.*",
+  "ignore::DeprecationWarning:vispy.*",
+  "ignore::DeprecationWarning:qtpy.*",
+  "ignore::PendingDeprecationWarning:napari.*",
 ]
 # Test isolation settings
 junit_family = "xunit2"
@@ -175,14 +161,10 @@ select = [
   "PIE", # flake8-pie
 ]
 ignore = [
-  "E501",   # line too long - let black handle this
+  "E501",   # line too long - handled by ruff format
   "BLE001", # blind except - needed for robust error handling in server code
   "S101",   # assert detected - allow in tests
-  "S102",   # exec detected - needed for MCP server functionality
   "S110",   # try-except-pass - acceptable for best-effort operations
-  "S307",   # eval detected - needed for MCP server functionality
-  "S603",   # subprocess call - allow for tools
-  "S607",   # subprocess with shell - allow for tools
   "SIM105", # contextlib.suppress - prefer explicit try/except for clarity
   "TCH003", # typing-only imports - not critical for functionality
   "D401",   # imperative mood - not critical for functionality
@@ -201,6 +183,11 @@ convention = "numpy"
   "S311",
   "D",
 ] # Allow asserts, hardcoded passwords, random, and skip docstrings in tests
+"src/napari_mcp/server.py" = ["S102", "S307", "A002"]  # exec/eval needed for MCP execute_code; format param
+"src/napari_mcp/bridge_server.py" = ["S102", "S307"]  # exec/eval needed for MCP execute_code
+"src/napari_mcp/_helpers.py" = ["S102", "S307"]  # exec/eval needed for run_code helper
+"src/napari_mcp/cli/install/utils.py" = ["S603", "S607"]  # subprocess needed for python detection
+"src/napari_mcp/cli/install/codex_cli.py" = ["S603", "S607"]  # subprocess needed for codex
 
 [tool.ruff.format]
 quote-style = "double"
@@ -208,22 +195,19 @@ indent-style = "space"
 skip-magic-trailing-comma = false
 line-ending = "auto"
 
-[tool.black]
-line-length = 88
-target-version = ['py310', 'py311', 'py312', 'py313']
-
 [dependency-groups]
 dev = [
     "ruff>=0.12.10",
-    "black>=24.0.0",
     "types-toml>=0.10.8.20240310",
 ]
 testing = [
-  "tox",
   "pytest>=8.4.0",
+  "pytest-asyncio>=0.23.0",
   "pytest-cov>=4.0.0",
   "pytest-qt>=4.0.0",
-  "pytest-asyncio>=0.23.0",
+  "pytest-xdist>=3.5.0",
+  "pytest-timeout>=2.2.0",
+  "pytest-benchmark>=4.0.0",
   "pytest-mock>=3.12.0",
   "pytest-random-order>=1.1.0",
   "pytest-forked>=1.6.0",
@@ -240,9 +224,8 @@ napari-mcp = { path = ".", editable = true }
 
 [tool.pixi.environments]
 default = { solve-group = "default" }
-all = { features = ["all", "test", "dev"], solve-group = "default" }
+all = { features = ["all", "dev", "testing"], solve-group = "default" }
 dev = { features = ["dev"], solve-group = "default" }
-test = { features = ["test"], solve-group = "default" }
 testing = { features = ["testing"], solve-group = "default" }
 
 [tool.pixi.tasks]
diff --git a/src/napari_mcp/__init__.py b/src/napari_mcp/__init__.py
index e055c3a..3ff1611 100644
--- a/src/napari_mcp/__init__.py
+++ b/src/napari_mcp/__init__.py
@@ -12,14 +12,25 @@
         __version__ = "0.0.0"
 
 # Import main components
-from .bridge_server import NapariBridgeServer
-from .server import NapariMCPTools
+from .server import create_server
 from .server import main as server_main
-from .widget import MCPControlWidget
+from .state import ServerState, StartupMode
+from .viewer_protocol import ViewerProtocol
+
+# Qt-dependent components may not be available in headless environments
+try:
+    from .bridge_server import NapariBridgeServer
+    from .widget import MCPControlWidget
+except ImportError:  # pragma: no cover
+    NapariBridgeServer = None  # type: ignore[assignment,misc]
+    MCPControlWidget = None  # type: ignore[assignment,misc]
 
 __all__ = [
-    "NapariMCPTools",
     "NapariBridgeServer",
     "MCPControlWidget",
+    "ServerState",
+    "StartupMode",
+    "ViewerProtocol",
+    "create_server",
     "server_main",
 ]
diff --git a/src/napari_mcp/_helpers.py b/src/napari_mcp/_helpers.py
new file mode 100644
index 0000000..07e987a
--- /dev/null
+++ b/src/napari_mcp/_helpers.py
@@ -0,0 +1,402 @@
+"""Shared helpers used by both server.py and bridge_server.py.
+
+These functions extract logic that was previously duplicated between the
+standalone server and the bridge server.
+"""
+
+from __future__ import annotations
+
+import ast
+import contextlib
+import traceback
+from io import StringIO
+from typing import Any
+
+import numpy as np
+
+from napari_mcp.output import truncate_output
+
+# ---------------------------------------------------------------------------
+# Bool parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_bool(value: bool | str | None, default: bool = False) -> bool:
+    """Parse a boolean value from various input types.
+
+    Handles bool, str ("true"/"false"/"1"/"0"/etc.), and None.
+    """
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.lower() in ("true", "1", "yes", "on")
+    return bool(value)
+
+
+# ---------------------------------------------------------------------------
+# Layer type alias map
+# ---------------------------------------------------------------------------
+
+LAYER_TYPE_ALIASES: dict[str, str] = {
+    "image": "image",
+    "images": "image",
+    "labels": "labels",
+    "label": "labels",
+    "points": "points",
+    "point": "points",
+    "shapes": "shapes",
+    "shape": "shapes",
+    "vectors": "vectors",
+    "vector": "vectors",
+    "tracks": "tracks",
+    "track": "tracks",
+    "surface": "surface",
+    "surfaces": "surface",
+}
+
+
+def resolve_layer_type(layer_type: str) -> str | None:
+    """Resolve a layer type string to its canonical form.
+
+    Returns None if the type is not recognized.
+    """
+    return LAYER_TYPE_ALIASES.get(layer_type.strip().lower())
+
+
+# ---------------------------------------------------------------------------
+# Layer detail building (shared between session_information variants)
+# ---------------------------------------------------------------------------
+
+
+def build_layer_detail(layer: Any) -> dict[str, Any]:
+    """Build a detail dict for a single napari layer.
+
+    Used by session_information in both standalone and bridge modes.
+    """
+    detail: dict[str, Any] = {
+        "name": layer.name,
+        "type": layer.__class__.__name__,
+        "visible": bool(getattr(layer, "visible", True)),
+        "opacity": float(getattr(layer, "opacity", 1.0)),
+    }
+    if hasattr(layer, "data") and hasattr(layer.data, "shape"):
+        detail["data_shape"] = list(layer.data.shape)
+    if hasattr(layer, "data") and hasattr(layer.data, "dtype"):
+        detail["data_dtype"] = str(layer.data.dtype)
+    if hasattr(layer, "colormap"):
+        detail["colormap"] = getattr(layer.colormap, "name", str(layer.colormap))
+    if hasattr(layer, "blending"):
+        detail["blending"] = getattr(layer, "blending", None)
+    if hasattr(layer, "contrast_limits"):
+        try:
+            cl = layer.contrast_limits
+            detail["contrast_limits"] = [float(cl[0]), float(cl[1])]
+        except Exception:
+            pass
+    if hasattr(layer, "gamma"):
+        detail["gamma"] = float(getattr(layer, "gamma", 1.0))
+    return detail
+
+
+# ---------------------------------------------------------------------------
+# Layer creation on viewer (shared between server and bridge)
+# ---------------------------------------------------------------------------
+
+
+def create_layer_on_viewer(
+    viewer: Any,
+    resolved_data: Any,
+    lt: str,
+    *,
+    name: str | None = None,
+    colormap: str | None = None,
+    blending: str | None = None,
+    channel_axis: int | str | None = None,
+    size: float | str | None = None,
+    shape_type: str | None = None,
+    edge_color: str | None = None,
+    face_color: str | None = None,
+    edge_width: float | str | None = None,
+) -> dict[str, Any]:
+    """Add a layer to a napari viewer and return a result dict.
+
+    This is the shared core used by ``add_layer`` in both server.py
+    (standalone) and bridge_server.py (Qt thread). The caller is responsible
+    for calling ``process_events`` and holding locks.
+
+    Parameters
+    ----------
+    viewer : napari.Viewer
+        The napari viewer instance.
+    resolved_data : Any
+        The data to add (numpy array, list, tuple, etc.).
+    lt : str
+        Canonical layer type (one of: image, labels, points, shapes,
+        vectors, tracks, surface).
+    """
+    if lt == "image":
+        arr = np.asarray(resolved_data)
+        if arr.size == 0:
+            return {
+                "status": "error",
+                "message": "Cannot add image layer: data is empty.",
+            }
+        if np.issubdtype(arr.dtype, np.complexfloating):
+            return {
+                "status": "error",
+                "message": (
+                    f"Cannot add image layer: complex dtype ({arr.dtype}) "
+                    "not supported. Convert to real first (e.g., np.abs(data))."
+                ),
+            }
+        kwargs: dict[str, Any] = {"name": name}
+        if colormap is not None:
+            kwargs["colormap"] = colormap
+        if blending is not None:
+            kwargs["blending"] = blending
+        if channel_axis is not None:
+            kwargs["channel_axis"] = int(channel_axis)
+        layer = viewer.add_image(arr, **kwargs)
+        # napari returns a list of layers when channel_axis is used
+        if isinstance(layer, list):
+            names = [lyr.name for lyr in layer]
+            return {
+                "status": "ok",
+                "name": names,
+                "shape": list(np.shape(arr)),
+                "n_channels": len(layer),
+            }
+        return {"status": "ok", "name": layer.name, "shape": list(np.shape(arr))}
+
+    elif lt == "labels":
+        arr = np.asarray(resolved_data)
+        if arr.size == 0:
+            return {
+                "status": "error",
+                "message": "Cannot add labels layer: data is empty.",
+            }
+        layer = viewer.add_labels(arr, name=name)
+        return {"status": "ok", "name": layer.name, "shape": list(np.shape(arr))}
+
+    elif lt == "points":
+        arr = np.asarray(resolved_data, dtype=float)
+        if arr.size == 0:
+            return {
+                "status": "error",
+                "message": "Cannot add points layer: data is empty.",
+            }
+        layer = viewer.add_points(arr, name=name, size=float(size or 10.0))
+        return {"status": "ok", "name": layer.name, "n_points": int(arr.shape[0])}
+
+    elif lt == "shapes":
+        kwargs = {"name": name, "shape_type": shape_type or "rectangle"}
+        if edge_color is not None:
+            kwargs["edge_color"] = edge_color
+        if face_color is not None:
+            kwargs["face_color"] = face_color
+        if edge_width is not None:
+            kwargs["edge_width"] = float(edge_width)
+        layer = viewer.add_shapes(resolved_data, **kwargs)
+        return {"status": "ok", "name": layer.name, "nshapes": int(layer.nshapes)}
+
+    elif lt == "vectors":
+        arr = np.asarray(resolved_data, dtype=float)
+        kwargs = {"name": name}
+        if edge_color is not None:
+            kwargs["edge_color"] = edge_color
+        if edge_width is not None:
+            kwargs["edge_width"] = float(edge_width)
+        layer = viewer.add_vectors(arr, **kwargs)
+        return {"status": "ok", "name": layer.name, "n_vectors": int(arr.shape[0])}
+
+    elif lt == "tracks":
+        arr = np.asarray(resolved_data, dtype=float)
+        layer = viewer.add_tracks(arr, name=name)
+        return {
+            "status": "ok",
+            "name": layer.name,
+            "n_tracks": int(len(np.unique(arr[:, 0]))),
+        }
+
+    elif lt == "surface":
+        layer = viewer.add_surface(resolved_data, name=name)
+        verts = np.asarray(resolved_data[0])
+        faces = np.asarray(resolved_data[1])
+        return {
+            "status": "ok",
+            "name": layer.name,
+            "n_vertices": int(verts.shape[0]),
+            "n_faces": int(faces.shape[0]),
+        }
+
+    else:
+        return {
+            "status": "error",
+            "message": f"Unknown layer type '{lt}'.",
+        }
+
+
+# ---------------------------------------------------------------------------
+# Code execution core
+# ---------------------------------------------------------------------------
+
+
+def run_code(
+    code: str,
+    exec_globals: dict[str, Any],
+    *,
+    source_label: str = "<mcp-exec>",
+) -> tuple[str, str, str | None, Exception | None]:
+    """Execute Python code with stdout/stderr capture.
+
+    This is the shared core used by both ``execute_code`` in server.py
+    (standalone) and bridge_server.py (Qt thread).
+
+    Parameters
+    ----------
+    code : str
+        Python code string. The last expression's value is captured.
+    exec_globals : dict
+        The execution namespace (both globals and locals).
+    source_label : str
+        Label for compile() filename, e.g. ``"<mcp-exec>"`` or ``"<bridge-exec>"``.
+
+    Returns
+    -------
+    tuple of (stdout, stderr, result_repr, error)
+        - stdout: captured stdout output
+        - stderr: captured stderr output (includes traceback on error)
+        - result_repr: repr() of the last expression, or None
+        - error: the exception if one occurred, or None
+    """
+    stdout_buf = StringIO()
+    stderr_buf = StringIO()
+    result_repr: str | None = None
+    error: Exception | None = None
+
+    try:
+        with (
+            contextlib.redirect_stdout(stdout_buf),
+            contextlib.redirect_stderr(stderr_buf),
+        ):
+            parsed = ast.parse(code, mode="exec")
+            if parsed.body and isinstance(parsed.body[-1], ast.Expr):
+                if len(parsed.body) > 1:
+                    exec_ast = ast.Module(body=parsed.body[:-1], type_ignores=[])
+                    exec(
+                        compile(exec_ast, source_label, "exec"),
+                        exec_globals,
+                        exec_globals,
+                    )
+                last_expr = ast.Expression(body=parsed.body[-1].value)
+                value = eval(
+                    compile(last_expr, source_label.replace("-exec", "-eval"), "eval"),
+                    exec_globals,
+                    exec_globals,
+                )
+                result_repr = repr(value)
+            else:
+                exec(
+                    compile(parsed, source_label, "exec"),
+                    exec_globals,
+                    exec_globals,
+                )
+    except Exception as e:
+        tb = traceback.format_exc()
+        error = e
+        # Append traceback to stderr
+        stderr_buf.write(tb)
+
+    return (
+        stdout_buf.getvalue(),
+        stderr_buf.getvalue(),
+        result_repr,
+        error,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Truncated response building
+# ---------------------------------------------------------------------------
+
+
+def build_truncated_response(
+    *,
+    status: str,
+    output_id: str,
+    stdout_full: str,
+    stderr_full: str,
+    result_repr: str | None,
+    line_limit: int | str,
+    error: Exception | None = None,
+) -> dict[str, Any]:
+    """Build a response dict with optional output truncation.
+
+    This is the shared pattern used by ``execute_code`` in both server.py
+    and bridge_server.py, and also by ``install_packages``.
+
+    Parameters
+    ----------
+    status : str
+        "ok" or "error".
+    output_id : str
+        The stored output ID.
+    stdout_full, stderr_full : str
+        Full stdout/stderr content.
+    result_repr : str or None
+        The repr of the last expression result.
+    line_limit : int or str
+        Maximum lines (-1 for unlimited). Strings are converted to int;
+        invalid values fall back to 30.
+    error : Exception or None
+        The exception, if status == "error".
+
+    Returns
+    -------
+    dict[str, Any]
+        The response dict ready to return from a tool.
+    """
+    response: dict[str, Any] = {
+        "status": status,
+        "output_id": output_id,
+    }
+    if result_repr is not None:
+        response["result_repr"] = result_repr
+
+    try:
+        line_limit = int(line_limit)
+    except (ValueError, TypeError):
+        line_limit = 30
+
+    if line_limit == -1:
+        response["warning"] = (
+            "Unlimited output requested. This may consume a large number "
+            "of tokens. Consider using read_output for large outputs."
+        )
+        response["stdout"] = stdout_full
+        response["stderr"] = stderr_full
+    else:
+        limit = line_limit
+        stdout_truncated, stdout_was_truncated = truncate_output(stdout_full, limit)
+        stderr_truncated, stderr_was_truncated = truncate_output(stderr_full, limit)
+        response["stdout"] = stdout_truncated
+
+        # For errors, inject a summary line if not already visible
+        if status == "error" and error is not None:
+            error_summary = f"{type(error).__name__}: {error}"
+            if error_summary not in stderr_truncated:
+                if stderr_truncated and not stderr_truncated.endswith("\n"):
+                    stderr_truncated += "\n"
+                stderr_truncated += error_summary + "\n"
+
+        response["stderr"] = stderr_truncated
+        if stdout_was_truncated or stderr_was_truncated:
+            response["truncated"] = True
+            response["message"] = (
+                f"Output truncated to {limit} lines. "
+                f"Use read_output('{output_id}') to retrieve full output."
+            )
+
+    return response
diff --git a/src/napari_mcp/bridge_server.py b/src/napari_mcp/bridge_server.py
index 74e272b..d52dc76 100644
--- a/src/napari_mcp/bridge_server.py
+++ b/src/napari_mcp/bridge_server.py
@@ -1,21 +1,21 @@
-"""MCP Server runner for napari plugin."""
+"""Bridge MCP server for the napari plugin.
+
+Creates a ``ServerState`` and calls ``create_server()`` to build the base
+server, then overrides ``session_information``, ``add_layer``, and
+``execute_code`` with thread-safe versions that dispatch to the Qt main thread
+via ``QtBridge``.
+"""
 
 from __future__ import annotations
 
 import asyncio
-import base64
-import contextlib
 import logging
 import threading
 from concurrent.futures import Future
-from functools import wraps
-from io import BytesIO, StringIO
+from concurrent.futures import TimeoutError as FutureTimeoutError
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
-from fastmcp import FastMCP
-
-from napari_mcp.server import NapariMCPTools as _Tools
 
 if TYPE_CHECKING:
     import napari
@@ -23,17 +23,23 @@
 else:
     ImageContent = Any
 
-from PIL import Image
 from qtpy.QtCore import QObject, QThread, Signal, Slot
 from qtpy.QtWidgets import QApplication
 
-from napari_mcp.server import _parse_bool
+from napari_mcp._helpers import (
+    build_layer_detail,
+    build_truncated_response,
+    create_layer_on_viewer,
+    resolve_layer_type,
+    run_code,
+)
+from napari_mcp.server import create_server
+from napari_mcp.state import ServerState, StartupMode
 
 
 class QtBridge(QObject):
     """Qt bridge for thread-safe operations."""
 
-    # Signal to request operation in main thread
     operation_requested = Signal(object, object)  # (callable, future)
 
     def __init__(self):
@@ -49,17 +55,32 @@ def _execute_operation(self, operation, future):
         except Exception as e:
             future.set_exception(e)
 
-    def run_in_main_thread(self, operation):
-        """Run an operation in the main thread and return the result."""
-        # Check if we're already on the main thread using Qt's method
+    def run_in_main_thread(self, operation, timeout=300.0):
+        """Run an operation in the main thread and return the result.
+
+        Parameters
+        ----------
+        operation : callable
+            The function to execute on the Qt main thread.
+        timeout : float
+            Maximum seconds to wait for the operation to complete.
+            Defaults to 300 (5 minutes).
+        """
         if QThread.currentThread() == QApplication.instance().thread():
-            # We're already on the main thread, execute directly
             return operation()
 
-        # Use signal/slot mechanism for cross-thread execution
         future = Future()
         self.operation_requested.emit(operation, future)
-        return future.result(timeout=5.0)
+        try:
+            return future.result(timeout=timeout)
+        except (TimeoutError, FutureTimeoutError):
+            raise TimeoutError(
+                f"napari bridge operation timed out after {timeout:.0f}s. "
+                f"The operation may still be running on the napari main thread. "
+                f"Consider breaking your code into smaller steps, or if the "
+                f"computation is genuinely long-running, use execute_code with "
+                f"a larger timeout parameter."
+            ) from None
 
 
 class NapariBridgeServer:
@@ -77,68 +98,36 @@ def __init__(self, viewer: napari.Viewer, port: int = 9999):
         """
         self.viewer = viewer
         self.port = port
-        self.server = FastMCP("Napari Bridge MCP Server")
         self.server_task = None
         self.loop = None
         self.thread = None
-        self._exec_globals: dict[str, Any] = {}
+
+        # Qt bridge for thread-safe operations
         self.qt_bridge = QtBridge()
-        # Move QtBridge to main thread for proper signal/slot communication
         app = QApplication.instance()
         if app and app.thread() != self.qt_bridge.thread():
             self.qt_bridge.moveToThread(app.thread())
-        # Expose this viewer to shared implementation so server/bridge delegate consistently
-        try:
-            from napari_mcp import server as _srv_impl
 
-            _srv_impl._viewer = viewer  # type: ignore[attr-defined]
+        # Create state with STANDALONE mode (bridge IS the local viewer)
+        self.state = ServerState(mode=StartupMode.STANDALONE, bridge_port=port)
+        self.state.viewer = viewer
+        self.state.gui_executor = self.qt_bridge.run_in_main_thread
 
-            # Disable external proxying inside the bridge to avoid loops
-            async def _no_proxy(*_args, **_kwargs):
-                return None
+        # Create server with all shared tools bound to this state
+        self.server = create_server(self.state)
 
-            async def _no_detect():
-                return (None, None)
+        # Remove lifecycle tools that should not be available in bridge mode
+        # (the viewer is managed by napari, not the agent)
+        for name in ("close_viewer", "init_viewer"):
+            self.server._tool_manager._tools.pop(name, None)
 
-            _srv_impl._proxy_to_external = _no_proxy  # type: ignore[attr-defined]
-            _srv_impl._detect_external_viewer = _no_detect  # type: ignore[attr-defined]
-            # Configure shared tools to run GUI ops on the main thread
-            if hasattr(_srv_impl, "set_gui_executor"):
-                _srv_impl.set_gui_executor(self.qt_bridge.run_in_main_thread)
+        # Override the 3 tools that differ in bridge mode
+        self._register_bridge_overrides()
 
-            # Also disable external session info to prevent recursion
-            async def _no_external_session_info(_port):
-                raise RuntimeError("external session disabled in bridge")
+    def _register_bridge_overrides(self):
+        """Register bridge-specific tool overrides."""
 
-            if hasattr(_srv_impl, "NapariMCPTools"):
-                _srv_impl.NapariMCPTools._external_session_information = (  # type: ignore[attr-defined, method-assign]
-                    _no_external_session_info
-                )
-        except Exception:
-            pass
-        self._setup_tools()
-
-    def _run_in_main(self, func):
-        """Decorator to run a function in the main thread."""
-
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            return self.qt_bridge.run_in_main_thread(lambda: func(*args, **kwargs))
-
-        return wrapper
-
-    def _encode_png_base64(self, img: np.ndarray) -> dict[str, str]:
-        """Encode image as base64 PNG."""
-        pil = Image.fromarray(img)
-        buf = BytesIO()
-        pil.save(buf, format="PNG")
-        data = base64.b64encode(buf.getvalue()).decode("ascii")
-        return {"mime_type": "image/png", "base64_data": data}
-
-    def _setup_tools(self):
-        """Register all MCP tools with the server."""
-
-        @self.server.tool
+        @self.server.tool()
         async def session_information():
             """Get comprehensive information about the current napari session."""
 
@@ -160,21 +149,9 @@ def get_info():
                     "grid_enabled": self.viewer.grid.enabled,
                 }
 
-                layer_details = []
-                for layer in self.viewer.layers:
-                    layer_detail = {
-                        "name": layer.name,
-                        "type": layer.__class__.__name__,
-                        "visible": _parse_bool(getattr(layer, "visible", True)),
-                        "opacity": float(getattr(layer, "opacity", 1.0)),
-                    }
-                    if hasattr(layer, "data") and hasattr(layer.data, "shape"):
-                        layer_detail["data_shape"] = list(layer.data.shape)
-                    if hasattr(layer, "colormap"):
-                        layer_detail["colormap"] = getattr(
-                            layer.colormap, "name", str(layer.colormap)
-                        )
-                    layer_details.append(layer_detail)
+                layer_details = [
+                    build_layer_detail(layer) for layer in self.viewer.layers
+                ]
 
                 return {
                     "status": "ok",
@@ -184,190 +161,180 @@ def get_info():
                     "bridge_port": self.port,
                 }
 
-            # Run in main thread via Qt bridge and avoid any external proxy recursion
             return self.qt_bridge.run_in_main_thread(get_info)
 
-        @self.server.tool
-        async def list_layers():
-            """Return a list of layers with key properties."""
-            return await _Tools.list_layers()
-
-        @self.server.tool
-        async def add_image(
-            data: list | None = None,
+        @self.server.tool()
+        async def add_layer(
+            layer_type: str,
             path: str | None = None,
+            data: list | None = None,
+            data_var: str | None = None,
             name: str | None = None,
             colormap: str | None = None,
+            blending: str | None = None,
+            channel_axis: int | str | None = None,
+            size: float | str | None = None,
+            shape_type: str | None = None,
+            edge_color: str | None = None,
+            face_color: str | None = None,
+            edge_width: float | str | None = None,
         ):
-            """Add an image layer from data or file path."""
-            if path:
-                return await _Tools.add_image(path=path, name=name, colormap=colormap)
-
-            if data is None:
+            """Add a layer via the bridge (Qt main thread)."""
+            lt = resolve_layer_type(layer_type)
+            if lt is None:
                 return {
                     "status": "error",
-                    "message": "Either data or path must be provided",
+                    "message": (
+                        f"Unknown layer_type '{layer_type}'. "
+                        f"Valid types: image, labels, points, shapes, vectors, tracks, surface"
+                    ),
                 }
 
-            # Fallback: add from in-memory data on GUI thread
-            arr = np.asarray(data)
-
-            def add_layer():
-                layer = self.viewer.add_image(arr, name=name, colormap=colormap)
-                return {"status": "ok", "name": layer.name, "shape": list(arr.shape)}
-
-            return self.qt_bridge.run_in_main_thread(add_layer)
-
-        @self.server.tool
-        async def add_points(
-            points: list[list[float]], name: str | None = None, size: float = 10.0
-        ):
-            """Add a points layer."""
-            return await _Tools.add_points(points=points, name=name, size=size)
-
-        @self.server.tool
-        async def remove_layer(name: str):
-            """Remove a layer by name."""
-            return await _Tools.remove_layer(name)
-
-        @self.server.tool
-        async def rename_layer(old_name: str, new_name: str):
-            """Rename a layer (delegates to set_layer_properties)."""
-            return await _Tools.set_layer_properties(name=old_name, new_name=new_name)
-
-        @self.server.tool
-        async def set_layer_properties(
-            name: str,
-            visible: bool | None = None,
-            opacity: float | None = None,
-            colormap: str | None = None,
-        ):
-            """Set properties on a layer."""
-            return await _Tools.set_layer_properties(
-                name=name, visible=visible, opacity=opacity, colormap=colormap
-            )
-
-        @self.server.tool
-        async def reset_view():
-            """Reset the camera view to fit data."""
-            return await _Tools.reset_view()
-
-        @self.server.tool
-        async def set_zoom(zoom: float):
-            """Set camera zoom factor."""
-            return await _Tools.set_camera(zoom=zoom)
-
-        @self.server.tool
-        async def set_ndisplay(ndisplay: int):
-            """Set number of displayed dimensions (2 or 3)."""
-            return await _Tools.set_ndisplay(ndisplay)
-
-        @self.server.tool
-        async def screenshot(canvas_only: bool | str = True) -> ImageContent:
-            """Take a screenshot and return as base64 PNG."""
-            return await _Tools.screenshot(canvas_only=canvas_only)
-
-        @self.server.tool
-        async def timelapse_screenshot(
-            axis: int,
-            slice_range: str,
-            canvas_only: bool | str = True,
-            interpolate_to_fit: bool = False,
-        ) -> list[ImageContent]:
-            """Capture a series of screenshots while sweeping a dims axis with optional downsampling to fit size cap."""
-            return await _Tools.timelapse_screenshot(
-                axis=axis,
-                slice_range=slice_range,
-                canvas_only=canvas_only,
-                interpolate_to_fit=interpolate_to_fit,
-            )
-
-        @self.server.tool
-        async def execute_code(code: str):
-            """Execute Python code with access to the viewer."""
+            # Validate only one data source
+            sources = sum([data_var is not None, data is not None, path is not None])
+            if sources > 1:
+                return {
+                    "status": "error",
+                    "message": "Provide only ONE of 'path', 'data', or 'data_var', not multiple.",
+                }
 
-            def execute():
-                self._exec_globals.setdefault("__builtins__", __builtins__)
-                self._exec_globals["viewer"] = self.viewer
-                self._exec_globals.setdefault("napari", None)
-                self._exec_globals.setdefault("np", np)
+            # Resolve data
+            resolved: Any | None = None
+            if path:
+                if lt not in ("image", "labels"):
+                    return {
+                        "status": "error",
+                        "message": f"'path' is only supported for image/labels, not {layer_type}",
+                    }
+                from pathlib import Path as _Path
 
-                stdout_buf = StringIO()
-                stderr_buf = StringIO()
-                result_repr = None
+                import imageio.v3 as iio
 
+                p = _Path(path).expanduser().resolve(strict=False)
+                if not p.exists():
+                    return {
+                        "status": "error",
+                        "message": f"File not found: {p}",
+                    }
                 try:
-                    with (
-                        contextlib.redirect_stdout(stdout_buf),
-                        contextlib.redirect_stderr(stderr_buf),
-                    ):
-                        import ast
-
-                        parsed = ast.parse(code, mode="exec")
-                        if parsed.body and isinstance(parsed.body[-1], ast.Expr):
-                            if len(parsed.body) > 1:
-                                exec_ast = ast.Module(
-                                    body=parsed.body[:-1], type_ignores=[]
-                                )
-                                exec(
-                                    compile(exec_ast, "<bridge-exec>", "exec"),
-                                    self._exec_globals,
-                                )
-                            last_expr = ast.Expression(body=parsed.body[-1].value)
-                            value = eval(
-                                compile(last_expr, "<bridge-eval>", "eval"),
-                                self._exec_globals,
-                            )
-                            result_repr = repr(value)
-                        else:
-                            exec(
-                                compile(parsed, "<bridge-exec>", "exec"),
-                                self._exec_globals,
-                            )
-
+                    resolved = iio.imread(str(p))
+                except Exception as e:
+                    return {
+                        "status": "error",
+                        "message": f"Failed to read file: {e}",
+                    }
+            elif data_var:
+                if data_var not in self.state.exec_globals:
                     return {
-                        "status": "ok",
-                        **({"result_repr": result_repr} if result_repr else {}),
-                        "stdout": stdout_buf.getvalue(),
-                        "stderr": stderr_buf.getvalue(),
+                        "status": "error",
+                        "message": f"Variable '{data_var}' not found in execution namespace",
                     }
-                except Exception:
-                    import traceback
+                resolved = self.state.exec_globals[data_var]
+            elif data is not None:
+                resolved = data
 
-                    tb = traceback.format_exc()
+            if resolved is None:
+                if lt == "surface":
                     return {
                         "status": "error",
-                        "stdout": stdout_buf.getvalue(),
-                        "stderr": stderr_buf.getvalue() + tb,
+                        "message": "'data_var' is required for surface layers.",
                     }
+                return {
+                    "status": "error",
+                    "message": "Provide 'path', 'data', or 'data_var'.",
+                }
 
-            return self.qt_bridge.run_in_main_thread(execute)
-
-        @self.server.tool
-        async def install_packages(
-            packages: list[str],
-            upgrade: bool | None = False,
-            no_deps: bool | None = False,
-            index_url: str | None = None,
-            extra_index_url: str | None = None,
-            pre: bool | None = False,
-            line_limit: int | str = 30,
-            timeout: int = 240,
-        ):
-            """Install Python packages using pip.
+            def _do_add():
+                return create_layer_on_viewer(
+                    self.viewer,
+                    resolved,
+                    lt,
+                    name=name,
+                    colormap=colormap,
+                    blending=blending,
+                    channel_axis=channel_axis,
+                    size=size,
+                    shape_type=shape_type,
+                    edge_color=edge_color,
+                    face_color=face_color,
+                    edge_width=edge_width,
+                )
+
+            try:
+                return self.qt_bridge.run_in_main_thread(_do_add)
+            except Exception as e:
+                return {
+                    "status": "error",
+                    "message": f"Failed to add {layer_type} layer: {e}",
+                }
 
-            Install packages into the currently running server environment.
+        @self.server.tool()
+        async def execute_code(code: str, line_limit: int | str = 30):
+            """Execute Python code with access to the viewer.
+
+            Parameters
+            ----------
+            code : str
+                Python code string. The value of the last expression (if any)
+                is returned as 'result_repr'.
+            line_limit : int, default=30
+                Maximum number of output lines to return. Use -1 for unlimited.
             """
-            # Delegate to shared implementation (no Qt main-thread requirement)
-            return await _Tools.install_packages(
-                packages=packages,
-                upgrade=upgrade,
-                no_deps=no_deps,
-                index_url=index_url,
-                extra_index_url=extra_index_url,
-                pre=pre,
+
+            def _run_on_qt():
+                """Run code on Qt main thread using shared helper."""
+                import napari
+
+                self.state.exec_globals.setdefault("__builtins__", __builtins__)
+                self.state.exec_globals["viewer"] = self.viewer
+                self.state.exec_globals.setdefault("napari", napari)
+                self.state.exec_globals.setdefault("np", np)
+                return run_code(
+                    code, self.state.exec_globals, source_label="<bridge-exec>"
+                )
+
+            try:
+                stdout_full, stderr_full, result_repr, error = (
+                    self.qt_bridge.run_in_main_thread(_run_on_qt, timeout=600.0)
+                )
+            except TimeoutError:
+                output_id = await self.state.store_output(
+                    tool_name="execute_code",
+                    stdout="",
+                    stderr="execute_code timed out after 600s.",
+                    code=code,
+                    error=True,
+                )
+                return {
+                    "status": "error",
+                    "output_id": output_id,
+                    "stdout": "",
+                    "stderr": (
+                        "execute_code timed out after 600s. "
+                        "The code may still be running on the napari main thread. "
+                        "To avoid this, break your computation into smaller steps "
+                        "or move heavy processing to a background thread."
+                    ),
+                }
+
+            status = "error" if error else "ok"
+            output_id = await self.state.store_output(
+                tool_name="execute_code",
+                stdout=stdout_full,
+                stderr=stderr_full,
+                result_repr=result_repr,
+                code=code,
+                **({"error": True} if error else {}),
+            )
+
+            return build_truncated_response(
+                status=status,
+                output_id=output_id,
+                stdout_full=stdout_full,
+                stderr_full=stderr_full,
+                result_repr=result_repr,
                 line_limit=line_limit,
-                timeout=timeout,
+                error=error,
             )
 
     def _run_server_thread(self):
@@ -376,7 +343,6 @@ def _run_server_thread(self):
         asyncio.set_event_loop(self.loop)
 
         try:
-            # Run the server synchronously (FastMCP handles the async internally)
             self.server.run(
                 transport="http", host="127.0.0.1", port=self.port, path="/mcp"
             )
@@ -387,7 +353,6 @@ def _run_server_thread(self):
 
     def start(self):
         """Start the MCP server in a background thread."""
-        # Thread-safe check and creation
         if self.thread is not None and self.thread.is_alive():
             return False
 
@@ -401,68 +366,15 @@ def stop(self):
             try:
                 self.loop.call_soon_threadsafe(self.loop.stop)
             except RuntimeError:
-                pass  # Loop already stopped/closed
+                pass
 
         if self.thread:
             self.thread.join(timeout=2)
             self.thread = None
 
-        # Clean up loop reference
         self.loop = None
         return True
 
-    # Method wrappers to expose tools as direct methods for easier testing
-    async def session_information(self):
-        """Get session information via the registered tool."""
-        tool = await self.server.get_tool("session_information")
-        return await tool.fn()
-
-    async def list_layers(self):
-        """List layers via the registered tool."""
-        tool = await self.server.get_tool("list_layers")
-        return await tool.fn()
-
-    async def execute_code(self, code: str):
-        """Execute code via the registered tool."""
-        tool = await self.server.get_tool("execute_code")
-        return await tool.fn(code)
-
-    async def screenshot(self, canvas_only: bool = True) -> dict[str, str]:
-        """Take screenshot via the registered tool."""
-        tool = await self.server.get_tool("screenshot")
-        return await tool.fn(canvas_only)
-
-    async def timelapse_screenshot(
-        self,
-        axis: int,
-        slice_range: str,
-        canvas_only: bool = True,
-        interpolate_to_fit: bool = False,
-    ) -> list[dict[str, str]]:
-        """Timelapse screenshot via the registered tool."""
-        tool = await self.server.get_tool("timelapse_screenshot")
-        return await tool.fn(axis, slice_range, canvas_only, interpolate_to_fit)
-
-    async def add_image(self, **kwargs):
-        """Add image via the registered tool."""
-        tool = await self.server.get_tool("add_image")
-        return await tool.fn(**kwargs)
-
-    async def add_points(self, **kwargs):
-        """Add points via the registered tool."""
-        tool = await self.server.get_tool("add_points")
-        return await tool.fn(**kwargs)
-
-    async def remove_layer(self, name: str):
-        """Remove layer via the registered tool."""
-        tool = await self.server.get_tool("remove_layer")
-        return await tool.fn(name)
-
-    async def install_packages(self, **kwargs):
-        """Install packages via the registered tool."""
-        tool = await self.server.get_tool("install_packages")
-        return await tool.fn(**kwargs)
-
     @property
     def is_running(self) -> bool:
         """Check if server is running."""
diff --git a/src/napari_mcp/cli/install/base.py b/src/napari_mcp/cli/install/base.py
index 0d1bfab..6bbf67a 100644
--- a/src/napari_mcp/cli/install/base.py
+++ b/src/napari_mcp/cli/install/base.py
@@ -29,6 +29,7 @@ def __init__(
         server_name: str = "napari-mcp",
         persistent: bool = False,
         python_path: str | None = None,
+        napari_backend: str | None = None,
         force: bool = False,
         backup: bool = True,
         dry_run: bool = False,
@@ -45,6 +46,8 @@ def __init__(
             Use Python path instead of uv run.
         python_path : Optional[str]
             Custom Python executable path.
+        napari_backend : Optional[str]
+            Optional napari requirement to add to uv-based installs.
         force : bool
             Skip prompts and force update.
         backup : bool
@@ -57,6 +60,7 @@ def __init__(
         self.server_name = server_name
         self.persistent = persistent
         self.python_path = python_path
+        self.napari_backend = napari_backend
         self.force = force
         self.backup = backup
         self.dry_run = dry_run
@@ -80,7 +84,7 @@ def get_extra_config(self) -> dict[str, Any]:
         dict[str, Any]
             Extra configuration fields (e.g., timeout for Gemini).
         """
-        return {}
+        ...
 
     def validate_environment(self) -> bool:
         """Validate the installation environment.
@@ -140,8 +144,15 @@ def install(self) -> tuple[bool, str]:
                 return False, "User cancelled update"
 
             # Build server configuration
+            build_kwargs: dict[str, Any] = {}
+            if self.napari_backend is not None:
+                build_kwargs["napari_requirement"] = self.napari_backend
+
             server_config = build_server_config(
-                self.persistent, self.python_path, self.get_extra_config()
+                self.persistent,
+                self.python_path,
+                self.get_extra_config(),
+                **build_kwargs,
             )
 
             # Show what will be installed
@@ -191,11 +202,10 @@ def uninstall(self) -> tuple[bool, str]:
             config = read_json_config(config_path)
 
             # Check if server exists
-            if (
-                not check_existing_server(config, self.server_name)
-                and not self.force
-                and not prompt_update_existing(self.app_name, config_path)
-            ):
+            if not check_existing_server(config, self.server_name):
+                console.print(
+                    f"[yellow]napari-mcp server '{self.server_name}' not found in {self.app_name} configuration[/yellow]"
+                )
                 return False, f"Server '{self.server_name}' not found in configuration"
 
             if self.dry_run:
diff --git a/src/napari_mcp/cli/install/cline_cursor.py b/src/napari_mcp/cli/install/cline_cursor.py
index 01ee377..3663162 100644
--- a/src/napari_mcp/cli/install/cline_cursor.py
+++ b/src/napari_mcp/cli/install/cline_cursor.py
@@ -76,5 +76,5 @@ def show_post_install_message(self) -> None:
             "\n[yellow]Note: This configures Cline extension in Cursor IDE[/yellow]"
         )
         console.print(
-            "[yellow]For Cursor's native MCP support, use: napari-mcp-install cursor[/yellow]"
+            "[yellow]For Cursor's native MCP support, use: napari-mcp-install install cursor[/yellow]"
         )
diff --git a/src/napari_mcp/cli/install/codex_cli.py b/src/napari_mcp/cli/install/codex_cli.py
index 06c209c..53e5512 100644
--- a/src/napari_mcp/cli/install/codex_cli.py
+++ b/src/napari_mcp/cli/install/codex_cli.py
@@ -1,12 +1,21 @@
 """Codex CLI installer for napari-mcp."""
 
+import sys
 from pathlib import Path
 from typing import Any
 
 from rich.console import Console
 
 from .base import BaseInstaller
-from .utils import expand_path
+from .utils import build_server_config, expand_path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
 
 console = Console()
 
@@ -44,14 +53,7 @@ def install(self):
 
         Override to handle TOML format instead of JSON.
         """
-        try:
-            import toml
-        except ImportError:
-            console.print(
-                "[red]Error: toml package is required for Codex CLI configuration[/red]"
-            )
-            console.print("[yellow]Install it with: pip install toml[/yellow]")
-            return False, "Missing toml package"
+        import toml as toml_writer
 
         try:
             # Get configuration path
@@ -67,8 +69,8 @@ def install(self):
 
             # Read existing configuration or create new
             if config_path.exists():
-                with open(config_path) as f:
-                    config = toml.load(f)
+                with open(config_path, "rb") as f:
+                    config = tomllib.load(f)
             else:
                 config = {}
 
@@ -85,20 +87,16 @@ def install(self):
                     return False, "User cancelled update"
 
             # Build server configuration for TOML format
-            if self.persistent or self.python_path:
-                from .utils import get_python_executable
-
-                command, _ = get_python_executable(self.persistent, self.python_path)
-                server_config = {
-                    "command": command,
-                    "args": ["-m", "napari_mcp.server"],
-                }
-            else:
-                # Use uv for ephemeral environment
-                server_config = {
-                    "command": "uv",
-                    "args": ["run", "--with", "napari-mcp", "napari-mcp"],
-                }
+            build_kwargs: dict[str, Any] = {}
+            if self.napari_backend is not None:
+                build_kwargs["napari_requirement"] = self.napari_backend
+
+            server_config = build_server_config(
+                self.persistent,
+                self.python_path,
+                self.get_extra_config(),
+                **build_kwargs,
+            )
 
             # Show what will be installed
             console.print("\n[cyan]Configuration to install:[/cyan]")
@@ -118,10 +116,10 @@ def install(self):
 
             # Write TOML configuration
             with open(config_path, "w") as f:
-                toml.dump(config, f)
+                toml_writer.dump(config, f)
 
             console.print(
-                "\n[green]✓ Successfully installed napari-mcp for Codex CLI[/green]"
+                "\n[green]\u2713 Successfully installed napari-mcp for Codex CLI[/green]"
             )
             self.show_post_install_message()
             return True, "Installation successful"
@@ -135,14 +133,7 @@ def uninstall(self):
 
         Override to handle TOML format instead of JSON.
         """
-        try:
-            import toml
-        except ImportError:
-            console.print(
-                "[red]Error: toml package is required for Codex CLI configuration[/red]"
-            )
-            console.print("[yellow]Install it with: pip install toml[/yellow]")
-            return False, "Missing toml package"
+        import toml as toml_writer
 
         try:
             # Get configuration path
@@ -152,8 +143,8 @@ def uninstall(self):
                 return False, f"Configuration file not found: {config_path}"
 
             # Read configuration
-            with open(config_path) as f:
-                config = toml.load(f)
+            with open(config_path, "rb") as f:
+                config = tomllib.load(f)
 
             # Check if server exists
             server_name = "napari_mcp"
@@ -175,10 +166,10 @@ def uninstall(self):
 
             # Write TOML configuration
             with open(config_path, "w") as f:
-                toml.dump(config, f)
+                toml_writer.dump(config, f)
 
             console.print(
-                "\n[green]✓ Successfully uninstalled napari-mcp from Codex CLI[/green]"
+                "\n[green]\u2713 Successfully uninstalled napari-mcp from Codex CLI[/green]"
             )
             return True, "Uninstallation successful"
 
diff --git a/src/napari_mcp/cli/install/cursor.py b/src/napari_mcp/cli/install/cursor.py
index f6b67a6..e197005 100644
--- a/src/napari_mcp/cli/install/cursor.py
+++ b/src/napari_mcp/cli/install/cursor.py
@@ -20,6 +20,7 @@ def __init__(
         server_name: str = "napari-mcp",
         persistent: bool = False,
         python_path: str | None = None,
+        napari_backend: str | None = None,
         force: bool = False,
         backup: bool = True,
         dry_run: bool = False,
@@ -36,6 +37,8 @@ def __init__(
             Use Python path instead of uv run.
         python_path : Optional[str]
             Custom Python executable path.
+        napari_backend : Optional[str]
+            Optional napari requirement to add to uv-based installs.
         force : bool
             Skip prompts and force update.
         backup : bool
@@ -48,13 +51,14 @@ def __init__(
             Project directory for project-specific installation.
         """
         super().__init__(
-            "cursor",
-            server_name,
-            persistent,
-            python_path,
-            force,
-            backup,
-            dry_run,
+            app_key="cursor",
+            server_name=server_name,
+            persistent=persistent,
+            python_path=python_path,
+            napari_backend=napari_backend,
+            force=force,
+            backup=backup,
+            dry_run=dry_run,
         )
         self.global_install = global_install
         self.project_dir = project_dir
diff --git a/src/napari_mcp/cli/install/gemini_cli.py b/src/napari_mcp/cli/install/gemini_cli.py
index 4dfb763..06d4037 100644
--- a/src/napari_mcp/cli/install/gemini_cli.py
+++ b/src/napari_mcp/cli/install/gemini_cli.py
@@ -20,6 +20,7 @@ def __init__(
         server_name: str = "napari-mcp",
         persistent: bool = False,
         python_path: str | None = None,
+        napari_backend: str | None = None,
         force: bool = False,
         backup: bool = True,
         dry_run: bool = False,
@@ -36,6 +37,8 @@ def __init__(
             Use Python path instead of uv run.
         python_path : Optional[str]
             Custom Python executable path.
+        napari_backend : Optional[str]
+            Optional napari requirement to add to uv-based installs.
         force : bool
             Skip prompts and force update.
         backup : bool
@@ -48,13 +51,14 @@ def __init__(
             Project directory for project-specific installation.
         """
         super().__init__(
-            "gemini",
-            server_name,
-            persistent,
-            python_path,
-            force,
-            backup,
-            dry_run,
+            app_key="gemini",
+            server_name=server_name,
+            persistent=persistent,
+            python_path=python_path,
+            napari_backend=napari_backend,
+            force=force,
+            backup=backup,
+            dry_run=dry_run,
         )
         self.global_install = global_install
         self.project_dir = project_dir
diff --git a/src/napari_mcp/cli/install/utils.py b/src/napari_mcp/cli/install/utils.py
index a2b4a59..ea31775 100644
--- a/src/napari_mcp/cli/install/utils.py
+++ b/src/napari_mcp/cli/install/utils.py
@@ -10,11 +10,14 @@
 from typing import Any
 
 from rich.console import Console
-from rich.prompt import Confirm
+from rich.prompt import Confirm, Prompt
 from rich.table import Table
 
 console = Console()
 
+DEFAULT_NAPARI_BACKEND = "all"
+NAPARI_BACKEND_CHOICES = ("all", "pyqt5", "pyqt6", "pyside", "none", "other")
+
 
 def get_platform() -> str:
     """Get the current platform.
@@ -65,6 +68,13 @@ def read_json_config(path: Path) -> dict[str, Any]:
     -------
     dict[str, Any]
         Configuration dictionary, or empty dict if file doesn't exist.
+
+    Raises
+    ------
+    json.JSONDecodeError
+        If the file contains invalid JSON.
+    OSError
+        If the file cannot be read.
     """
     if not path.exists():
         return {}
@@ -74,7 +84,11 @@ def read_json_config(path: Path) -> dict[str, Any]:
             return json.load(f, object_pairs_hook=OrderedDict)
     except (OSError, json.JSONDecodeError) as e:
         console.print(f"[red]Error reading {path}: {e}[/red]")
-        return {}
+        console.print(
+            "[red]Cannot proceed with a corrupted config file. "
+            "Please fix or remove it manually.[/red]"
+        )
+        raise
 
 
 def write_json_config(path: Path, config: dict[str, Any], backup: bool = True) -> bool:
@@ -160,6 +174,8 @@ def build_server_config(
     persistent: bool = False,
     python_path: str | None = None,
     extra_args: dict[str, Any] | None = None,
+    *,
+    napari_requirement: str | None = None,
 ) -> dict[str, Any]:
     """Build the server configuration for napari-mcp.
 
@@ -171,6 +187,8 @@ def build_server_config(
         Custom Python executable path.
     extra_args : Optional[dict[str, Any]]
         Additional configuration fields (e.g., for Gemini CLI).
+    napari_requirement : Optional[str]
+        Optional napari dependency to add to uv-based installs.
 
     Returns
     -------
@@ -185,6 +203,15 @@ def build_server_config(
             "command": "uv",
             "args": ["run", "--with", "napari-mcp", "napari-mcp"],
         }
+        if napari_requirement:
+            config["args"] = [
+                "run",
+                "--with",
+                "napari-mcp",
+                "--with",
+                napari_requirement,
+                "napari-mcp",
+            ]
     else:
         # Persistent Python environment
         config = {"command": command, "args": ["-m", "napari_mcp.server"]}
@@ -213,9 +240,6 @@ def check_existing_server(
     bool
         True if server exists, False otherwise.
     """
-    if "mcpServers" not in config:
-        return False
-
     return server_name in config.get("mcpServers", {})
 
 
@@ -242,6 +266,127 @@ def prompt_update_existing(app_name: str, config_path: Path) -> bool:
     )
 
 
+def normalize_napari_requirement(selection: str | None) -> str | None:
+    """Normalize a napari backend selection into a package requirement.
+
+    Parameters
+    ----------
+    selection : Optional[str]
+        Backend preset, ``none``, or a custom napari requirement.
+
+    Returns
+    -------
+    Optional[str]
+        Normalized requirement string, or None when no extra should be added.
+    """
+    if selection is None:
+        return None
+
+    cleaned = selection.strip()
+    if not cleaned:
+        return None
+
+    lowered = cleaned.lower()
+    preset_requirements = {
+        "all": "napari[all]",
+        "pyqt5": "napari[pyqt5]",
+        "pyqt6": "napari[pyqt6]",
+        "pyside": "napari[pyside]",
+    }
+
+    if lowered == "none":
+        return None
+    if lowered in preset_requirements:
+        return preset_requirements[lowered]
+    if cleaned.startswith("napari"):
+        return cleaned
+    return f"napari[{cleaned}]"
+
+
+def prompt_napari_requirement() -> str | None:
+    """Prompt for a napari backend requirement.
+
+    Returns
+    -------
+    Optional[str]
+        Normalized napari requirement, or None when the user selects no backend.
+    """
+    console.print(
+        "\n[cyan]Optional: add napari with a GUI backend to the uv environment[/cyan]"
+    )
+    selection = Prompt.ask(
+        "Choose a napari backend",
+        choices=list(NAPARI_BACKEND_CHOICES),
+        default=DEFAULT_NAPARI_BACKEND,
+    )
+
+    if selection == "other":
+        return prompt_custom_napari_requirement()
+
+    return normalize_napari_requirement(selection)
+
+
+def prompt_custom_napari_requirement() -> str | None:
+    """Prompt for a custom napari requirement.
+
+    Returns
+    -------
+    Optional[str]
+        Normalized custom napari requirement, or None when left blank.
+    """
+    console.print(
+        "[dim]Enter a napari extra like 'pyside6' or a full requirement like 'napari[pyside6]'.[/dim]"
+    )
+    custom_value = Prompt.ask("Custom napari backend", default="").strip()
+    if not custom_value:
+        return None
+    return normalize_napari_requirement(custom_value)
+
+
+def resolve_napari_requirement(
+    selection: str | None,
+    *,
+    prompt_user: bool = False,
+) -> str | None:
+    """Resolve a napari backend selection into a package requirement.
+
+    Parameters
+    ----------
+    selection : Optional[str]
+        Backend preset, ``none``, ``other``, or a custom napari requirement.
+    prompt_user : bool
+        Whether interactive prompting is allowed when needed.
+
+    Returns
+    -------
+    Optional[str]
+        Normalized requirement string, or None when no extra should be added.
+
+    Raises
+    ------
+    ValueError
+        If ``other`` is requested without interactive prompting.
+    """
+    if selection is None:
+        if prompt_user:
+            return prompt_napari_requirement()
+        return normalize_napari_requirement(DEFAULT_NAPARI_BACKEND)
+
+    cleaned = selection.strip()
+    if not cleaned:
+        return normalize_napari_requirement(DEFAULT_NAPARI_BACKEND)
+
+    if cleaned.lower() == "other":
+        if prompt_user:
+            return prompt_custom_napari_requirement()
+        raise ValueError(
+            "Custom backend selection requires interactive input. "
+            "Pass a specific value to --backend instead."
+        )
+
+    return normalize_napari_requirement(cleaned)
+
+
 def show_installation_summary(installations: dict[str, tuple[bool, str]]) -> None:
     """Show a summary table of installation results.
 
@@ -303,28 +448,6 @@ def validate_python_environment(python_path: str) -> bool:
         return False
 
 
-def detect_python_environment() -> str | None:
-    """Detect the current Python environment type.
-
-    Returns
-    -------
-    Optional[str]
-        Environment type ('conda', 'venv', 'system'), or None if detection fails.
-    """
-    # Check for Conda environment
-    if os.environ.get("CONDA_DEFAULT_ENV"):
-        return "conda"
-
-    # Check for virtual environment
-    if hasattr(sys, "real_prefix") or (
-        hasattr(sys, "base_prefix") and sys.base_prefix != sys.prefix
-    ):
-        return "venv"
-
-    # Otherwise it's likely system Python
-    return "system"
-
-
 def get_app_display_name(app_key: str) -> str:
     """Get the display name for an application.
 
diff --git a/src/napari_mcp/cli/main.py b/src/napari_mcp/cli/main.py
index c078211..db49b6e 100644
--- a/src/napari_mcp/cli/main.py
+++ b/src/napari_mcp/cli/main.py
@@ -1,12 +1,14 @@
 """Main CLI entry point for napari-mcp installer."""
 
+import sys as _sys
+from enum import Enum
 from typing import Annotated
 
 import typer
 from rich.console import Console
 from rich.table import Table
 
-from .install import (
+from .install import (  # noqa: F401 - accessed via _get_installer_class
     ClaudeCodeInstaller,
     ClaudeDesktopInstaller,
     ClineCursorInstaller,
@@ -15,7 +17,11 @@
     CursorInstaller,
     GeminiCLIInstaller,
 )
-from .install.utils import get_app_display_name, show_installation_summary
+from .install.utils import (
+    get_app_display_name,
+    resolve_napari_requirement,
+    show_installation_summary,
+)
 
 app = typer.Typer(
     name="napari-mcp-install",
@@ -25,6 +31,41 @@
 console = Console()
 
 
+class InstallTarget(str, Enum):
+    """Supported installation targets."""
+
+    CLAUDE_DESKTOP = "claude-desktop"
+    CLAUDE_CODE = "claude-code"
+    CURSOR = "cursor"
+    CLINE_VSCODE = "cline-vscode"
+    CLINE_CURSOR = "cline-cursor"
+    GEMINI = "gemini"
+    CODEX = "codex"
+    ALL = "all"
+
+
+# Maps target names to class attribute names in this module (looked up at
+# call time so that unittest.mock.patch works correctly).
+_INSTALLER_CLASS_NAMES = {
+    InstallTarget.CLAUDE_DESKTOP: "ClaudeDesktopInstaller",
+    InstallTarget.CLAUDE_CODE: "ClaudeCodeInstaller",
+    InstallTarget.CURSOR: "CursorInstaller",
+    InstallTarget.CLINE_VSCODE: "ClineVSCodeInstaller",
+    InstallTarget.CLINE_CURSOR: "ClineCursorInstaller",
+    InstallTarget.GEMINI: "GeminiCLIInstaller",
+    InstallTarget.CODEX: "CodexCLIInstaller",
+}
+
+
+def _get_installer_class(target: InstallTarget):
+    """Look up installer class by name (supports mock patching)."""
+    return getattr(_sys.modules[__name__], _INSTALLER_CLASS_NAMES[target])
+
+
+# Targets that support --global / --project options
+PROJECT_TARGETS = {InstallTarget.CURSOR, InstallTarget.GEMINI}
+
+
 def version_callback(value: bool):
     """Show version and exit."""
     if value:
@@ -49,44 +90,45 @@ def main(
     """napari-mcp installer - Easy setup for LLM applications."""
 
 
-@app.command("claude-desktop")
-def install_claude_desktop(
-    persistent: Annotated[
-        bool,
-        typer.Option("--persistent", help="Use Python path instead of uv run"),
-    ] = False,
-    python_path: Annotated[
-        str | None,
-        typer.Option("--python-path", help="Custom Python executable path"),
-    ] = None,
-    force: Annotated[
-        bool,
-        typer.Option("--force", "-f", help="Skip prompts and force update"),
-    ] = False,
-    backup: Annotated[
-        bool,
-        typer.Option("--backup/--no-backup", help="Create backup before updating"),
-    ] = True,
-    dry_run: Annotated[
-        bool,
-        typer.Option("--dry-run", help="Preview changes without applying"),
-    ] = False,
+def _create_installer(
+    target: InstallTarget,
+    *,
+    persistent: bool = False,
+    python_path: str | None = None,
+    napari_backend: str | None = None,
+    force: bool = False,
+    backup: bool = True,
+    dry_run: bool = False,
+    global_install: bool = False,
+    project_dir: str | None = None,
 ):
-    """Install napari-mcp for Claude Desktop."""
-    installer = ClaudeDesktopInstaller(
-        persistent=persistent,
-        python_path=python_path,
-        force=force,
-        backup=backup,
-        dry_run=dry_run,
-    )
-    success, message = installer.install()
-    if not success:
-        raise typer.Exit(1)
+    """Create an installer instance for the given target."""
+    installer_class = _get_installer_class(target)
+    kwargs = {
+        "persistent": persistent,
+        "python_path": python_path,
+        "napari_backend": napari_backend,
+        "force": force,
+        "backup": backup,
+        "dry_run": dry_run,
+    }
+    if target in PROJECT_TARGETS:
+        kwargs["global_install"] = global_install
+        if project_dir is not None:
+            kwargs["project_dir"] = project_dir
+    elif global_install or project_dir:
+        console.print(
+            f"[yellow]Warning: --global/--project ignored for {target.value}[/yellow]"
+        )
+    return installer_class(**kwargs)
 
 
-@app.command("claude-code")
-def install_claude_code(
+@app.command("install")
+def install(
+    target: Annotated[
+        InstallTarget,
+        typer.Argument(help="Target application to install for"),
+    ],
     persistent: Annotated[
         bool,
         typer.Option("--persistent", help="Use Python path instead of uv run"),
@@ -95,41 +137,15 @@ def install_claude_code(
         str | None,
         typer.Option("--python-path", help="Custom Python executable path"),
     ] = None,
-    force: Annotated[
-        bool,
-        typer.Option("--force", "-f", help="Skip prompts and force update"),
-    ] = False,
-    backup: Annotated[
-        bool,
-        typer.Option("--backup/--no-backup", help="Create backup before updating"),
-    ] = True,
-    dry_run: Annotated[
-        bool,
-        typer.Option("--dry-run", help="Preview changes without applying"),
-    ] = False,
-):
-    """Install napari-mcp for Claude Code CLI."""
-    installer = ClaudeCodeInstaller(
-        persistent=persistent,
-        python_path=python_path,
-        force=force,
-        backup=backup,
-        dry_run=dry_run,
-    )
-    success, message = installer.install()
-    if not success:
-        raise typer.Exit(1)
-
-
-@app.command("cursor")
-def install_cursor(
-    persistent: Annotated[
-        bool,
-        typer.Option("--persistent", help="Use Python path instead of uv run"),
-    ] = False,
-    python_path: Annotated[
+    napari_backend: Annotated[
         str | None,
-        typer.Option("--python-path", help="Custom Python executable path"),
+        typer.Option(
+            "--backend",
+            help=(
+                "Napari backend for uv installs: all, pyqt5, pyqt6, pyside, "
+                "none, or a custom value"
+            ),
+        ),
     ] = None,
     force: Annotated[
         bool,
@@ -145,269 +161,82 @@ def install_cursor(
     ] = False,
     global_install: Annotated[
         bool,
-        typer.Option("--global", help="Install globally instead of project-specific"),
+        typer.Option("--global", help="Install globally (cursor/gemini only)"),
     ] = False,
     project_dir: Annotated[
         str | None,
-        typer.Option("--project", help="Project directory for installation"),
-    ] = None,
-):
-    """Install napari-mcp for Cursor IDE."""
-    installer = CursorInstaller(
-        persistent=persistent,
-        python_path=python_path,
-        force=force,
-        backup=backup,
-        dry_run=dry_run,
-        global_install=global_install,
-        project_dir=project_dir,
-    )
-    success, message = installer.install()
-    if not success:
-        raise typer.Exit(1)
-
-
-@app.command("cline-vscode")
-def install_cline_vscode(
-    persistent: Annotated[
-        bool,
-        typer.Option("--persistent", help="Use Python path instead of uv run"),
-    ] = False,
-    python_path: Annotated[
-        str | None,
-        typer.Option("--python-path", help="Custom Python executable path"),
+        typer.Option("--project", help="Project directory (cursor/gemini only)"),
     ] = None,
-    force: Annotated[
-        bool,
-        typer.Option("--force", "-f", help="Skip prompts and force update"),
-    ] = False,
-    backup: Annotated[
-        bool,
-        typer.Option("--backup/--no-backup", help="Create backup before updating"),
-    ] = True,
-    dry_run: Annotated[
-        bool,
-        typer.Option("--dry-run", help="Preview changes without applying"),
-    ] = False,
 ):
-    """Install napari-mcp for Cline extension in VS Code."""
-    installer = ClineVSCodeInstaller(
-        persistent=persistent,
-        python_path=python_path,
-        force=force,
-        backup=backup,
-        dry_run=dry_run,
-    )
-    success, message = installer.install()
-    if not success:
-        raise typer.Exit(1)
-
-
-@app.command("cline-cursor")
-def install_cline_cursor(
-    persistent: Annotated[
-        bool,
-        typer.Option("--persistent", help="Use Python path instead of uv run"),
-    ] = False,
-    python_path: Annotated[
-        str | None,
-        typer.Option("--python-path", help="Custom Python executable path"),
-    ] = None,
-    force: Annotated[
-        bool,
-        typer.Option("--force", "-f", help="Skip prompts and force update"),
-    ] = False,
-    backup: Annotated[
-        bool,
-        typer.Option("--backup/--no-backup", help="Create backup before updating"),
-    ] = True,
-    dry_run: Annotated[
-        bool,
-        typer.Option("--dry-run", help="Preview changes without applying"),
-    ] = False,
-):
-    """Install napari-mcp for Cline extension in Cursor IDE."""
-    installer = ClineCursorInstaller(
-        persistent=persistent,
-        python_path=python_path,
-        force=force,
-        backup=backup,
-        dry_run=dry_run,
-    )
-    success, message = installer.install()
-    if not success:
-        raise typer.Exit(1)
-
+    """Install napari-mcp for a target application."""
+    resolved_napari_backend = None
+    if persistent or python_path:
+        if napari_backend:
+            console.print(
+                "[yellow]Warning: --backend is ignored when using --persistent or --python-path[/yellow]"
+            )
+    else:
+        try:
+            resolved_napari_backend = resolve_napari_requirement(
+                napari_backend,
+                prompt_user=(
+                    not force and _sys.stdin is not None and _sys.stdin.isatty()
+                ),
+            )
+        except ValueError as exc:
+            console.print(f"[red]{exc}[/red]")
+            raise typer.Exit(1) from exc
 
-@app.command("codex")
-def install_codex(
-    persistent: Annotated[
-        bool,
-        typer.Option("--persistent", help="Use Python path instead of uv run"),
-    ] = False,
-    python_path: Annotated[
-        str | None,
-        typer.Option("--python-path", help="Custom Python executable path"),
-    ] = None,
-    force: Annotated[
-        bool,
-        typer.Option("--force", "-f", help="Skip prompts and force update"),
-    ] = False,
-    backup: Annotated[
-        bool,
-        typer.Option("--backup/--no-backup", help="Create backup before updating"),
-    ] = True,
-    dry_run: Annotated[
-        bool,
-        typer.Option("--dry-run", help="Preview changes without applying"),
-    ] = False,
-):
-    """Install napari-mcp for Codex CLI."""
-    installer = CodexCLIInstaller(
-        persistent=persistent,
-        python_path=python_path,
-        force=force,
-        backup=backup,
-        dry_run=dry_run,
-    )
-    success, message = installer.install()
-    if not success:
-        raise typer.Exit(1)
+    if target == InstallTarget.ALL:
+        console.print(
+            "[bold cyan]Installing napari-mcp for all supported applications...[/bold cyan]\n"
+        )
+        results = {}
+        for app_target in _INSTALLER_CLASS_NAMES:
+            try:
+                display_name = get_app_display_name(app_target.value)
+                console.print(f"[cyan]Installing for {display_name}...[/cyan]")
+                inst = _create_installer(
+                    app_target,
+                    persistent=persistent,
+                    python_path=python_path,
+                    napari_backend=resolved_napari_backend,
+                    force=force,
+                    backup=backup,
+                    dry_run=dry_run,
+                    global_install=app_target in PROJECT_TARGETS,
+                )
+                success, message = inst.install()
+                results[display_name] = (success, message)
+            except Exception as e:
+                results[get_app_display_name(app_target.value)] = (False, str(e))
 
+        show_installation_summary(results)
+        if not all(success for success, _ in results.values()):
+            raise typer.Exit(1)
+        return
 
-@app.command("gemini")
-def install_gemini(
-    persistent: Annotated[
-        bool,
-        typer.Option("--persistent", help="Use Python path instead of uv run"),
-    ] = False,
-    python_path: Annotated[
-        str | None,
-        typer.Option("--python-path", help="Custom Python executable path"),
-    ] = None,
-    force: Annotated[
-        bool,
-        typer.Option("--force", "-f", help="Skip prompts and force update"),
-    ] = False,
-    backup: Annotated[
-        bool,
-        typer.Option("--backup/--no-backup", help="Create backup before updating"),
-    ] = True,
-    dry_run: Annotated[
-        bool,
-        typer.Option("--dry-run", help="Preview changes without applying"),
-    ] = False,
-    global_install: Annotated[
-        bool,
-        typer.Option("--global", help="Install globally instead of project-specific"),
-    ] = False,
-    project_dir: Annotated[
-        str | None,
-        typer.Option("--project", help="Project directory for installation"),
-    ] = None,
-):
-    """Install napari-mcp for Gemini CLI."""
-    installer = GeminiCLIInstaller(
+    inst = _create_installer(
+        target,
         persistent=persistent,
         python_path=python_path,
+        napari_backend=resolved_napari_backend,
         force=force,
         backup=backup,
         dry_run=dry_run,
         global_install=global_install,
         project_dir=project_dir,
     )
-    success, message = installer.install()
+    success, message = inst.install()
     if not success:
         raise typer.Exit(1)
 
 
-@app.command("all")
-def install_all(
-    persistent: Annotated[
-        bool,
-        typer.Option("--persistent", help="Use Python path instead of uv run"),
-    ] = False,
-    python_path: Annotated[
-        str | None,
-        typer.Option("--python-path", help="Custom Python executable path"),
-    ] = None,
-    force: Annotated[
-        bool,
-        typer.Option("--force", "-f", help="Skip prompts and force update"),
-    ] = False,
-    backup: Annotated[
-        bool,
-        typer.Option("--backup/--no-backup", help="Create backup before updating"),
-    ] = True,
-    dry_run: Annotated[
-        bool,
-        typer.Option("--dry-run", help="Preview changes without applying"),
-    ] = False,
-):
-    """Install napari-mcp for all supported applications."""
-    console.print(
-        "[bold cyan]Installing napari-mcp for all supported applications...[/bold cyan]\n"
-    )
-
-    results = {}
-
-    # Install for each application
-    installers = [
-        ("claude-desktop", ClaudeDesktopInstaller),
-        ("claude-code", ClaudeCodeInstaller),
-        ("cursor", CursorInstaller),
-        ("cline-vscode", ClineVSCodeInstaller),
-        ("cline-cursor", ClineCursorInstaller),
-        ("gemini", GeminiCLIInstaller),
-        ("codex", CodexCLIInstaller),
-    ]
-
-    for app_key, installer_class in installers:
-        try:
-            console.print(
-                f"[cyan]Installing for {get_app_display_name(app_key)}...[/cyan]"
-            )
-
-            # Special handling for project-specific installers
-            if app_key in ["cursor", "gemini"]:
-                installer = installer_class(
-                    persistent=persistent,
-                    python_path=python_path,
-                    force=force,
-                    backup=backup,
-                    dry_run=dry_run,
-                    global_install=True,  # Use global for 'all' command
-                )
-            else:
-                installer = installer_class(
-                    persistent=persistent,
-                    python_path=python_path,
-                    force=force,
-                    backup=backup,
-                    dry_run=dry_run,
-                )
-
-            success, message = installer.install()
-            results[get_app_display_name(app_key)] = (success, message)
-
-        except Exception as e:
-            results[get_app_display_name(app_key)] = (False, str(e))
-
-    # Show summary
-    show_installation_summary(results)
-
-    # Exit with error if any failed
-    if not all(success for success, _ in results.values()):
-        raise typer.Exit(1)
-
-
 @app.command("uninstall")
 def uninstall(
-    app_name: Annotated[
-        str,
-        typer.Argument(
-            help="Application to uninstall from (claude-desktop, claude-code, cursor, cline, gemini, all)"
-        ),
+    target: Annotated[
+        InstallTarget,
+        typer.Argument(help="Target application to uninstall from"),
     ],
     force: Annotated[
         bool,
@@ -423,78 +252,42 @@ def uninstall(
     ] = False,
 ):
     """Uninstall napari-mcp from an application."""
-    app_map = {
-        "claude-desktop": ClaudeDesktopInstaller,
-        "claude-code": ClaudeCodeInstaller,
-        "cursor": CursorInstaller,
-        "cline-vscode": ClineVSCodeInstaller,
-        "cline-cursor": ClineCursorInstaller,
-        "gemini": GeminiCLIInstaller,
-        "codex": CodexCLIInstaller,
-    }
-
-    if app_name == "all":
+    if target == InstallTarget.ALL:
         console.print(
             "[bold cyan]Uninstalling napari-mcp from all applications...[/bold cyan]\n"
         )
         results = {}
-
-        for app_key, installer_class in app_map.items():
+        for app_target in _INSTALLER_CLASS_NAMES:
             try:
-                console.print(
-                    f"[cyan]Uninstalling from {get_app_display_name(app_key)}...[/cyan]"
+                display_name = get_app_display_name(app_target.value)
+                console.print(f"[cyan]Uninstalling from {display_name}...[/cyan]")
+                inst = _create_installer(
+                    app_target,
+                    force=force,
+                    backup=backup,
+                    dry_run=dry_run,
+                    global_install=app_target in PROJECT_TARGETS,
                 )
-
-                # Special handling for project-specific installers
-                if app_key in ["cursor", "gemini"]:
-                    installer = installer_class(
-                        force=force,
-                        backup=backup,
-                        dry_run=dry_run,
-                        global_install=True,
-                    )
-                else:
-                    installer = installer_class(
-                        force=force,
-                        backup=backup,
-                        dry_run=dry_run,
-                    )
-
-                success, message = installer.uninstall()
-                results[get_app_display_name(app_key)] = (success, message)
-
+                success, message = inst.uninstall()
+                results[display_name] = (success, message)
             except Exception as e:
-                results[get_app_display_name(app_key)] = (False, str(e))
+                results[get_app_display_name(app_target.value)] = (False, str(e))
 
         show_installation_summary(results)
-
-    elif app_name in app_map:
-        installer_class = app_map[app_name]
-
-        # Special handling for project-specific installers
-        if app_name in ["cursor", "gemini"]:
-            installer = installer_class(
-                force=force,
-                backup=backup,
-                dry_run=dry_run,
-                global_install=True,
-            )
-        else:
-            installer = installer_class(
-                force=force,
-                backup=backup,
-                dry_run=dry_run,
-            )
-
-        success, message = installer.uninstall()
-        if not success:
-            console.print(f"[red]Failed: {message}[/red]")
+        if not all(success for success, _ in results.values()):
             raise typer.Exit(1)
-    else:
-        console.print(f"[red]Unknown application: {app_name}[/red]")
-        console.print(
-            "Available: claude-desktop, claude-code, cursor, cline-vscode, cline-cursor, gemini, codex, all"
-        )
+        return
+
+    inst = _create_installer(
+        target,
+        force=force,
+        backup=backup,
+        dry_run=dry_run,
+        global_install=target in PROJECT_TARGETS,
+    )
+    success, message = inst.uninstall()
+    if not success:
+        console.print(f"[red]Failed: {message}[/red]")
         raise typer.Exit(1)
 
 
@@ -509,64 +302,53 @@ def list_installations():
     table.add_column("Config Path")
     table.add_column("Details")
 
-    # Check each application
-    apps = [
-        ("claude-desktop", ClaudeDesktopInstaller),
-        ("claude-code", ClaudeCodeInstaller),
-        ("cursor", CursorInstaller),
-        ("cline-vscode", ClineVSCodeInstaller),
-        ("cline-cursor", ClineCursorInstaller),
-        ("gemini", GeminiCLIInstaller),
-        ("codex", CodexCLIInstaller),
-    ]
-
-    for app_key, installer_class in apps:
+    for app_target in _INSTALLER_CLASS_NAMES:
+        app_key = app_target.value
         try:
-            # Create installer to get config path (force=True to skip prompts)
-            if app_key in ["cursor", "gemini"]:
-                installer = installer_class(
-                    force=True,  # Skip prompts in list command
-                    global_install=True,
-                )
-            else:
-                installer = installer_class(force=True)  # Skip prompts in list command
+            kwargs = {"force": True}
+            if app_target in PROJECT_TARGETS:
+                kwargs["global_install"] = True
+            installer = _get_installer_class(app_target)(**kwargs)
 
             config_path = installer.get_config_path()
             display_name = get_app_display_name(app_key)
 
             if config_path.exists():
-                # Special handling for Codex CLI which uses TOML
                 if app_key == "codex":
                     try:
-                        import toml
+                        import sys
+
+                        if sys.version_info >= (3, 11):
+                            import tomllib
+                        else:
+                            import tomli as tomllib  # type: ignore[no-redef]
 
-                        with open(config_path) as f:
-                            config = toml.load(f)
-                        # Check for napari_mcp in mcp_servers
+                        with open(config_path, "rb") as f:
+                            config = tomllib.load(f)
                         if (
                             "mcp_servers" in config
                             and "napari_mcp" in config["mcp_servers"]
                         ):
-                            status = "[green]✓[/green]"
+                            status = "[green]\u2713[/green]"
                             details = "Installed"
                         else:
-                            status = "[yellow]○[/yellow]"
+                            status = "[yellow]\u25cb[/yellow]"
                             details = "Config exists, server not configured"
                     except Exception as e:
-                        status = "[red]✗[/red]"
-                        details = f"Error: {str(e)[:30]}"
+                        status = "[red]\u2717[/red]"
+                        details = f"Error: {e}"
                 else:
                     from .install.utils import check_existing_server, read_json_config
 
                     config = read_json_config(config_path)
                     if check_existing_server(config, "napari-mcp"):
-                        status = "[green]✓[/green]"
+                        status = "[green]\u2713[/green]"
                         details = "Installed"
                     else:
-                        status = "[yellow]○[/yellow]"
+                        status = "[yellow]\u25cb[/yellow]"
                         details = "Config exists, server not configured"
             else:
-                status = "[dim]−[/dim]"
+                status = "[dim]\u2212[/dim]"
                 details = "Not configured"
 
             table.add_row(display_name, status, str(config_path), details)
@@ -574,14 +356,14 @@ def list_installations():
         except Exception as e:
             table.add_row(
                 get_app_display_name(app_key),
-                "[red]✗[/red]",
+                "[red]\u2717[/red]",
                 "Error",
                 f"[red]{str(e)}[/red]",
             )
 
     console.print(table)
     console.print(
-        "\n[dim]Legend: ✓ Installed | ○ Partial | − Not configured | ✗ Error[/dim]"
+        "\n[dim]Legend: \u2713 Installed | \u25cb Partial | \u2212 Not configured | \u2717 Error[/dim]"
     )
 
 
diff --git a/src/napari_mcp/output.py b/src/napari_mcp/output.py
new file mode 100644
index 0000000..e839ca9
--- /dev/null
+++ b/src/napari_mcp/output.py
@@ -0,0 +1,35 @@
+"""Output storage and truncation utilities."""
+
+from __future__ import annotations
+
+
+def truncate_output(output: str, line_limit: int) -> tuple[str, bool]:
+    """Truncate output to specified line limit.
+
+    Parameters
+    ----------
+    output : str
+        The output text to truncate.
+    line_limit : int
+        Maximum number of lines to return. If -1, return all lines.
+
+    Returns
+    -------
+    tuple[str, bool]
+        Tuple of (truncated_output, was_truncated).
+    """
+    try:
+        line_limit = int(line_limit)
+    except Exception:
+        line_limit = 30
+    if line_limit < -1:
+        line_limit = -1
+    if line_limit == -1:
+        return output, False
+
+    lines = output.splitlines(keepends=True)
+    if len(lines) <= line_limit:
+        return output, False
+
+    truncated = "".join(lines[:line_limit])
+    return truncated, True
diff --git a/src/napari_mcp/qt_helpers.py b/src/napari_mcp/qt_helpers.py
new file mode 100644
index 0000000..60a8f9c
--- /dev/null
+++ b/src/napari_mcp/qt_helpers.py
@@ -0,0 +1,87 @@
+"""Qt application and event loop management."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from napari_mcp.state import ServerState
+
+
+def ensure_qt_app(state: ServerState) -> Any:
+    """Return the Qt application, creating one if necessary, or a no-op stub."""
+    from qtpy import QtWidgets
+
+    if QtWidgets is None:
+
+        class _StubApp:
+            def processEvents(self, *_: Any) -> None:  # noqa: N802
+                pass
+
+            def setQuitOnLastWindowClosed(self, *_: Any) -> None:  # noqa: N802
+                pass
+
+        if state.qt_app is None:
+            state.qt_app = _StubApp()
+        return state.qt_app
+
+    app = QtWidgets.QApplication.instance()
+    if app is None:
+        state.qt_app = QtWidgets.QApplication([])
+        app = state.qt_app
+    if isinstance(app, QtWidgets.QApplication):
+        try:
+            app.setQuitOnLastWindowClosed(False)
+        except Exception:
+            pass
+    return app
+
+
+def connect_window_destroyed_signal(state: ServerState, viewer: Any) -> None:
+    """Connect to the Qt window destroyed signal to clear the viewer."""
+    if state.window_close_connected:
+        return
+    try:
+        qt_win = viewer.window._qt_window  # type: ignore[attr-defined]
+
+        def _on_destroyed(*_args: Any) -> None:
+            state.viewer = None
+            state.window_close_connected = False
+            state.request_shutdown()
+
+        qt_win.destroyed.connect(_on_destroyed)  # type: ignore[attr-defined]
+        state.window_close_connected = True
+    except Exception:
+        pass
+
+
+def process_events(state: ServerState, cycles: int = 2) -> None:
+    """Process pending Qt events."""
+    app = ensure_qt_app(state)
+    for _ in range(max(1, cycles)):
+        app.processEvents()
+
+
+async def qt_event_pump(state: ServerState) -> None:
+    """Periodically process Qt events so the GUI remains responsive."""
+    try:
+        while True:
+            try:
+                process_events(state, 2)
+            except Exception:
+                pass  # Don't crash the pump on transient Qt errors
+            await asyncio.sleep(0.01)
+    except asyncio.CancelledError:
+        pass
+
+
+def ensure_viewer(state: ServerState) -> Any:
+    """Create or return the napari viewer singleton."""
+    import napari
+
+    ensure_qt_app(state)
+    if state.viewer is None:
+        state.viewer = napari.Viewer()
+        connect_window_destroyed_signal(state, state.viewer)
+    return state.viewer
diff --git a/src/napari_mcp/server.py b/src/napari_mcp/server.py
index 160a073..0e868d0 100644
--- a/src/napari_mcp/server.py
+++ b/src/napari_mcp/server.py
@@ -1,25 +1,24 @@
 """
 Napari MCP Server.
 
-Exposes a set of MCP tools to control a running napari Viewer: layer control,
-viewer control (zoom, camera, dims), and a screenshot tool returning a PNG image
-as base64.
+Provides ``create_server(state) -> FastMCP`` which builds an MCP server with
+tools defined as closures over a ``ServerState`` instance.  Tool categories
+include session management, layer operations, viewer/camera controls,
+screenshots, code execution, and package installation.
 """
 
 from __future__ import annotations
 
-import ast
 import asyncio
 import asyncio.subprocess
 import contextlib
-import datetime
 import logging
 import math
 import os
+import re
 import shlex
 import sys
-import traceback
-from io import BytesIO, StringIO
+from io import BytesIO
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -29,418 +28,133 @@
 
 
 import fastmcp
-import napari
 import numpy as np
 import typer
-from fastmcp import Client, FastMCP
-from PIL import Image
-from qtpy import QtWidgets
-
-server = FastMCP(
-    "Napari MCP Server",
-    # -- deprecated --
-    # dependencies=["napari", "Pillow", "imageio", "numpy", "qtpy", "PyQt6"],
+from fastmcp import FastMCP
+
+from napari_mcp._helpers import (
+    build_layer_detail,
+    build_truncated_response,
+    create_layer_on_viewer,
+    parse_bool,
+    resolve_layer_type,
+    run_code,
 )
-
-
-# Global GUI singletons (created lazily)
-_qt_app: Any | None = None
-_viewer: Any | None = None
-_viewer_lock: asyncio.Lock = asyncio.Lock()
-_exec_globals: dict[str, Any] = {}
-_qt_pump_task: asyncio.Task | None = None
-_window_close_connected: bool = False
-# Note: _external_client is kept for test compatibility but not used
-# - we create fresh clients for each call
-_external_client: Any = None
-_external_port: int = int(os.environ.get("NAPARI_MCP_BRIDGE_PORT", "9999"))
+from napari_mcp.qt_helpers import (
+    connect_window_destroyed_signal,
+    ensure_qt_app,
+    ensure_viewer,
+    process_events,
+    qt_event_pump,
+)
+from napari_mcp.state import ServerState, StartupMode
 
 # Module logger
 logger = logging.getLogger(__name__)
 
-# Output storage for tool results
-_output_storage: dict[str, dict[str, Any]] = {}
-_output_storage_lock: asyncio.Lock = asyncio.Lock()
-_next_output_id: int = 1
-# Maximum number of output items to retain; set NAPARI_MCP_MAX_OUTPUT_ITEMS<=0 for unlimited
-try:
-    _MAX_OUTPUT_ITEMS: int = int(os.environ.get("NAPARI_MCP_MAX_OUTPUT_ITEMS", "1000"))
-except Exception:
-    _MAX_OUTPUT_ITEMS = 1000
 
+# Regex for validating pip package specifiers (rejects URL-based specifiers)
+_PKG_NAME_RE = re.compile(
+    r"^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?"
+    r"(\[[\w,\s-]+\])?"
+    r"([<>=!~]=?[\w.*,<>=!~\s]*)?$"
+)
 
-def _parse_bool(value: bool | str | None, default: bool = False) -> bool:
-    """Parse a boolean value from various input types.
 
-    Parameters
-    ----------
-    value : bool | str | None
-        Value to parse. Strings like "true", "1", "yes", "on" are considered True.
-    default : bool
-        Default value if input is None.
+# ---------------------------------------------------------------------------
+# Module-level state singleton (for backward compat + test access)
+# ---------------------------------------------------------------------------
 
-    Returns
-    -------
-    bool
-        Parsed boolean value.
-    """
-    if value is None:
-        return default
-    if isinstance(value, bool):
-        return value
-    if isinstance(value, str):
-        return value.lower() in ("true", "1", "yes", "on")
-    return bool(value)
+_state: ServerState | None = None
 
 
-def _truncate_output(output: str, line_limit: int) -> tuple[str, bool]:
-    """Truncate output to specified line limit.
+def get_state() -> ServerState:
+    """Return the current module-level ServerState singleton."""
+    if _state is None:
+        raise RuntimeError("Server state not initialised. Call create_server() first.")
+    return _state
 
-    Parameters
-    ----------
-    output : str
-        The output text to truncate.
-    line_limit : int
-        Maximum number of lines to return. If -1, return all lines.
 
-    Returns
-    -------
-    tuple[str, bool]
-        Tuple of (truncated_output, was_truncated).
-    """
-    # Normalize/validate line_limit
-    try:
-        line_limit = int(line_limit)
-    except Exception:
-        line_limit = 30
-    if line_limit < -1:
-        line_limit = -1
-    if line_limit == -1:
-        return output, False
-
-    lines = output.splitlines(keepends=True)
-    if len(lines) <= line_limit:
-        return output, False
-
-    truncated = "".join(lines[:line_limit])
-    return truncated, True
+# ---------------------------------------------------------------------------
+# Server factory
+# ---------------------------------------------------------------------------
 
 
-async def _store_output(
-    tool_name: str,
-    stdout: str = "",
-    stderr: str = "",
-    result_repr: str | None = None,
-    **metadata: Any,
-) -> str:
-    """Store tool output and return a unique ID.
+def create_server(state: ServerState | None = None) -> FastMCP:
+    """Create a FastMCP server with all tools bound to *state*.
 
     Parameters
     ----------
-    tool_name : str
-        Name of the tool that generated the output.
-    stdout : str
-        Standard output content.
-    stderr : str
-        Standard error content.
-    result_repr : str, optional
-        String representation of the result.
-    **metadata : Any
-        Additional metadata to store with the output.
+    state : ServerState, optional
+        The server state instance. If None, creates a default STANDALONE state.
 
     Returns
     -------
-    str
-        Unique output ID for later retrieval.
-    """
-    global _next_output_id
-
-    async with _output_storage_lock:
-        output_id = str(_next_output_id)
-        _next_output_id += 1
-
-        _output_storage[output_id] = {
-            "tool_name": tool_name,
-            # ISO8601 UTC timestamp for interoperability
-            "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
-            "stdout": stdout,
-            "stderr": stderr,
-            "result_repr": result_repr,
-            **metadata,
-        }
-        # Evict oldest items if exceeding capacity
-        if _MAX_OUTPUT_ITEMS > 0 and len(_output_storage) > _MAX_OUTPUT_ITEMS:
-            overflow = len(_output_storage) - _MAX_OUTPUT_ITEMS
-            # IDs are numeric strings; evict smallest IDs first
-            for victim in sorted(_output_storage.keys(), key=lambda k: int(k))[
-                :overflow
-            ]:
-                _output_storage.pop(victim, None)
-
-        return output_id
-
-
-async def _proxy_to_external(
-    tool_name: str, params: dict[str, Any] | None = None
-) -> dict[str, Any] | None:
-    """Proxy a tool call to an external viewer if available.
-
-    Attempts to contact a running napari-mcp bridge server on the configured
-    port. Returns None if no external server is reachable, so the caller can
-    fall back to the local viewer implementation.
-    """
-    try:
-        client = Client(f"http://localhost:{_external_port}/mcp")
-        async with client:
-            result = await client.call_tool(tool_name, params or {})
-            # return result
-            if hasattr(result, "content"):
-                content = result.content
-                if content[0].type == "text":
-                    import json
-
-                    response = (
-                        content[0].text
-                        if hasattr(content[0], "text")
-                        else str(content[0])
-                    )
-                    try:
-                        return json.loads(response)
-                    except json.JSONDecodeError:
-                        return {
-                            "status": "error",
-                            "message": f"Invalid JSON response: {response}",
-                        }
-                else:
-                    return content
-            return {
-                "status": "error",
-                "message": "Invalid response format from external viewer",
-            }
-    except Exception:
-        return None
-
-
-def _ensure_qt_app() -> Any:
-    """Return a Qt application instance if available, else a no-op stub.
-
-    This allows running in environments without Qt (e.g., some CI or tests
-    that mock napari) while keeping real GUI behavior when Qt is present.
-    """
-    global _qt_app
-    if QtWidgets is None:  # Fallback: provide a minimal stub
-
-        class _StubApp:
-            def processEvents(self, *_: Any) -> None:  # noqa: N802 (Qt-style)
-                pass
-
-            def setQuitOnLastWindowClosed(self, *_: Any) -> None:  # noqa: N802
-                pass
-
-        if _qt_app is None:
-            _qt_app = _StubApp()
-        return _qt_app
-
-    app = QtWidgets.QApplication.instance()
-    if app is None:
-        _qt_app = QtWidgets.QApplication([])
-        app = _qt_app
-    # Ensure the application stays alive even if the last window is closed
-    try:
-        app.setQuitOnLastWindowClosed(False)
-    except Exception:
-        # Best-effort; some headless backends may not support this
-        pass
-    return app
-
-
-async def _detect_external_viewer() -> tuple[Client | None, dict[str, Any] | None]:
-    """Detect if an external napari viewer is available via MCP bridge.
-
-    Returns
-    -------
-    tuple
-        (client, session_info) if external viewer found, (None, None) otherwise
-    """
-    try:
-        client = Client(f"http://localhost:{_external_port}/mcp")
-        async with client:
-            # Try to get session info to verify it's a napari bridge
-            result = await client.call_tool("session_information")
-            if result and hasattr(result, "content"):
-                content = result.content
-                if isinstance(content, list) and len(content) > 0:
-                    info = (
-                        content[0].text
-                        if hasattr(content[0], "text")
-                        else str(content[0])
-                    )
-                    # Parse the JSON response
-                    import json
-
-                    info_dict = json.loads(info) if isinstance(info, str) else info
-                    if info_dict.get("session_type") == "napari_bridge_session":
-                        return client, info_dict
-            return None, None
-    except Exception:
-        return None, None
-
-
-def _detect_external_viewer_sync() -> bool:
-    """Synchronous wrapper to check if external viewer is available.
-
-    In tests, ``_detect_external_viewer`` may be patched to return a plain
-    tuple rather than a coroutine. Handle both cases gracefully.
+    FastMCP
+        Fully configured MCP server with all napari tools registered.
     """
-    try:
-        import asyncio
-        import inspect
-
-        maybe_coro = _detect_external_viewer()
-        if inspect.isawaitable(maybe_coro):
-            loop = asyncio.new_event_loop()
-            try:
-                client, info = loop.run_until_complete(maybe_coro)  # type: ignore[assignment]
-            finally:
-                loop.close()
-        else:
-            # Already a concrete (client, info) tuple from a patch/mocked fn
-            client, info = maybe_coro  # type: ignore[misc]
-        return client is not None
-    except Exception:
-        return False
-
-
-def _ensure_viewer() -> Any:
-    global _viewer
-    _ensure_qt_app()
-    if _viewer is None:
-        _viewer = napari.Viewer()
-        _connect_window_destroyed_signal(_viewer)
-    return _viewer
-
+    global _state
 
-def _connect_window_destroyed_signal(viewer) -> None:
-    """Connect to the Qt window destroyed signal to clear our singleton.
-
-    This prevents stale references after a user manually closes the window.
-    """
-    global _window_close_connected, _viewer
-    if _window_close_connected:
-        return
-    try:
-        qt_win = viewer.window._qt_window  # type: ignore[attr-defined]
-
-        def _on_destroyed(*_args: Any) -> None:
-            # Clear the global so future calls re-create a fresh viewer
-            # Keep the Qt application alive
-            global _viewer
-            _viewer = None
-
-        qt_win.destroyed.connect(_on_destroyed)  # type: ignore[attr-defined]
-        _window_close_connected = True
-    except Exception:
-        # If anything goes wrong, continue without the connection
-        pass
-
-
-def _process_events(cycles: int = 2) -> None:
-    app = _ensure_qt_app()
-    for _ in range(max(1, cycles)):
-        app.processEvents()
-
-
-# Optional GUI executor for running viewer operations on the main thread
-_GUI_EXECUTOR: Any | None = None
-
-
-def set_gui_executor(executor: Any | None) -> None:
-    """Configure an executor that runs a callable on the GUI/main thread.
-
-    If None, operations execute directly in the current thread.
-    """
-    global _GUI_EXECUTOR
-    _GUI_EXECUTOR = executor
+    if state is None:
+        state = ServerState()
+    _state = state
 
+    @contextlib.asynccontextmanager
+    async def _lifespan(_server: FastMCP):  # type: ignore[type-arg]
+        state._event_loop = asyncio.get_running_loop()
+        try:
+            yield {}
+        finally:
+            state._event_loop = None
 
-def _gui_execute(operation):
-    if _GUI_EXECUTOR is not None:
-        return _GUI_EXECUTOR(operation)
-    return operation()
+    server = FastMCP("Napari MCP Server", lifespan=_lifespan)
 
+    # Dict to collect raw async functions before @server.tool() wraps them.
+    # Used at the end to expose backward-compatible module-level names.
+    _raw_tools: dict[str, Any] = {}
 
-async def _qt_event_pump() -> None:
-    """Periodically process Qt events so the GUI remains responsive.
+    def _register(fn: Any) -> Any:
+        """Register fn in _raw_tools, then pass to @server.tool()."""
+        _raw_tools[fn.__name__] = fn
+        return server.tool()(fn)
 
-    We avoid calling napari.run() to keep the server responsive while still
-    allowing the user to interact with the GUI.
-    """
-    try:
-        # Tight loop with small sleep keeps UI fluid without starving asyncio
-        while True:
-            _process_events(2)
-            await asyncio.sleep(0.01)
-    except asyncio.CancelledError:
-        # Graceful shutdown of the pump
-        pass
+    # ------------------------------------------------------------------
+    # Helpers (closures over *state*)
+    # ------------------------------------------------------------------
 
+    def _resolve_data_var(var_name: str) -> Any:
+        """Look up a variable in the execution namespace.
 
-class NapariMCPTools:
-    """Implementation of Napari MCP tools (exactly matching server.py behavior)."""
-
-    @staticmethod
-    async def detect_viewers() -> dict[str, Any]:
-        """
-        Detect available viewers (local and external).
-
-        Returns
-        -------
-        dict
-            Dictionary with information about available viewers
+        Raises ``KeyError`` with a helpful message if the variable is missing.
         """
-        viewers: dict[str, Any] = {"local": None, "external": None}
-
-        # Check for external viewer
-        client, info = await _detect_external_viewer()
-        if client and info is not None:
-            viewers["external"] = {
-                "available": True,
-                "type": "napari_bridge",
-                "port": info.get("bridge_port", _external_port),
-                "viewer_info": info.get("viewer", {}),
-            }
-        else:
-            viewers["external"] = {"available": False}
-
-        # Check for local viewer
-        global _viewer
-        if _viewer is not None:
-            viewers["local"] = {
-                "available": True,
-                "type": "singleton",
-                "title": _viewer.title,
-                "n_layers": len(_viewer.layers),
-            }
-        else:
-            viewers["local"] = {
-                "available": True,  # Can be created
-                "type": "not_initialized",
-            }
+        if var_name not in state.exec_globals:
+            avail = [
+                k
+                for k in state.exec_globals
+                if not k.startswith("__") and k not in ("viewer", "napari", "np")
+            ]
+            raise KeyError(
+                f"Variable '{var_name}' not found in execution namespace. "
+                f"Available user variables: {avail}"
+            )
+        return state.exec_globals[var_name]
 
-        return {
-            "status": "ok",
-            "viewers": viewers,
-        }
+    # ------------------------------------------------------------------
+    # Tool definitions (closures over *state*)
+    # ------------------------------------------------------------------
 
-    @staticmethod
+    @_register
     async def init_viewer(
         title: str | None = None,
         width: int | str | None = None,
         height: int | str | None = None,
         port: int | str | None = None,
+        detect_only: bool = False,
     ) -> dict[str, Any]:
-        """
-        Create or return the napari viewer (local or external).
+        """Create or return the napari viewer, with viewer detection.
+
+        When ``detect_only=True``, reports available viewers (local and
+        external) without creating or modifying anything.
 
         Parameters
         ----------
@@ -453,66 +167,76 @@ async def init_viewer(
         port : int, optional
             If provided, attempt to connect to an external napari-mcp bridge on
             this port (default is taken from NAPARI_MCP_BRIDGE_PORT or 9999).
-
-        Returns
-        -------
-        dict
-            Dictionary containing status, viewer type, and layer info.
+        detect_only : bool, default=False
+            If True, only detect available viewers without initialising.
         """
-        # Allow overriding the external port per-call
-        global _external_port
         if port is not None:
             try:
-                _external_port = int(port)
+                state.bridge_port = int(port)
             except Exception:
-                logger.error("Invalid port: {port}")
-                _external_port = _external_port
+                logger.error("Invalid port: %s", port)
+
+        # --- Detect-only mode (replaces former detect_viewers tool) ---
+        if detect_only:
+            viewers: dict[str, Any] = {"local": None, "external": None}
+            found, info = await state.detect_external_viewer()
+            if found and info is not None:
+                viewers["external"] = {
+                    "available": True,
+                    "type": "napari_bridge",
+                    "port": info.get("bridge_port", state.bridge_port),
+                    "viewer_info": info.get("viewer", {}),
+                }
+            else:
+                viewers["external"] = {"available": False}
+            if state.viewer is not None:
+                viewers["local"] = {
+                    "available": True,
+                    "type": "singleton",
+                    "title": state.viewer.title,
+                    "n_layers": len(state.viewer.layers),
+                }
+            else:
+                viewers["local"] = {"available": True, "type": "not_initialized"}
+            return {"status": "ok", "viewers": viewers}
 
-        async with _viewer_lock:
-            # Try external viewer first; fall back to local
-            try:
-                return await NapariMCPTools._external_session_information(
-                    _external_port
-                )
-            except Exception:
-                # No external viewer; continue to local viewer
-                pass
+        # --- Normal init ---
+        async with state.viewer_lock:
+            if state.mode == StartupMode.AUTO_DETECT:
+                try:
+                    return await state.external_session_information()
+                except Exception:
+                    pass
 
-            # Use local viewer
-            v = _ensure_viewer()
+            v = ensure_viewer(state)
             if title:
                 v.title = title
             if width or height:
-                w = (
-                    int(width)
-                    if width is not None
-                    else v.window.qt_viewer.canvas.size().width()
-                )
-                h = (
-                    int(height)
-                    if height is not None
-                    else v.window.qt_viewer.canvas.size().height()
-                )
-                v.window.qt_viewer.canvas.native.resize(w, h)
-            # Always ensure GUI pump is running for local viewer (backwards-incompatible change)
-            global _qt_pump_task
-            app = _ensure_qt_app()
+                try:
+                    qt_win = v.window._qt_window  # type: ignore[attr-defined]
+                    cur_size = qt_win.size()
+                    w = int(width) if width is not None else cur_size.width()
+                    h = int(height) if height is not None else cur_size.height()
+                    qt_win.resize(w, h)
+                except Exception:
+                    pass  # Resize is best-effort
+
+            app = ensure_qt_app(state)
             with contextlib.suppress(Exception):
                 app.setQuitOnLastWindowClosed(False)
-            _connect_window_destroyed_signal(v)
+            connect_window_destroyed_signal(state, v)
 
-            # Best-effort to show window without forcing focus (safer for tests/headless)
             try:
                 qt_win = v.window._qt_window  # type: ignore[attr-defined]
                 qt_win.show()
             except Exception:
                 pass
 
-            if _qt_pump_task is None or _qt_pump_task.done():
+            if state.qt_pump_task is None or state.qt_pump_task.done():
                 loop = asyncio.get_running_loop()
-                _qt_pump_task = loop.create_task(_qt_event_pump())
+                state.qt_pump_task = loop.create_task(qt_event_pump(state))
 
-            _process_events()
+            process_events(state)
             return {
                 "status": "ok",
                 "viewer_type": "local",
@@ -520,95 +244,51 @@ async def init_viewer(
                 "layers": [lyr.name for lyr in v.layers],
             }
 
-    @staticmethod
-    async def _external_session_information(_external_port: int) -> dict[str, Any]:
-        """Get session information from the external viewer."""
-        test_client = Client(f"http://localhost:{_external_port}/mcp")
-        async with test_client:
-            result = await test_client.call_tool("session_information")
-            if hasattr(result, "content"):
-                content = result.content
-                if isinstance(content, list) and len(content) > 0:
-                    import json
-
-                    info = (
-                        content[0].text
-                        if hasattr(content[0], "text")
-                        else str(content[0])
-                    )
-                    info_dict = json.loads(info) if isinstance(info, str) else info
-                    if info_dict.get("session_type") == "napari_bridge_session":
-                        return {
-                            "status": "ok",
-                            "viewer_type": "external",
-                            "title": info_dict.get("viewer", {}).get(
-                                "title", "External Viewer"
-                            ),
-                            "layers": info_dict.get("viewer", {}).get(
-                                "layer_names", []
-                            ),
-                            "port": info_dict.get("bridge_port", _external_port),
-                        }
+    @_register
+    async def close_viewer() -> dict[str, Any]:
+        """Close the viewer window and clear all layers."""
+        async with state.viewer_lock:
+            if state.viewer is None:
+                return {"status": "no_viewer"}
+
+            def _close():
+                if state.viewer is not None:
+                    state.viewer.close()
+                    state.viewer = None
+                process_events(state)
+                return {"status": "closed"}
 
-        return {
-            "status": "error",
-            "message": "Failed to get session information from external viewer",
-        }
+            try:
+                result = state.gui_execute(_close)
+            except Exception as e:
+                return {"status": "error", "message": f"Failed to close viewer: {e}"}
 
-    @staticmethod
-    async def close_viewer() -> dict[str, Any]:
-        """
-        Close the viewer window and clear all layers.
+            if state.qt_pump_task is not None and not state.qt_pump_task.done():
+                state.qt_pump_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await state.qt_pump_task
+            state.qt_pump_task = None
 
-        Returns
-        -------
-        dict
-            Dictionary with status: 'closed' if viewer existed, 'no_viewer' if none.
-        """
-        async with _viewer_lock:
-            global _viewer, _qt_pump_task
-            if _viewer is not None:
-                _viewer.close()
-                _viewer = None
-                # Stop GUI pump when closing viewer
-                if _qt_pump_task is not None and not _qt_pump_task.done():
-                    _qt_pump_task.cancel()
-                    with contextlib.suppress(asyncio.CancelledError):
-                        await _qt_pump_task
-                _qt_pump_task = None
-                _process_events()
-                return {"status": "closed"}
-            return {"status": "no_viewer"}
+            # Schedule server shutdown now that the viewer is gone
+            state.request_shutdown()
 
-    @staticmethod
-    async def session_information() -> dict[str, Any]:
-        """
-        Get comprehensive information about the current napari session.
+            return result
 
-        Returns
-        -------
-        dict
-            Comprehensive session information including viewer state, system info,
-            and environment details.
-        """
-        import os
+    @_register
+    async def session_information() -> dict[str, Any]:
+        """Get comprehensive information about the current napari session."""
         import platform
 
-        async with _viewer_lock:
-            global _viewer, _qt_pump_task, _exec_globals
-
-            try:
-                return await NapariMCPTools._external_session_information(
-                    _external_port
-                )
-            except Exception:
-                # No external viewer; continue to local viewer
-                pass
+        import napari
 
-            # Use local viewer
+        async with state.viewer_lock:
+            if state.mode == StartupMode.AUTO_DETECT:
+                try:
+                    return await state.external_session_information()
+                except Exception:
+                    pass
 
-            # Check if viewer exists
-            viewer_exists = _viewer is not None
+            viewer_exists = state.viewer is not None
             if not viewer_exists:
                 return {
                     "status": "ok",
@@ -618,10 +298,9 @@ async def session_information() -> dict[str, Any]:
                     "message": "No viewer currently initialized. Call init_viewer() first.",
                 }
 
-            v = _viewer
-            assert v is not None  # We already checked this above
+            v = state.viewer
+            assert v is not None
 
-            # Viewer information
             viewer_info = {
                 "title": v.title,
                 "viewer_id": id(v),
@@ -638,7 +317,6 @@ async def session_information() -> dict[str, Any]:
                 "grid_enabled": v.grid.enabled,
             }
 
-            # System information
             system_info = {
                 "python_version": sys.version,
                 "platform": platform.platform(),
@@ -647,49 +325,21 @@ async def session_information() -> dict[str, Any]:
                 "working_directory": os.getcwd(),
             }
 
-            # Session status
-            gui_running = _qt_pump_task is not None and not _qt_pump_task.done()
+            gui_running = (
+                state.qt_pump_task is not None and not state.qt_pump_task.done()
+            )
             session_info = {
                 "server_type": "napari_mcp_standalone",
                 "viewer_instance": f"<napari.Viewer at {hex(id(v))}>",
                 "gui_pump_running": gui_running,
-                "execution_namespace_vars": list(_exec_globals.keys()),
-                "qt_app_available": _qt_app is not None,
+                "execution_namespace_vars": list(state.exec_globals.keys()),
+                "qt_app_available": state.qt_app is not None,
             }
 
-            # Layer details
-            layer_details = []
-            for layer in v.layers:
-                layer_detail = {
-                    "name": layer.name,
-                    "type": layer.__class__.__name__,
-                    "visible": _parse_bool(getattr(layer, "visible", True)),
-                    "opacity": float(getattr(layer, "opacity", 1.0)),
-                    "blending": getattr(layer, "blending", None),
-                    "data_shape": list(layer.data.shape)
-                    if hasattr(layer, "data") and hasattr(layer.data, "shape")
-                    else None,
-                    "data_dtype": str(layer.data.dtype)
-                    if hasattr(layer, "data") and hasattr(layer.data, "dtype")
-                    else None,
-                    "layer_id": id(layer),
-                }
-
-                # Add layer-specific properties
-                if hasattr(layer, "colormap"):
-                    layer_detail["colormap"] = getattr(
-                        layer.colormap, "name", str(layer.colormap)
-                    )
-                if hasattr(layer, "contrast_limits"):
-                    try:
-                        cl = layer.contrast_limits
-                        layer_detail["contrast_limits"] = [float(cl[0]), float(cl[1])]
-                    except Exception:
-                        pass
-                if hasattr(layer, "gamma"):
-                    layer_detail["gamma"] = float(getattr(layer, "gamma", 1.0))
-
-                layer_details.append(layer_detail)
+            layer_details = [build_layer_detail(layer) for layer in v.layers]
+            # Add standalone-specific fields
+            for layer, detail in zip(v.layers, layer_details, strict=False):
+                detail["layer_id"] = id(layer)
 
             return {
                 "status": "ok",
@@ -701,13 +351,11 @@ async def session_information() -> dict[str, Any]:
                 "layers": layer_details,
             }
 
-    @staticmethod
+    @_register
     async def list_layers() -> list[dict[str, Any]]:
         """Return a list of layers with key properties."""
-        # Try to proxy to external viewer first
-        proxy_result = await _proxy_to_external("list_layers")
+        proxy_result = await state.proxy_to_external("list_layers")
         if proxy_result is not None:
-            # Ensure the result is the expected list format
             if isinstance(proxy_result, list):
                 return proxy_result
             elif isinstance(proxy_result, dict) and "content" in proxy_result:
@@ -716,181 +364,534 @@ async def list_layers() -> list[dict[str, Any]]:
                     return content
             return []
 
-        # Local execution
-        async with _viewer_lock:
+        async with state.viewer_lock:
+            if state.viewer is None:
+                return []
 
             def _build():
-                v = _ensure_viewer()
-                result: list[dict[str, Any]] = []  # type: ignore
-                for lyr in v.layers:
-                    entry = {
-                        "name": lyr.name,
-                        "type": lyr.__class__.__name__,
-                        "visible": _parse_bool(getattr(lyr, "visible", True)),
-                        "opacity": float(getattr(lyr, "opacity", 1.0)),
-                        "blending": getattr(lyr, "blending", None),
-                    }
-                    if (
-                        hasattr(lyr, "colormap")
-                        and getattr(lyr, "colormap", None) is not None
-                    ):
-                        entry["colormap"] = getattr(lyr.colormap, "name", None) or str(
+                v = state.viewer
+                return [build_layer_detail(lyr) for lyr in v.layers]
+
+            try:
+                return state.gui_execute(_build)
+            except Exception:
+                return []
+
+    def _parse_numpy_slicing(spec: str) -> tuple:
+        """Parse a numpy-style slicing string into a tuple of slices/ints.
+
+        Only allows integers, colons, and commas — no arbitrary expressions.
+        Examples: ``"0, :5, :5"`` → ``(0, slice(None, 5), slice(None, 5))``
+        """
+        components: list[int | slice] = []
+        for part in spec.split(","):
+            part = part.strip()
+            if not part:
+                continue
+            if ":" in part:
+                pieces = part.split(":")
+                if len(pieces) > 3:
+                    raise ValueError(f"Invalid slice component: {part!r}")
+                vals: list[int | None] = []
+                for p in pieces:
+                    p = p.strip()
+                    vals.append(int(p) if p else None)
+                while len(vals) < 3:
+                    vals.append(None)
+                components.append(slice(vals[0], vals[1], vals[2]))
+            else:
+                components.append(int(part))
+        if not components:
+            raise ValueError(f"Empty slicing specification: {spec!r}")
+        return tuple(components)
+
+    @_register
+    async def get_layer(
+        name: str,
+        include_data: bool = False,
+        slicing: str | None = None,
+        max_elements: int | str = 1000,
+    ) -> dict[str, Any]:
+        """Get detailed info about a layer, optionally including data.
+
+        Always returns metadata (shape, dtype, scale, translate, type-specific
+        properties). When ``include_data=True`` or ``slicing`` is provided,
+        also returns statistics and/or raw data values.
+
+        Parameters
+        ----------
+        name : str
+            Layer name (exact match).
+        include_data : bool, default False
+            If True, include data statistics (min/max/mean/std) and, for
+            small layers, inline data values.
+        slicing : str, optional
+            Numpy-style index string, e.g. ``"0, :5, :5"``. Implies
+            ``include_data=True``.
+        max_elements : int, default 1000
+            Maximum number of data elements to return inline. Larger data
+            is stored and an ``output_id`` returned for ``read_output``.
+        """
+        max_el = int(max_elements)
+        max_el = 1_000_000 if max_el < 0 else min(max_el, 1_000_000)
+        want_data = include_data or slicing is not None
+
+        async with state.viewer_lock:
+            if state.viewer is None:
+                return {
+                    "status": "not_found",
+                    "name": name,
+                    "message": "No viewer is open.",
+                }
+
+            def _build():
+                v = state.viewer
+                if name not in v.layers:
+                    return {"status": "not_found", "name": name}
+
+                lyr = v.layers[name]
+                ltype = lyr.__class__.__name__
+                data = getattr(lyr, "data", None)
+
+                # --- Always: metadata (former get_layer_info) ---
+                info: dict[str, Any] = {
+                    "status": "ok",
+                    "name": lyr.name,
+                    "type": ltype,
+                    "visible": bool(getattr(lyr, "visible", True)),
+                    "opacity": float(getattr(lyr, "opacity", 1.0)),
+                    "blending": getattr(lyr, "blending", None),
+                    "ndim": int(getattr(lyr, "ndim", 0)),
+                }
+
+                if data is not None:
+                    try:
+                        info["data_shape"] = list(np.shape(data))
+                    except Exception:
+                        pass
+                    dtype = getattr(data, "dtype", None)
+                    if dtype is not None:
+                        info["data_dtype"] = str(dtype)
+
+                scale = getattr(lyr, "scale", None)
+                if scale is not None:
+                    try:
+                        info["scale"] = [float(s) for s in scale]
+                    except Exception:
+                        pass
+                translate = getattr(lyr, "translate", None)
+                if translate is not None:
+                    try:
+                        info["translate"] = [float(t) for t in translate]
+                    except Exception:
+                        pass
+
+                # Type-specific metadata
+                if ltype == "Image":
+                    if hasattr(lyr, "colormap") and lyr.colormap is not None:
+                        info["colormap"] = getattr(lyr.colormap, "name", None) or str(
                             lyr.colormap
                         )
                     if (
                         hasattr(lyr, "contrast_limits")
-                        and getattr(lyr, "contrast_limits", None) is not None
+                        and lyr.contrast_limits is not None
                     ):
                         try:
                             cl = list(lyr.contrast_limits)
-                            entry["contrast_limits"] = [float(cl[0]), float(cl[1])]
+                            info["contrast_limits"] = [float(cl[0]), float(cl[1])]
                         except Exception:
                             pass
-                    result.append(entry)
-                return result
+                    info["gamma"] = float(getattr(lyr, "gamma", 1.0))
+                    if hasattr(lyr, "interpolation2d"):
+                        info["interpolation2d"] = str(lyr.interpolation2d)
 
-            return _gui_execute(_build)
+                elif ltype == "Labels":
+                    if data is not None:
+                        try:
+                            info["n_labels"] = int(
+                                len(np.unique(data)) - (1 if 0 in data else 0)
+                            )
+                        except Exception:
+                            pass
+                    if hasattr(lyr, "selected_label"):
+                        info["selected_label"] = int(lyr.selected_label)
 
-    @staticmethod
-    async def add_image(
-        path: str,
+                elif ltype == "Points":
+                    if data is not None:
+                        try:
+                            info["n_points"] = int(np.shape(data)[0])
+                        except Exception:
+                            pass
+                    if hasattr(lyr, "size"):
+                        try:
+                            info["point_size"] = float(np.mean(lyr.size))
+                        except Exception:
+                            pass
+                    if hasattr(lyr, "symbol"):
+                        info["symbol"] = str(lyr.symbol)
+
+                elif ltype == "Shapes":
+                    if data is not None:
+                        try:
+                            info["nshapes"] = int(lyr.nshapes)
+                        except Exception:
+                            pass
+                    if hasattr(lyr, "shape_type"):
+                        info["shape_type"] = list(lyr.shape_type)
+                    if hasattr(lyr, "edge_width"):
+                        try:
+                            info["edge_width"] = float(np.mean(lyr.edge_width))
+                        except Exception:
+                            pass
+
+                elif ltype == "Vectors":
+                    if data is not None:
+                        try:
+                            info["n_vectors"] = int(np.shape(data)[0])
+                        except Exception:
+                            pass
+                    if hasattr(lyr, "edge_width"):
+                        info["edge_width"] = float(lyr.edge_width)
+
+                elif ltype == "Tracks":
+                    if data is not None:
+                        try:
+                            info["n_tracks"] = int(len(np.unique(data[:, 0])))
+                        except Exception:
+                            pass
+
+                elif ltype == "Surface":
+                    if data is not None:
+                        try:
+                            vertices, faces = data[0], data[1]
+                            info["n_vertices"] = int(np.shape(vertices)[0])
+                            info["n_faces"] = int(np.shape(faces)[0])
+                        except Exception:
+                            pass
+
+                if not want_data:
+                    return info
+
+                # --- Data retrieval (former get_layer_data) ---
+
+                # Compute statistics for any numeric array data
+                def _add_stats(arr_like):
+                    try:
+                        arr = np.asarray(arr_like)
+                        # Sample to avoid allocating a huge float64 copy
+                        flat = (
+                            arr.flat[:1_000_000]
+                            if arr.size > 1_000_000
+                            else arr.ravel()
+                        )
+                        a = np.asarray(flat, dtype=float)
+                        info["statistics"] = {
+                            "min": float(np.nanmin(a)),
+                            "max": float(np.nanmax(a)),
+                            "mean": float(np.nanmean(a)),
+                            "std": float(np.nanstd(a)),
+                        }
+                    except Exception:
+                        pass
+
+                if ltype == "Points" and data is not None:
+                    coords = np.asarray(data)
+                    _add_stats(coords)
+                    if coords.size <= max_el:
+                        info["coordinates"] = coords.tolist()
+                    else:
+                        info["_large_data"] = coords
+                        info["_large_label"] = "coordinates"
+                    return info
+
+                if ltype == "Shapes":
+                    shapes_data = lyr.data
+                    total_elems = sum(np.asarray(s).size for s in shapes_data)
+                    if total_elems <= max_el:
+                        info["shapes"] = [np.asarray(s).tolist() for s in shapes_data]
+                    else:
+                        info["_large_data"] = shapes_data
+                        info["_large_label"] = "shapes"
+                    return info
+
+                if ltype == "Surface" and data is not None:
+                    try:
+                        vertices, faces = np.asarray(data[0]), np.asarray(data[1])
+                        info["data_shape"] = {
+                            "vertices": list(vertices.shape),
+                            "faces": list(faces.shape),
+                        }
+                        total = vertices.size + faces.size
+                        if total <= max_el:
+                            info["vertices"] = vertices.tolist()
+                            info["faces"] = faces.tolist()
+                        else:
+                            info["_large_data"] = (vertices, faces)
+                            info["_large_label"] = "surface"
+                    except Exception:
+                        pass
+                    return info
+
+                if ltype == "Vectors" and data is not None:
+                    arr = np.asarray(data)
+                    _add_stats(arr)
+                    if arr.size <= max_el:
+                        info["data"] = arr.tolist()
+                    else:
+                        info["_large_data"] = arr
+                        info["_large_label"] = "vectors"
+                    return info
+
+                if ltype == "Tracks" and data is not None:
+                    arr = np.asarray(data)
+                    _add_stats(arr)
+                    if arr.size <= max_el:
+                        info["data"] = arr.tolist()
+                    else:
+                        info["_large_data"] = arr
+                        info["_large_label"] = "tracks"
+                    return info
+
+                # Image / Labels / generic
+                if data is None:
+                    return info
+
+                arr = np.asarray(data)
+                if np.issubdtype(arr.dtype, np.number) or np.issubdtype(
+                    arr.dtype, np.bool_
+                ):
+                    _add_stats(arr)
+
+                if slicing is not None:
+                    try:
+                        idx = _parse_numpy_slicing(slicing)
+                        extracted = np.asarray(arr[idx])
+                        info["slice_shape"] = list(extracted.shape)
+                        if extracted.size <= max_el:
+                            info["data"] = extracted.tolist()
+                        else:
+                            info["_large_data"] = extracted
+                            info["_large_label"] = f"slice[{slicing}]"
+                    except Exception as e:
+                        info["slice_error"] = str(e)
+
+                return info
+
+            try:
+                raw = state.gui_execute(_build)
+            except Exception as e:
+                return {"status": "error", "message": f"Failed to get layer: {e}"}
+
+        # Handle large data storage (outside gui_execute since store_output is async)
+        if isinstance(raw, dict) and "_large_data" in raw:
+            large = raw.pop("_large_data")
+            label = raw.pop("_large_label", "data")
+            if isinstance(large, list | tuple):
+                lines = [
+                    repr(item)
+                    if not isinstance(item, np.ndarray)
+                    else np.array2string(item, threshold=sys.maxsize)
+                    for item in large
+                ]
+                text = "\n---\n".join(lines)
+            elif isinstance(large, np.ndarray):
+                text = np.array2string(large, threshold=sys.maxsize)
+            else:
+                text = repr(large)
+            oid = await state.store_output(
+                tool_name="get_layer",
+                stdout=text,
+                stderr="",
+            )
+            raw["output_id"] = oid
+            raw["message"] = (
+                f"{label} too large for inline response "
+                f"(>{max_el} elements). Use read_output('{oid}') to retrieve."
+            )
+
+        return raw
+
+    @_register
+    async def add_layer(
+        layer_type: str,
+        path: str | None = None,
+        data: list | None = None,
+        data_var: str | None = None,
         name: str | None = None,
+        # Image / Labels options
         colormap: str | None = None,
         blending: str | None = None,
         channel_axis: int | str | None = None,
+        # Points options
+        size: float | str | None = None,
+        # Shapes options
+        shape_type: str | None = None,
+        edge_color: str | None = None,
+        face_color: str | None = None,
+        edge_width: float | str | None = None,
     ) -> dict[str, Any]:
-        """
-        Add an image layer from a file path.
+        """Add a layer to the viewer.
 
         Parameters
         ----------
-        path : str
-            Path to an image readable by imageio (e.g., PNG, TIFF, OME-TIFF).
+        layer_type : str
+            One of: ``"image"``, ``"labels"``, ``"points"``, ``"shapes"``,
+            ``"vectors"``, ``"tracks"``, ``"surface"``.
+        path : str, optional
+            File path (for image/labels).
+        data : list, optional
+            Inline data (coordinates, shape vertices, etc.).
+        data_var : str, optional
+            Name of a variable in the ``execute_code`` namespace.
         name : str, optional
-            Layer name. If None, uses filename.
+            Layer name. Defaults to variable name or filename.
         colormap : str, optional
-            Napari colormap name (e.g., 'gray', 'magma').
+            Colormap name (image only).
         blending : str, optional
-            Blending mode (e.g., 'translucent').
+            Blending mode (image only).
         channel_axis : int, optional
-            If provided, interpret that axis as channels.
-
-        Returns
-        -------
-        dict
-            Dictionary containing status, layer name, and image shape.
+            Channel axis (image only).
+        size : float, optional
+            Point size in pixels (points only, default 10).
+        shape_type : str, optional
+            Shape type: "rectangle", "ellipse", "line", "path", "polygon"
+            (shapes only, default "rectangle").
+        edge_color : str, optional
+            Edge color (shapes/vectors only).
+        face_color : str, optional
+            Face color (shapes only).
+        edge_width : float, optional
+            Edge width in pixels (shapes/vectors only).
         """
-        # Try to proxy to external viewer first
-        params: dict[str, Any] = {"path": path}
-        if name:
-            params["name"] = name
-        if colormap:
-            params["colormap"] = colormap
-        if blending:
-            params["blending"] = blending
-        if channel_axis is not None:
-            params["channel_axis"] = int(channel_axis)
-
-        result = await _proxy_to_external("add_image", params)
-        if result is not None:
-            return result
+        lt = resolve_layer_type(layer_type)
+        if lt is None:
+            return {
+                "status": "error",
+                "message": (
+                    f"Unknown layer_type '{layer_type}'. "
+                    f"Valid types: image, labels, points, shapes, vectors, tracks, surface"
+                ),
+            }
 
-        # Local execution
-        import imageio.v3 as iio
+        # --- Resolve data ---
+        sources = sum([data_var is not None, data is not None, path is not None])
+        if sources > 1:
+            return {
+                "status": "error",
+                "message": "Provide only ONE of 'path', 'data', or 'data_var', not multiple.",
+            }
+
+        resolved_data = None
+        if data_var:
+            try:
+                resolved_data = _resolve_data_var(data_var)
+            except KeyError as e:
+                return {"status": "error", "message": str(e)}
+            if name is None:
+                name = data_var
+        elif data is not None:
+            resolved_data = data
+        elif path:
+            if lt in ("image", "labels"):
+                # Proxy check for image path loading
+                if lt == "image":
+                    params: dict[str, Any] = {
+                        "layer_type": "image",
+                        "path": path,
+                    }
+                    if name:
+                        params["name"] = name
+                    if colormap:
+                        params["colormap"] = colormap
+                    if blending:
+                        params["blending"] = blending
+                    if channel_axis is not None:
+                        params["channel_axis"] = int(channel_axis)
+                    result = await state.proxy_to_external("add_layer", params)
+                    if result is not None:
+                        return result
+
+                from pathlib import Path as _Path
+
+                import imageio.v3 as iio
+
+                p = _Path(path).expanduser().resolve(strict=False)
+                if not p.exists():
+                    return {
+                        "status": "error",
+                        "message": f"File not found: {p}",
+                    }
+                try:
+                    resolved_data = iio.imread(str(p))
+                except Exception as e:
+                    return {
+                        "status": "error",
+                        "message": f"Failed to add {layer_type} layer: {e}",
+                    }
+            else:
+                return {
+                    "status": "error",
+                    "message": f"'path' is only supported for image/labels, not {layer_type}",
+                }
+        elif lt == "surface":
+            return {
+                "status": "error",
+                "message": "'data_var' is required for surface layers.",
+            }
+        else:
+            return {
+                "status": "error",
+                "message": "Provide 'path', 'data', or 'data_var'.",
+            }
 
-        async with _viewer_lock:
-            data = iio.imread(path)
+        async with state.viewer_lock:
 
             def _add():
-                v = _ensure_viewer()
-                layer = v.add_image(
-                    data,
+                v = ensure_viewer(state)
+                result = create_layer_on_viewer(
+                    v,
+                    resolved_data,
+                    lt,
                     name=name,
                     colormap=colormap,
                     blending=blending,
                     channel_axis=channel_axis,
+                    size=size,
+                    shape_type=shape_type,
+                    edge_color=edge_color,
+                    face_color=face_color,
+                    edge_width=edge_width,
                 )
-                _process_events()
-                return {
-                    "status": "ok",
-                    "name": layer.name,
-                    "shape": list(np.shape(data)),
-                }
-
-            return _gui_execute(_add)
-
-    @staticmethod
-    async def add_labels(path: str, name: str | None = None) -> dict[str, Any]:
-        """Add a labels layer from a file path (e.g., PNG/TIFF with integer labels)."""
-        import imageio.v3 as iio
+                process_events(state)
+                return result
 
-        async with _viewer_lock:
             try:
-                from pathlib import Path
-
-                def _add():
-                    v = _ensure_viewer()
-                    p = Path(path).expanduser().resolve(strict=False)
-                    data = iio.imread(str(p))
-                    layer = v.add_labels(data, name=name)
-                    _process_events()
-                    return {
-                        "status": "ok",
-                        "name": layer.name,
-                        "shape": list(np.shape(data)),
-                    }
-
-                return _gui_execute(_add)
+                return state.gui_execute(_add)
             except Exception as e:
                 return {
                     "status": "error",
-                    "message": f"Failed to add labels from '{path}': {e}",
+                    "message": f"Failed to add {layer_type} layer: {e}",
                 }
 
-    @staticmethod
-    async def add_points(
-        points: list[list[float]], name: str | None = None, size: float | str = 10.0
-    ) -> dict[str, Any]:
-        """
-        Add a points layer.
-
-        - points: List of [y, x] or [z, y, x] coordinates
-        - name: Optional layer name
-        - size: Point size in pixels
-        """
-        async with _viewer_lock:
-
-            def _add():
-                v = _ensure_viewer()
-                arr = np.asarray(points, dtype=float)
-                layer = v.add_points(arr, name=name, size=float(size))
-                _process_events()
-                return {
-                    "status": "ok",
-                    "name": layer.name,
-                    "n_points": int(arr.shape[0]),
-                }
-
-            return _gui_execute(_add)
-
-    @staticmethod
+    @_register
     async def remove_layer(name: str) -> dict[str, Any]:
         """Remove a layer by name."""
-        async with _viewer_lock:
+        async with state.viewer_lock:
 
             def _remove():
-                v = _ensure_viewer()
+                v = ensure_viewer(state)
                 if name in v.layers:
                     v.layers.remove(name)
-                    _process_events()
+                    process_events(state)
                     return {"status": "removed", "name": name}
                 return {"status": "not_found", "name": name}
 
-            return _gui_execute(_remove)
-
-    # Removed: rename_layer (use set_layer_properties with new_name instead)
+            try:
+                return state.gui_execute(_remove)
+            except Exception as e:
+                return {"status": "error", "message": f"Failed to remove layer: {e}"}
 
-    @staticmethod
+    @_register
     async def set_layer_properties(
         name: str,
         visible: bool | None = None,
@@ -900,57 +901,110 @@ async def set_layer_properties(
         contrast_limits: list[float] | None = None,
         gamma: float | str | None = None,
         new_name: str | None = None,
+        active: bool | None = None,
     ) -> dict[str, Any]:
-        """Set common properties on a layer by name."""
-        async with _viewer_lock:
+        """Set properties on a layer by name.
+
+        Parameters
+        ----------
+        name : str
+            Layer name (exact match).
+        visible, opacity, colormap, blending, contrast_limits, gamma
+            Standard layer rendering properties.
+        new_name : str, optional
+            Rename the layer.
+        active : bool, optional
+            If True, make this the selected/active layer. Setting to False
+            has no effect (use viewer selection directly).
+        """
+        async with state.viewer_lock:
 
             def _set():
-                v = _ensure_viewer()
+                v = ensure_viewer(state)
                 if name not in v.layers:
                     return {"status": "not_found", "name": name}
                 lyr = v.layers[name]
                 if visible is not None and hasattr(lyr, "visible"):
-                    lyr.visible = _parse_bool(visible)
+                    lyr.visible = parse_bool(visible)
                 if opacity is not None and hasattr(lyr, "opacity"):
-                    lyr.opacity = float(opacity)
+                    o = float(opacity)
+                    if not (0.0 <= o <= 1.0):
+                        return {
+                            "status": "error",
+                            "message": f"opacity must be between 0.0 and 1.0, got {o}",
+                        }
+                    lyr.opacity = o
                 if colormap is not None and hasattr(lyr, "colormap"):
-                    lyr.colormap = colormap
+                    try:
+                        lyr.colormap = colormap
+                    except (KeyError, ValueError) as e:
+                        return {
+                            "status": "error",
+                            "message": f"Invalid colormap '{colormap}': {e}",
+                        }
                 if blending is not None and hasattr(lyr, "blending"):
-                    lyr.blending = blending
+                    try:
+                        lyr.blending = blending
+                    except (ValueError, KeyError) as e:
+                        return {
+                            "status": "error",
+                            "message": f"Invalid blending mode '{blending}': {e}",
+                        }
                 if contrast_limits is not None and hasattr(lyr, "contrast_limits"):
-                    with contextlib.suppress(Exception):
-                        lyr.contrast_limits = [
-                            float(contrast_limits[0]),
-                            float(contrast_limits[1]),
-                        ]
+                    cl = list(contrast_limits)
+                    if len(cl) != 2:
+                        return {
+                            "status": "error",
+                            "message": f"contrast_limits must be [min, max], got {len(cl)} values",
+                        }
+                    try:
+                        lyr.contrast_limits = [float(cl[0]), float(cl[1])]
+                    except Exception as e:
+                        return {
+                            "status": "error",
+                            "message": f"Invalid contrast_limits: {e}",
+                        }
                 if gamma is not None and hasattr(lyr, "gamma"):
-                    lyr.gamma = float(gamma)
+                    g = float(gamma)
+                    if g <= 0:
+                        return {
+                            "status": "error",
+                            "message": f"gamma must be > 0, got {g}",
+                        }
+                    lyr.gamma = g
                 if new_name is not None:
                     lyr.name = new_name
-                _process_events()
+                if active is not None and parse_bool(active):
+                    v.layers.selection = {lyr}
+                process_events(state)
                 return {"status": "ok", "name": lyr.name}
 
-            return _gui_execute(_set)
+            try:
+                return state.gui_execute(_set)
+            except Exception as e:
+                return {
+                    "status": "error",
+                    "message": f"Failed to set layer properties: {e}",
+                }
 
-    @staticmethod
+    @_register
     async def reorder_layer(
         name: str,
         index: int | str | None = None,
         before: str | None = None,
         after: str | None = None,
     ) -> dict[str, Any]:
-        """
-        Reorder a layer by name.
+        """Reorder a layer by name.
 
         Provide exactly one of:
         - index: absolute target index
         - before: move before this layer name
         - after: move after this layer name
         """
-        async with _viewer_lock:
+        async with state.viewer_lock:
 
             def _reorder():
-                v = _ensure_viewer()
+                v = ensure_viewer(state)
                 if name not in v.layers:
                     return {"status": "not_found", "name": name}
                 if sum(x is not None for x in (index, before, after)) != 1:
@@ -972,185 +1026,445 @@ def _reorder():
                     target = v.layers.index(after) + 1
                 if target != cur:
                     v.layers.move(cur, target)
-                _process_events()
+                process_events(state)
                 return {"status": "ok", "name": name, "index": v.layers.index(name)}
 
-            return _gui_execute(_reorder)
+            try:
+                return state.gui_execute(_reorder)
+            except Exception as e:
+                return {"status": "error", "message": f"Failed to reorder layer: {e}"}
 
-    @staticmethod
-    async def set_active_layer(name: str) -> dict[str, Any]:
-        """Set the selected/active layer by name."""
-        async with _viewer_lock:
+    @_register
+    async def apply_to_layers(
+        filter_type: str | None = None,
+        filter_pattern: str | None = None,
+        properties: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Apply property changes to multiple layers matching a filter.
 
-            def _set_active():
-                v = _ensure_viewer()
-                if name not in v.layers:
-                    return {"status": "not_found", "name": name}
-                v.layers.selection = {v.layers[name]}
-                _process_events()
-                return {"status": "ok", "active": name}
+        Parameters
+        ----------
+        filter_type : str, optional
+            Layer type name to match (e.g., "Image", "Labels", "Points").
+        filter_pattern : str, optional
+            Glob pattern matched against layer names (e.g., "seg_*").
+        properties : dict, optional
+            Properties to set on matched layers. Supported keys: ``visible``,
+            ``opacity``, ``colormap``, ``blending``, ``contrast_limits``,
+            ``gamma``, ``new_name`` (renames by appending a suffix is NOT
+            supported — use ``set_layer_properties`` individually).
+        """
+        import fnmatch
+
+        if properties is None or not properties:
+            return {"status": "error", "message": "No properties specified."}
+
+        _KNOWN_PROPS = {
+            "visible",
+            "opacity",
+            "colormap",
+            "blending",
+            "contrast_limits",
+            "gamma",
+        }
+        unknown_keys = set(properties.keys()) - _KNOWN_PROPS
 
-            return _gui_execute(_set_active)
+        async with state.viewer_lock:
 
-    @staticmethod
-    async def reset_view() -> dict[str, Any]:
-        """Reset the camera view to fit data."""
-        async with _viewer_lock:
+            def _apply():
+                v = ensure_viewer(state)
+                matched: list[str] = []
 
-            def _reset():
-                v = _ensure_viewer()
-                v.reset_view()
-                _process_events()
-                return {"status": "ok"}
+                for lyr in list(v.layers):
+                    ltype = lyr.__class__.__name__
+                    if filter_type and ltype != filter_type:
+                        continue
+                    if filter_pattern and not fnmatch.fnmatch(lyr.name, filter_pattern):
+                        continue
 
-            return _gui_execute(_reset)
+                    matched.append(lyr.name)
+                    for key, val in properties.items():
+                        if key in unknown_keys:
+                            continue
+                        try:
+                            if key == "visible":
+                                lyr.visible = parse_bool(val)
+                            elif key == "opacity":
+                                o = float(val)
+                                if 0.0 <= o <= 1.0:
+                                    lyr.opacity = o
+                            elif key == "colormap" and hasattr(lyr, "colormap"):
+                                lyr.colormap = val
+                            elif key == "blending":
+                                lyr.blending = val
+                            elif key == "contrast_limits" and hasattr(
+                                lyr, "contrast_limits"
+                            ):
+                                cl = list(val)
+                                if len(cl) == 2:
+                                    lyr.contrast_limits = (float(cl[0]), float(cl[1]))
+                            elif key == "gamma" and hasattr(lyr, "gamma"):
+                                g = float(val)
+                                if g > 0:
+                                    lyr.gamma = g
+                        except Exception:
+                            pass  # skip invalid values per-layer
 
-    # Removed: set_zoom (use set_camera with zoom instead)
+                process_events(state)
+                result: dict[str, Any] = {
+                    "status": "ok",
+                    "matched": matched,
+                    "count": len(matched),
+                }
+                if unknown_keys:
+                    result["unknown_properties"] = sorted(unknown_keys)
+                    result["message"] = (
+                        f"Unknown properties ignored: {', '.join(sorted(unknown_keys))}"
+                    )
+                return result
+
+            try:
+                return state.gui_execute(_apply)
+            except Exception as e:
+                return {
+                    "status": "error",
+                    "message": f"Failed to apply properties: {e}",
+                }
 
-    @staticmethod
-    async def set_camera(
+    @_register
+    async def configure_viewer(
+        reset_view: bool = False,
         center: list[float] | None = None,
         zoom: float | str | None = None,
-        angle: float | str | None = None,
+        angles: list[float] | None = None,
+        ndisplay: int | str | None = None,
+        dims_axis: int | str | None = None,
+        dims_value: int | str | None = None,
+        grid: bool | str | None = None,
     ) -> dict[str, Any]:
-        """Set camera properties: center, zoom, and/or angle."""
-        async with _viewer_lock:
+        """Configure viewer display: camera, dimensions, and grid.
+
+        All parameters are optional — set any combination in one call.
+
+        Parameters
+        ----------
+        reset_view : bool, default False
+            If True, reset the camera to fit all data.
+        center : list[float], optional
+            Camera center position.
+        zoom : float, optional
+            Camera zoom factor (must be > 0).
+        angles : list[float], optional
+            Camera angles as [azimuth, elevation, roll] in degrees.
+        ndisplay : int, optional
+            Number of displayed dimensions (2 or 3).
+        dims_axis : int, optional
+            Axis index for slider position (use with ``dims_value``).
+        dims_value : int, optional
+            Step value for the given axis.
+        grid : bool, optional
+            Enable or disable grid view.
+        """
+        async with state.viewer_lock:
+
+            def _configure():
+                v = ensure_viewer(state)
+                result: dict[str, Any] = {"status": "ok"}
+
+                # Validate upfront
+                if zoom is not None:
+                    z = float(zoom)
+                    if z <= 0:
+                        return {
+                            "status": "error",
+                            "message": f"zoom must be > 0, got {z}",
+                        }
+                if ndisplay is not None:
+                    nd = int(ndisplay)
+                    if nd not in (2, 3):
+                        return {
+                            "status": "error",
+                            "message": f"ndisplay must be 2 or 3, got {nd}",
+                        }
+                if (dims_axis is None) != (dims_value is None):
+                    return {
+                        "status": "error",
+                        "message": "Both 'dims_axis' and 'dims_value' must be provided together.",
+                    }
+                if dims_axis is not None:
+                    ax = int(dims_axis)
+                    if ax < 0 or ax >= v.dims.ndim:
+                        return {
+                            "status": "error",
+                            "message": f"axis {ax} out of range for {v.dims.ndim}D data",
+                        }
+
+                # Apply
+                if reset_view:
+                    v.reset_view()
 
-            def _set_cam():
-                v = _ensure_viewer()
                 if center is not None:
                     v.camera.center = list(map(float, center))
                 if zoom is not None:
                     v.camera.zoom = float(zoom)
-                if angle is not None:
-                    v.camera.angles = (float(angle),)
-                _process_events()
+                if angles is not None:
+                    v.camera.angles = tuple(float(a) for a in angles)
+
+                result["center"] = list(map(float, v.camera.center))
+                result["zoom"] = float(v.camera.zoom)
+                result["angles"] = list(map(float, v.camera.angles))
+
+                if ndisplay is not None:
+                    v.dims.ndisplay = int(ndisplay)
+                    result["ndisplay"] = int(v.dims.ndisplay)
+
+                if dims_axis is not None and dims_value is not None:
+                    ax = int(dims_axis)
+                    val = int(dims_value)
+                    nsteps = v.dims.nsteps[ax]
+                    clamped = max(0, min(val, nsteps - 1))
+                    v.dims.set_current_step(ax, clamped)
+                    result["axis"] = ax
+                    result["value"] = clamped
+                    if clamped != val:
+                        result["warning"] = (
+                            f"value {val} clamped to {clamped} "
+                            f"(axis {ax} has {nsteps} steps)"
+                        )
+
+                if grid is not None:
+                    v.grid.enabled = parse_bool(grid)
+                    result["grid"] = bool(v.grid.enabled)
+
+                process_events(state)
+                return result
+
+            try:
+                return state.gui_execute(_configure)
+            except Exception as e:
                 return {
-                    "status": "ok",
-                    "center": list(map(float, v.camera.center)),
-                    "zoom": float(v.camera.zoom),
+                    "status": "error",
+                    "message": f"Failed to configure viewer: {e}",
                 }
 
-            return _gui_execute(_set_cam)
+    @_register
+    async def save_layer_data(
+        name: str,
+        path: str,
+        format: str | None = None,
+    ) -> dict[str, Any]:
+        """Save a layer's data to a file.
+
+        Parameters
+        ----------
+        name : str
+            Layer name.
+        path : str
+            Output file path. Format is inferred from extension unless
+            *format* is specified. Supported: ``.tiff``, ``.png``,
+            ``.npy``, ``.csv`` (points/tabular only).
+        format : str, optional
+            Explicit format override (e.g., ``"npy"``, ``"tiff"``).
+        """
+        from pathlib import Path as _Path
 
-    @staticmethod
-    async def set_ndisplay(ndisplay: int | str) -> dict[str, Any]:
-        """Set number of displayed dimensions (2 or 3)."""
-        async with _viewer_lock:
+        async with state.viewer_lock:
 
-            def _set():
-                v = _ensure_viewer()
-                v.dims.ndisplay = int(ndisplay)
-                _process_events()
-                return {"status": "ok", "ndisplay": int(v.dims.ndisplay)}
+            def _save():
+                v = ensure_viewer(state)
+                if name not in v.layers:
+                    return {"status": "not_found", "name": name}
+
+                lyr = v.layers[name]
+                p = _Path(path).expanduser().resolve()
+                p.parent.mkdir(parents=True, exist_ok=True)
+                ext = format or p.suffix.lstrip(".").lower()
+                ltype = lyr.__class__.__name__
+
+                _SUPPORTED_EXTS = {
+                    "npy",
+                    "csv",
+                    "tiff",
+                    "tif",
+                    "png",
+                    "jpg",
+                    "jpeg",
+                }
+                if ext and ext not in _SUPPORTED_EXTS:
+                    return {
+                        "status": "error",
+                        "message": (
+                            f"Unsupported format '{ext}'. "
+                            f"Supported: {', '.join(sorted(_SUPPORTED_EXTS))}"
+                        ),
+                    }
+
+                # Validate format/type compatibility
+                if ext == "csv" and ltype not in ("Points", "Tracks", "Vectors"):
+                    return {
+                        "status": "error",
+                        "message": f"CSV format only supported for Points/Tracks/Vectors, not {ltype}.",
+                    }
+                if ext in ("tiff", "tif", "png", "jpg", "jpeg") and ltype not in (
+                    "Image",
+                    "Labels",
+                ):
+                    return {
+                        "status": "error",
+                        "message": f"Image format '{ext}' only supported for Image/Labels, not {ltype}.",
+                    }
+
+                if ext == "npy":
+                    data = getattr(lyr, "data", None)
+                    if not str(p).endswith(".npy"):
+                        p = p.with_suffix(".npy")
+                    np.save(str(p), data, allow_pickle=False)
+                elif ext == "csv" and ltype in ("Points", "Tracks", "Vectors"):
+                    data = np.asarray(lyr.data)
+                    flat = data.reshape(-1, data.shape[-1])
+                    ncols = flat.shape[1]
+                    if ltype == "Points":
+                        header = ",".join(f"axis-{i}" for i in range(ncols))
+                    elif ltype == "Tracks":
+                        header = ",".join(
+                            ["track_id"] + [f"axis-{i}" for i in range(ncols - 1)]
+                        )
+                    else:
+                        header = ",".join(f"col-{i}" for i in range(ncols))
+                    np.savetxt(str(p), flat, delimiter=",", header=header, comments="")
+                elif ltype in ("Image", "Labels"):
+                    import imageio.v3 as iio
+
+                    data = np.asarray(lyr.data)
+                    iio.imwrite(str(p), data)
+                else:
+                    # Fallback: numpy save
+                    data = getattr(lyr, "data", None)
+                    if not str(p).endswith(".npy"):
+                        p = p.with_suffix(".npy")
+                    np.save(str(p), data, allow_pickle=False)
+
+                return {
+                    "status": "ok",
+                    "path": str(p),
+                    "format": ext,
+                    "size_bytes": int(p.stat().st_size),
+                }
+
+            try:
+                return state.gui_execute(_save)
+            except Exception as e:
+                return {
+                    "status": "error",
+                    "message": f"Failed to save layer data: {e}",
+                }
 
-            return _gui_execute(_set)
+    @_register
+    async def screenshot(
+        canvas_only: bool | str = True,
+        save_path: str | None = None,
+        axis: int | str | None = None,
+        slice_range: str | None = None,
+        interpolate_to_fit: bool = False,
+        save_dir: str | None = None,
+    ) -> ImageContent | list[ImageContent] | dict[str, Any]:
+        """Take a screenshot, or a timelapse series by sweeping a dims axis.
 
-    @staticmethod
-    async def set_dims_current_step(
-        axis: int | str, value: int | str
-    ) -> dict[str, Any]:
-        """Set the current step (slider position) for a specific axis."""
-        async with _viewer_lock:
+        For a single screenshot, call with no ``axis``/``slice_range``.
+        For a timelapse, provide both ``axis`` and ``slice_range``.
 
-            def _set():
-                v = _ensure_viewer()
-                v.dims.set_current_step(int(axis), int(value))
-                _process_events()
-                return {"status": "ok", "axis": int(axis), "value": int(value)}
+        Parameters
+        ----------
+        canvas_only : bool, default True
+            If True, only capture the canvas area.
+        save_path : str, optional
+            Save single screenshot to this file path (returns metadata).
+        axis : int, optional
+            Dims axis to sweep for timelapse (e.g., temporal axis).
+        slice_range : str, optional
+            Python-like slice string, e.g. ``"1:5"``, ``":6"``, ``"::2"``.
+            Required when ``axis`` is provided.
+        interpolate_to_fit : bool, default False
+            If True, downsample timelapse frames to fit ~1.3 MB total.
+        save_dir : str, optional
+            Save timelapse frames as ``frame_NNNN.png`` in this directory.
+        """
+        from PIL import Image
 
-            return _gui_execute(_set)
+        co = parse_bool(canvas_only, default=True)
 
-    @staticmethod
-    async def set_grid(enabled: bool | str = True) -> dict[str, Any]:
-        """Enable or disable grid view."""
-        async with _viewer_lock:
+        # --- Single screenshot mode ---
+        if axis is None and slice_range is None:
+            from pathlib import Path as _Path
 
-            def _set():
-                v = _ensure_viewer()
-                v.grid.enabled = _parse_bool(enabled)
-                _process_events()
-                return {"status": "ok", "grid": _parse_bool(v.grid.enabled)}
+            if save_path is None:
+                result = await state.proxy_to_external(
+                    "screenshot", {"canvas_only": co}
+                )
+                if result is not None:
+                    return result
 
-            return _gui_execute(_set)
+            async with state.viewer_lock:
 
-    @staticmethod
-    async def screenshot(canvas_only: bool | str = True) -> ImageContent:
-        """
-        Take a screenshot of the napari canvas and return as base64.
+                def _shot():
+                    v = ensure_viewer(state)
+                    process_events(state, 3)
+                    arr = v.screenshot(canvas_only=co)
+                    if not isinstance(arr, np.ndarray):
+                        arr = np.asarray(arr)
+                    if arr.dtype != np.uint8:
+                        arr = arr.astype(np.uint8, copy=False)
+                    img = Image.fromarray(arr)
 
-        Parameters
-        ----------
-        canvas_only : bool, default=True
-            If True, only capture the canvas area.
+                    if save_path is not None:
+                        p = _Path(save_path).expanduser().resolve()
+                        p.parent.mkdir(parents=True, exist_ok=True)
+                        img.save(str(p))
+                        return {
+                            "status": "ok",
+                            "path": str(p),
+                            "size": [img.width, img.height],
+                        }
 
-        Returns
-        -------
-        ImageContent
-            The screenshot image as an mcp.types.ImageContent object.
-        """
-        # Try to proxy to external viewer first
-        result = await _proxy_to_external("screenshot", {"canvas_only": canvas_only})
-        if result is not None:
-            return result
+                    # Auto-downscale inline screenshots to stay under
+                    # ~200 KB base64 (≈150 KB PNG).  This prevents MCP
+                    # context overflow while keeping useful resolution.
+                    max_png_bytes = 150_000
+                    buf = BytesIO()
+                    img.save(buf, format="PNG")
+                    enc = buf.getvalue()
+                    if len(enc) > max_png_bytes:
+                        scale = math.sqrt(max_png_bytes / len(enc))
+                        new_w = max(1, int(img.width * scale))
+                        new_h = max(1, int(img.height * scale))
+                        img = img.resize((new_w, new_h), resample=Image.BILINEAR)
+                        buf = BytesIO()
+                        img.save(buf, format="PNG")
+                        enc = buf.getvalue()
+                    return fastmcp.utilities.types.Image(
+                        data=enc, format="png"
+                    ).to_image_content()
 
-        # Local execution
-        async with _viewer_lock:
-
-            def _shot():
-                v = _ensure_viewer()
-                _process_events(3)
-                arr = v.screenshot(canvas_only=canvas_only)
-                if not isinstance(arr, np.ndarray):
-                    arr = np.asarray(arr)
-                if arr.dtype != np.uint8:
-                    arr = arr.astype(np.uint8, copy=False)
-                img = Image.fromarray(arr)
-                buf = BytesIO()
-                img.save(buf, format="PNG")
-                enc = buf.getvalue()
-                return fastmcp.utilities.types.Image(
-                    data=enc, format="png"
-                ).to_image_content()
-
-            return _gui_execute(_shot)
-
-    @staticmethod
-    async def timelapse_screenshot(
-        axis: int | str,
-        slice_range: str,
-        canvas_only: bool | str = True,
-        interpolate_to_fit: bool = True,
-    ) -> list[ImageContent]:
-        """
-        Capture a series of screenshots while sweeping a dims axis.
+                try:
+                    return state.gui_execute(_shot)
+                except Exception as e:
+                    return {"status": "error", "message": f"Screenshot failed: {e}"}
 
-        Parameters
-        ----------
-        axis : int
-            Dims axis index to sweep (e.g., temporal axis).
-        slice_range : str
-            Python-like slice string over step indices, e.g. "1:5", ":6", "::2".
-            Defaults follow Python semantics with start=0, stop=nsteps, step=1.
-        canvas_only : bool, default=True
-            If True, only capture the canvas area.
-        interpolate_to_fit : bool, default=False
-            If True, interpolate the images to fit the total size cap of 1309246 bytes.
+        # --- Timelapse mode ---
+        if axis is None or slice_range is None:
+            return {
+                "status": "error",
+                "message": "Both 'axis' and 'slice_range' are required for timelapse.",
+            }
 
-        Returns
-        -------
-        list[ImageContent]
-            List of screenshots as mcp.types.ImageContent objects.
-        """
         max_total_base64_bytes = 1309246 if interpolate_to_fit else None
 
-        # Try to proxy to external viewer first
-        result = await _proxy_to_external(
-            "timelapse_screenshot",
+        result = await state.proxy_to_external(
+            "screenshot",
             {
                 "axis": axis,
                 "slice_range": slice_range,
-                "canvas_only": canvas_only,
+                "canvas_only": co,
                 "interpolate_to_fit": interpolate_to_fit,
             },
         )
@@ -1158,9 +1472,7 @@ async def timelapse_screenshot(
             return result  # type: ignore[return-value]
 
         def _parse_slice(spec: str, length: int) -> list[int]:
-            # Normalize
             s = (spec or "").strip()
-            # Single integer
             if s and ":" not in s:
                 try:
                     idx = int(s)
@@ -1174,7 +1486,6 @@ def _parse_slice(spec: str, length: int) -> list[int]:
                     )
                 return [idx]
 
-            # Slice form start:stop:step
             parts = s.split(":")
             if len(parts) > 3:
                 raise ValueError(f"Invalid slice range: {spec!r}")
@@ -1188,11 +1499,11 @@ def _to_int_or_none(val: str) -> int | None:
 
             start = _to_int_or_none(start_s)
             stop = _to_int_or_none(stop_s)
-            step = _to_int_or_none(step_s) or 1
+            step = _to_int_or_none(step_s)
             if step == 0:
                 raise ValueError("slice step cannot be 0")
-
-            # Handle negatives like Python
+            if step is None:
+                step = 1
             if start is None:
                 start = 0 if step > 0 else length - 1
             if stop is None:
@@ -1201,32 +1512,24 @@ def _to_int_or_none(val: str) -> int | None:
                 start += length
             if stop < 0:
                 stop += length
-
-            # Clamp to valid iteration range similar to range() behavior
             rng = range(start, stop, step)
-            indices = [i for i in rng if 0 <= i < length]
-            return indices
+            return [i for i in rng if 0 <= i < length]
 
-        # Local execution
-        async with _viewer_lock:
+        async with state.viewer_lock:
 
             def _run_series():
-                v = _ensure_viewer()
-
-                # Determine number of steps along axis
+                v = ensure_viewer(state)
+                ax = int(axis)
                 try:
                     nsteps_tuple = getattr(v.dims, "nsteps", None)
                     if nsteps_tuple is None:
-                        # Fallback: infer from current_step length and a conservative stop
-                        # We cannot reliably infer total steps without dims.nsteps; require it
                         raise AttributeError
-                    total = int(nsteps_tuple[int(axis)])
+                    total = int(nsteps_tuple[ax])
                 except Exception:
-                    # Best effort via bounds from layers; may be approximate
                     try:
                         total = max(
-                            int(getattr(lyr.data, "shape", [1])[(int(axis))])
-                            if int(axis) < getattr(lyr.data, "ndim", 0)
+                            int(getattr(lyr.data, "shape", [1])[ax])
+                            if ax < getattr(lyr.data, "ndim", 0)
                             else 1
                             for lyr in v.layers
                         )
@@ -1242,10 +1545,9 @@ def _run_series():
                 if not indices:
                     return []
 
-                # Take a sample at the first index to estimate size
-                v.dims.set_current_step(int(axis), int(indices[0]))
-                _process_events(2)
-                sample_arr = v.screenshot(canvas_only=canvas_only)
+                v.dims.set_current_step(ax, int(indices[0]))
+                process_events(state, 2)
+                sample_arr = v.screenshot(canvas_only=co)
                 if not isinstance(sample_arr, np.ndarray):
                     sample_arr = np.asarray(sample_arr)
                 if sample_arr.dtype != np.uint8:
@@ -1256,7 +1558,6 @@ def _run_series():
                 sample_png = sbuf.getvalue()
                 sample_b64_len = ((len(sample_png) + 2) // 3) * 4
 
-                # Ask user whether to downsample if estimated total exceeds cap
                 downsample_factor = 1.0
                 if (
                     max_total_base64_bytes is not None
@@ -1268,20 +1569,41 @@ def _run_series():
                     )
                     downsample_factor = max(0.05, min(1.0, est_factor))
 
-                images: list[ImageContent] = []  # type: ignore
+                # Save to directory mode
+                if save_dir is not None:
+                    from pathlib import Path as _Path
+
+                    dirp = _Path(save_dir).expanduser().resolve()
+                    dirp.mkdir(parents=True, exist_ok=True)
+                    saved_paths: list[str] = []
+                    for idx in indices:
+                        v.dims.set_current_step(ax, int(idx))
+                        process_events(state, 2)
+                        arr = v.screenshot(canvas_only=co)
+                        if not isinstance(arr, np.ndarray):
+                            arr = np.asarray(arr)
+                        if arr.dtype != np.uint8:
+                            arr = arr.astype(np.uint8, copy=False)
+                        img = Image.fromarray(arr)
+                        fp = dirp / f"frame_{idx:04d}.png"
+                        img.save(str(fp))
+                        saved_paths.append(str(fp))
+                    return {
+                        "status": "ok",
+                        "paths": saved_paths,
+                        "n_frames": len(saved_paths),
+                    }
+
+                images: list[ImageContent] = []
                 total_b64_len = 0
                 for idx in indices:
-                    # Move slider
-                    v.dims.set_current_step(int(axis), int(idx))
-                    _process_events(2)
-
-                    # Capture
-                    arr = v.screenshot(canvas_only=canvas_only)
+                    v.dims.set_current_step(ax, int(idx))
+                    process_events(state, 2)
+                    arr = v.screenshot(canvas_only=co)
                     if not isinstance(arr, np.ndarray):
                         arr = np.asarray(arr)
                     if arr.dtype != np.uint8:
                         arr = arr.astype(np.uint8, copy=False)
-
                     img = Image.fromarray(arr)
                     if downsample_factor < 1.0:
                         new_w = max(1, int(img.width * downsample_factor))
@@ -1303,15 +1625,19 @@ def _run_series():
                             data=enc, format="png"
                         ).to_image_content()
                     )
-
                 return images
 
-            return _gui_execute(_run_series)
+            try:
+                return state.gui_execute(_run_series)
+            except Exception as e:
+                return {
+                    "status": "error",
+                    "message": f"Timelapse screenshot failed: {e}",
+                }
 
-    @staticmethod
+    @_register
     async def execute_code(code: str, line_limit: int | str = 30) -> dict[str, Any]:
-        """
-        Execute arbitrary Python code in the server's interpreter.
+        """Execute arbitrary Python code in the server's interpreter.
 
         Similar to napari's console. The execution namespace persists across calls
         and includes 'viewer', 'napari', and 'np'.
@@ -1325,174 +1651,56 @@ async def execute_code(code: str, line_limit: int | str = 30) -> dict[str, Any]:
             Maximum number of output lines to return. Use -1 for unlimited output.
             Warning: Using -1 may consume a large number of tokens.
 
-        Returns
-        -------
-        dict
-            Dictionary with 'status', optional 'result_repr', 'stdout', 'stderr',
-            and 'output_id' for retrieving full output if truncated.
+        Note
+        ----
+        In standalone mode, code execution runs synchronously on the main
+        thread (required for Qt/napari operations) and has no timeout.
+        In bridge mode, a 600-second timeout is enforced.
         """
-        # Try to proxy to external viewer first
-        result = await _proxy_to_external("execute_code", {"code": code})
-        if result is not None:
-            return result
-
-        # Local execution
-        async with _viewer_lock:
-            v = _ensure_viewer()
-            _exec_globals.setdefault("__builtins__", __builtins__)  # type: ignore[assignment]
-            _exec_globals["viewer"] = v
-            napari_mod = napari
-            if napari_mod is not None:
-                _exec_globals.setdefault("napari", napari_mod)
-            _exec_globals.setdefault("np", np)
-
-            stdout_buf = StringIO()
-            stderr_buf = StringIO()
-            result_repr: str | None = None
-            try:
-                # Capture stdout/stderr during execution
-                with (
-                    contextlib.redirect_stdout(stdout_buf),
-                    contextlib.redirect_stderr(stderr_buf),
-                ):
-                    # Try to evaluate last expression if present
-                    parsed = ast.parse(code, mode="exec")
-                    if parsed.body and isinstance(parsed.body[-1], ast.Expr):
-                        # Execute all but last, then eval last expression to
-                        # capture a result
-                        if len(parsed.body) > 1:
-                            exec_ast = ast.Module(
-                                body=parsed.body[:-1], type_ignores=[]
-                            )
-                            exec(
-                                compile(exec_ast, "<mcp-exec>", "exec"),
-                                _exec_globals,
-                                _exec_globals,
-                            )
-                        last_expr = ast.Expression(body=parsed.body[-1].value)
-                        value = eval(
-                            compile(last_expr, "<mcp-eval>", "eval"),
-                            _exec_globals,
-                            _exec_globals,
-                        )
-                        result_repr = repr(value)
-                    else:
-                        # Pure statements
-                        exec(
-                            compile(parsed, "<mcp-exec>", "exec"),
-                            _exec_globals,
-                            _exec_globals,
-                        )
-                _process_events(2)
-
-                # Get full output
-                stdout_full = stdout_buf.getvalue()
-                stderr_full = stderr_buf.getvalue()
-
-                # Store full output and get ID
-                output_id = await _store_output(
-                    tool_name="execute_code",
-                    stdout=stdout_full,
-                    stderr=stderr_full,
-                    result_repr=result_repr,
-                    code=code,
-                )
+        import napari
 
-                # Prepare response with line limiting
-                response = {
-                    "status": "ok",
-                    "output_id": output_id,
-                    **({"result_repr": result_repr} if result_repr is not None else {}),
-                }
-
-                # Add warning for unlimited output
-                if line_limit == -1:
-                    response["warning"] = (
-                        "Unlimited output requested. This may consume a large number "
-                        "of tokens. Consider using read_output for large outputs."
-                    )
-                    response["stdout"] = stdout_full
-                    response["stderr"] = stderr_full
-                else:
-                    # Truncate stdout and stderr
-                    stdout_truncated, stdout_was_truncated = _truncate_output(
-                        stdout_full, int(line_limit)
-                    )
-                    stderr_truncated, stderr_was_truncated = _truncate_output(
-                        stderr_full, int(line_limit)
-                    )
-
-                    response["stdout"] = stdout_truncated
-                    response["stderr"] = stderr_truncated
-
-                    if stdout_was_truncated or stderr_was_truncated:
-                        response["truncated"] = True  # type: ignore
-                        response["message"] = (
-                            f"Output truncated to {line_limit} lines. "
-                            f"Use read_output('{output_id}') to retrieve full output."
-                        )
-
-                return response
-            except Exception as e:
-                _process_events(1)
-                tb = traceback.format_exc()
-
-                # Get full output including traceback
-                stdout_full = stdout_buf.getvalue()
-                stderr_full = stderr_buf.getvalue() + tb
-
-                # Store full output and get ID
-                output_id = await _store_output(
-                    tool_name="execute_code",
-                    stdout=stdout_full,
-                    stderr=stderr_full,
-                    code=code,
-                    error=True,
-                )
+        try:
+            line_limit = int(line_limit)
+        except (ValueError, TypeError):
+            line_limit = 30
 
-                # Prepare error response with line limiting
-                response = {
-                    "status": "error",
-                    "output_id": output_id,
-                }
+        result = await state.proxy_to_external("execute_code", {"code": code})
+        if result is not None:
+            return result
 
-                # Add warning for unlimited output
-                if line_limit == -1:
-                    response["warning"] = (
-                        "Unlimited output requested. This may consume a large number "
-                        "of tokens. Consider using read_output for large outputs."
-                    )
-                    response["stdout"] = stdout_full
-                    response["stderr"] = stderr_full
-                else:
-                    # Truncate stdout and stderr
-                    stdout_truncated, stdout_was_truncated = _truncate_output(
-                        stdout_full, int(line_limit)
-                    )
-                    stderr_truncated, stderr_was_truncated = _truncate_output(
-                        stderr_full, int(line_limit)
-                    )
+        async with state.viewer_lock:
+            v = ensure_viewer(state)
+            state.exec_globals.setdefault("__builtins__", __builtins__)  # type: ignore[assignment]
+            state.exec_globals["viewer"] = v
+            state.exec_globals.setdefault("napari", napari)
+            state.exec_globals.setdefault("np", np)
 
-                    response["stdout"] = stdout_truncated
-                    # Ensure exception summary is present even when truncated
-                    error_summary = f"{type(e).__name__}: {e}"
-                    if error_summary not in stderr_truncated:
-                        # Append a concise summary line so callers can see the error type
-                        if stderr_truncated and not stderr_truncated.endswith("\n"):
-                            stderr_truncated += "\n"
-                        stderr_truncated += error_summary + "\n"
-                    response["stderr"] = stderr_truncated
-
-                    if stdout_was_truncated or stderr_was_truncated:
-                        response["truncated"] = True  # type: ignore
-                        response["message"] = (
-                            f"Output truncated to {line_limit} lines. "
-                            f"Use read_output('{output_id}') to retrieve full output."
-                        )
+            stdout_full, stderr_full, result_repr, error = run_code(
+                code, state.exec_globals, source_label="<mcp-exec>"
+            )
+            process_events(state, 2 if error is None else 1)
+
+            status = "error" if error else "ok"
+            output_id = await state.store_output(
+                tool_name="execute_code",
+                stdout=stdout_full,
+                stderr=stderr_full,
+                result_repr=result_repr,
+                code=code,
+                **({"error": True} if error else {}),
+            )
 
-                return response
+            return build_truncated_response(
+                status=status,
+                output_id=output_id,
+                stdout_full=stdout_full,
+                stderr_full=stderr_full,
+                result_repr=result_repr,
+                line_limit=line_limit,
+                error=error,
+            )
 
-    @staticmethod
+    @_register
     async def install_packages(
         packages: list[str],
         upgrade: bool | None = False,
@@ -1503,10 +1711,7 @@ async def install_packages(
         line_limit: int | str = 30,
         timeout: int = 240,
     ) -> dict[str, Any]:
-        """
-        Install Python packages using pip.
-
-        Install packages into the currently running server environment.
+        """Install Python packages using pip.
 
         Parameters
         ----------
@@ -1524,18 +1729,15 @@ async def install_packages(
             Allow pre-releases (--pre flag).
         line_limit : int, default=30
             Maximum number of output lines to return. Use -1 for unlimited output.
-            Warning: Using -1 may consume a large number of tokens.
         timeout : int, default=240
             Timeout for pip install in seconds.
-
-        Returns
-        -------
-        dict
-            Dictionary including status, returncode, stdout, stderr, command,
-            and output_id for retrieving full output if truncated.
         """
-        # Try to proxy to external viewer first
-        result = await _proxy_to_external(
+        try:
+            line_limit = int(line_limit)
+        except (ValueError, TypeError):
+            line_limit = 30
+
+        result = await state.proxy_to_external(
             "install_packages",
             {
                 "packages": packages,
@@ -1557,6 +1759,14 @@ async def install_packages(
                 "message": "Parameter 'packages' must be a non-empty list of package names",
             }
 
+        for pkg in packages:
+            if not _PKG_NAME_RE.match(pkg.strip()):
+                return {
+                    "status": "error",
+                    "message": f"Invalid package specifier: {pkg!r}. "
+                    "Use standard pip format (e.g., 'numpy>=1.20').",
+                }
+
         cmd: list[str] = [
             sys.executable,
             "-m",
@@ -1577,7 +1787,6 @@ async def install_packages(
             cmd.extend(["--extra-index-url", extra_index_url])
         cmd.extend(packages)
 
-        # Run pip as a subprocess without blocking the event loop
         proc = await asyncio.create_subprocess_exec(
             *cmd,
             stdout=asyncio.subprocess.PIPE,
@@ -1590,15 +1799,17 @@ async def install_packages(
         except asyncio.TimeoutError:
             with contextlib.suppress(ProcessLookupError):
                 proc.kill()
-            stdout_b, stderr_b = b"", f"pip install timed out after {timeout}s".encode()
+            stdout_b, stderr_b = (
+                b"",
+                f"pip install timed out after {timeout}s".encode(),
+            )
         stdout = stdout_b.decode(errors="replace")
         stderr = stderr_b.decode(errors="replace")
 
         status = "ok" if proc.returncode == 0 else "error"
         command_str = " ".join(shlex.quote(part) for part in cmd)
 
-        # Store full output and get ID
-        output_id = await _store_output(
+        output_id = await state.store_output(
             tool_name="install_packages",
             stdout=stdout,
             stderr=stderr,
@@ -1607,49 +1818,23 @@ async def install_packages(
             returncode=proc.returncode,
         )
 
-        # Prepare response with line limiting
-        response = {
-            "status": status,
-            "returncode": proc.returncode if proc.returncode is not None else -1,
-            "command": command_str,
-            "output_id": output_id,
-        }
-
-        # Add warning for unlimited output
-        if line_limit == -1:
-            response["warning"] = (
-                "Unlimited output requested. This may consume a large number "
-                "of tokens. Consider using read_output for large outputs."
-            )
-            response["stdout"] = stdout
-            response["stderr"] = stderr
-        else:
-            # Truncate stdout and stderr
-            stdout_truncated, stdout_was_truncated = _truncate_output(
-                stdout, int(line_limit)
-            )
-            stderr_truncated, stderr_was_truncated = _truncate_output(
-                stderr, int(line_limit)
-            )
-
-            response["stdout"] = stdout_truncated
-            response["stderr"] = stderr_truncated
-
-            if stdout_was_truncated or stderr_was_truncated:
-                response["truncated"] = True
-                response["message"] = (
-                    f"Output truncated to {line_limit} lines. "
-                    f"Use read_output('{output_id}') to retrieve full output."
-                )
-
+        response = build_truncated_response(
+            status=status,
+            output_id=output_id,
+            stdout_full=stdout,
+            stderr_full=stderr,
+            result_repr=None,
+            line_limit=line_limit,
+        )
+        response["returncode"] = proc.returncode if proc.returncode is not None else -1
+        response["command"] = command_str
         return response
 
-    @staticmethod
+    @_register
     async def read_output(
         output_id: str, start: int | str = 0, end: int | str = -1
     ) -> dict[str, Any]:
-        """
-        Read stored tool output with optional line range.
+        """Read stored tool output with optional line range.
 
         Parameters
         ----------
@@ -1659,22 +1844,16 @@ async def read_output(
             Starting line number (0-indexed).
         end : int, default=-1
             Ending line number (exclusive). If -1, read to end.
-
-        Returns
-        -------
-        dict
-            Dictionary containing the requested output lines and metadata.
         """
-        async with _output_storage_lock:
-            if output_id not in _output_storage:
+        async with state.output_storage_lock:
+            if output_id not in state.output_storage:
                 return {
                     "status": "error",
                     "message": f"Output ID '{output_id}' not found",
                 }
 
-            stored_output = _output_storage[output_id]
+            stored_output = state.output_storage[output_id]
 
-            # Combine stdout and stderr for line-based access
             full_output = ""
             if stored_output.get("stdout"):
                 full_output = stored_output["stdout"]
@@ -1688,7 +1867,6 @@ async def read_output(
                     full_output += "\n"
                 full_output += stderr_text
 
-            # Normalize and clamp range inputs
             try:
                 start = int(start)
             except Exception:
@@ -1697,15 +1875,11 @@ async def read_output(
                 end = int(end)
             except Exception:
                 end = -1
-
             start = max(0, start)
 
             lines = full_output.splitlines(keepends=True)
             total_lines = len(lines)
-
-            # Handle line range
             end = total_lines if end == -1 else min(total_lines, end)
-
             selected_lines = [] if start >= total_lines else lines[start:end]
 
             return {
@@ -1719,411 +1893,43 @@ async def read_output(
                 "result_repr": stored_output.get("result_repr"),
             }
 
+    # ---- backward-compatible module-level tool names (for tests) ----
+    # The @server.tool() decorator wraps closures into FunctionTool objects.
+    # We need to expose the raw async functions (stored in _raw_tools before
+    # decoration) so that ``from napari_mcp.server import list_layers`` works.
+    _mod: Any = sys.modules[__name__]
+    for _name, _fn in _raw_tools.items():
+        setattr(_mod, _name, _fn)
 
-async def detect_viewers() -> dict[str, Any]:
-    """
-    Detect available viewers (local and external).
-
-    Returns
-    -------
-    dict
-        Dictionary with information about available viewers
-    """
-    return await NapariMCPTools.detect_viewers()
-
-
-# Removed explicit selection API; the server now auto-detects an external
-# napari-mcp bridge if available and otherwise uses a local viewer.
-
-
-async def _external_session_information(_external_port: int) -> dict[str, Any]:
-    """Get session information from the external viewer."""
-    test_client = Client(f"http://localhost:{_external_port}/mcp")
-    async with test_client:
-        result = await test_client.call_tool("session_information")
-        if hasattr(result, "content"):
-            content = result.content
-            if isinstance(content, list) and len(content) > 0:
-                import json
-
-                info = (
-                    content[0].text if hasattr(content[0], "text") else str(content[0])
-                )
-                info_dict = json.loads(info) if isinstance(info, str) else info
-                if info_dict.get("session_type") == "napari_bridge_session":
-                    return {
-                        "status": "ok",
-                        "viewer_type": "external",
-                        "title": info_dict.get("viewer", {}).get(
-                            "title", "External Viewer"
-                        ),
-                        "layers": info_dict.get("viewer", {}).get("layer_names", []),
-                        "port": info_dict.get("bridge_port", _external_port),
-                    }
-    return {
-        "status": "error",
-        "message": "Failed to get session information from external viewer",
-    }
-
-
-async def init_viewer(
-    title: str | None = None,
-    width: int | str | None = None,
-    height: int | str | None = None,
-    port: int | str | None = None,
-) -> dict[str, Any]:
-    """
-    Create or return the napari viewer (local or external).
-
-    Parameters
-    ----------
-    title : str, optional
-        Optional window title (only for local viewer).
-    width : int, optional
-        Optional initial canvas width (only for local viewer).
-    height : int, optional
-        Optional initial canvas height (only for local viewer).
-    port : int, optional
-        If provided, attempt to connect to an external napari-mcp bridge on
-        this port (default is taken from NAPARI_MCP_BRIDGE_PORT or 9999).
-
-    Returns
-    -------
-    dict
-        Dictionary containing status, viewer type, and layer info.
-    """
-    return await NapariMCPTools.init_viewer(
-        title=title, width=width, height=height, port=port
-    )
-
-
-# Removed explicit GUI control APIs (start_gui/stop_gui/is_gui_running)
-# GUI pump now starts automatically when initializing a local viewer.
-
-
-async def close_viewer() -> dict[str, Any]:
-    """
-    Close the viewer window and clear all layers.
-
-    Returns
-    -------
-    dict
-        Dictionary with status: 'closed' if viewer existed, 'no_viewer' if none.
-    """
-    return await NapariMCPTools.close_viewer()
-
-
-async def session_information() -> dict[str, Any]:
-    """
-    Get comprehensive information about the current napari session.
-
-    Returns
-    -------
-    dict
-        Comprehensive session information including viewer state, system info,
-        and environment details.
-    """
-    return await NapariMCPTools.session_information()
-
-
-async def list_layers() -> list[dict[str, Any]]:
-    """Return a list of layers with key properties."""
-    return await NapariMCPTools.list_layers()
-
-
-async def add_image(
-    path: str,
-    name: str | None = None,
-    colormap: str | None = None,
-    blending: str | None = None,
-    channel_axis: int | str | None = None,
-) -> dict[str, Any]:
-    """
-    Add an image layer from a file path.
-
-    Parameters
-    ----------
-    path : str
-        Path to an image readable by imageio (e.g., PNG, TIFF, OME-TIFF).
-    name : str, optional
-        Layer name. If None, uses filename.
-    colormap : str, optional
-        Napari colormap name (e.g., 'gray', 'magma').
-    blending : str, optional
-        Blending mode (e.g., 'translucent').
-    channel_axis : int, optional
-        If provided, interpret that axis as channels.
-
-    Returns
-    -------
-    dict
-        Dictionary containing status, layer name, and image shape.
-    """
-    return await NapariMCPTools.add_image(
-        path=path,
-        name=name,
-        colormap=colormap,
-        blending=blending,
-        channel_axis=channel_axis,
-    )
-
-
-async def add_labels(path: str, name: str | None = None) -> dict[str, Any]:
-    """Add a labels layer from a file path (e.g., PNG/TIFF with integer labels)."""
-    return await NapariMCPTools.add_labels(path=path, name=name)
-
-
-async def add_points(
-    points: list[list[float]], name: str | None = None, size: float | str = 10.0
-) -> dict[str, Any]:
-    """
-    Add a points layer.
-
-    - points: List of [y, x] or [z, y, x] coordinates
-    - name: Optional layer name
-    - size: Point size in pixels
-    """
-    return await NapariMCPTools.add_points(points=points, name=name, size=size)
-
-
-async def remove_layer(name: str) -> dict[str, Any]:
-    """Remove a layer by name."""
-    return await NapariMCPTools.remove_layer(name)
-
-
-# Removed: rename_layer (use set_layer_properties with new_name instead)
-
-
-async def set_layer_properties(
-    name: str,
-    visible: bool | None = None,
-    opacity: float | None = None,
-    colormap: str | None = None,
-    blending: str | None = None,
-    contrast_limits: list[float] | None = None,
-    gamma: float | str | None = None,
-    new_name: str | None = None,
-) -> dict[str, Any]:
-    """Set common properties on a layer by name."""
-    return await NapariMCPTools.set_layer_properties(
-        name=name,
-        visible=visible,
-        opacity=opacity,
-        colormap=colormap,
-        blending=blending,
-        contrast_limits=contrast_limits,
-        gamma=gamma,
-        new_name=new_name,
-    )
-
-
-async def reorder_layer(
-    name: str,
-    index: int | str | None = None,
-    before: str | None = None,
-    after: str | None = None,
-) -> dict[str, Any]:
-    """
-    Reorder a layer by name.
-
-    Provide exactly one of:
-    - index: absolute target index
-    - before: move before this layer name
-    - after: move after this layer name
-    """
-    return await NapariMCPTools.reorder_layer(
-        name=name, index=index, before=before, after=after
-    )
-
-
-async def set_active_layer(name: str) -> dict[str, Any]:
-    """Set the selected/active layer by name."""
-    return await NapariMCPTools.set_active_layer(name)
-
-
-async def reset_view() -> dict[str, Any]:
-    """Reset the camera view to fit data."""
-    return await NapariMCPTools.reset_view()
-
-
-# Removed: set_zoom (use set_camera with zoom instead)
-
-
-async def set_camera(
-    center: list[float] | None = None,
-    zoom: float | str | None = None,
-    angle: float | str | None = None,
-) -> dict[str, Any]:
-    """Set camera properties: center, zoom, and/or angle."""
-    return await NapariMCPTools.set_camera(center=center, zoom=zoom, angle=angle)
+    # Store server instance for test access via ``napari_mcp.server.server``
+    _mod.server = server
 
+    return server
 
-async def set_ndisplay(ndisplay: int | str) -> dict[str, Any]:
-    """Set number of displayed dimensions (2 or 3)."""
-    return await NapariMCPTools.set_ndisplay(ndisplay)
 
+def detect_external_viewer_sync() -> bool:
+    """Synchronous check for external viewer availability."""
+    if _state is None:
+        return False
+    try:
+        try:
+            asyncio.get_running_loop()
+            return False
+        except RuntimeError:
+            pass
+        loop = asyncio.new_event_loop()
+        try:
+            found, _ = loop.run_until_complete(_state.detect_external_viewer())
+            return found
+        finally:
+            loop.close()
+    except Exception:
+        return False
 
-async def set_dims_current_step(axis: int | str, value: int | str) -> dict[str, Any]:
-    """Set the current step (slider position) for a specific axis."""
-    return await NapariMCPTools.set_dims_current_step(axis, value)
-
-
-async def set_grid(enabled: bool | str = True) -> dict[str, Any]:
-    """Enable or disable grid view."""
-    return await NapariMCPTools.set_grid(enabled)
-
-
-async def screenshot(canvas_only: bool | str = True) -> ImageContent:
-    """
-    Take a screenshot of the napari canvas and return as base64.
-
-    Parameters
-    ----------
-    canvas_only : bool, default=True
-        If True, only capture the canvas area.
-
-    Returns
-    -------
-    ImageContent
-        The screenshot image as an mcp.types.ImageContent object.
-    """
-    return await NapariMCPTools.screenshot(canvas_only)
-
-
-async def timelapse_screenshot(
-    axis: int | str,
-    slice_range: str,
-    canvas_only: bool | str = True,
-    interpolate_to_fit: bool = True,
-) -> list[ImageContent]:
-    """
-    Capture a series of screenshots while sweeping a dims axis.
-
-    Parameters
-    ----------
-    axis : int
-        Dims axis index to sweep (e.g., temporal axis).
-    slice_range : str
-        Python-like slice string over step indices, e.g. "1:5", ":6", "::2".
-        Defaults follow Python semantics with start=0, stop=nsteps, step=1.
-    canvas_only : bool, default=True
-        If True, only capture the canvas area.
-    interpolate_to_fit : bool, default=False
-        If True, interpolate the images to fit the total size cap of 1309246 bytes.
-
-    Returns
-    -------
-    list[ImageContent]
-        List of screenshots as mcp.types.ImageContent objects.
-    """
-    return await NapariMCPTools.timelapse_screenshot(
-        axis=axis,
-        slice_range=slice_range,
-        canvas_only=canvas_only,
-        interpolate_to_fit=interpolate_to_fit,
-    )
-
-
-async def execute_code(code: str, line_limit: int | str = 30) -> dict[str, Any]:
-    """
-    Execute arbitrary Python code in the server's interpreter.
-
-    Similar to napari's console. The execution namespace persists across calls
-    and includes 'viewer', 'napari', and 'np'.
-
-    Parameters
-    ----------
-    code : str
-        Python code string. The value of the last expression (if any)
-        is returned as 'result_repr'.
-    line_limit : int, default=30
-        Maximum number of output lines to return. Use -1 for unlimited output.
-        Warning: Using -1 may consume a large number of tokens.
-
-    Returns
-    -------
-    dict
-        Dictionary with 'status', optional 'result_repr', 'stdout', 'stderr',
-        and 'output_id' for retrieving full output if truncated.
-    """
-    return await NapariMCPTools.execute_code(code=code, line_limit=line_limit)
-
-
-async def install_packages(
-    packages: list[str],
-    upgrade: bool | None = False,
-    no_deps: bool | None = False,
-    index_url: str | None = None,
-    extra_index_url: str | None = None,
-    pre: bool | None = False,
-    line_limit: int | str = 30,
-    timeout: int = 240,
-) -> dict[str, Any]:
-    """
-    Install Python packages using pip.
-
-    Install packages into the currently running server environment.
-
-    Parameters
-    ----------
-    packages : list of str
-        List of package specifiers (e.g., "scikit-image", "torch==2.3.1").
-    upgrade : bool, optional
-        If True, pass --upgrade flag.
-    no_deps : bool, optional
-        If True, pass --no-deps flag.
-    index_url : str, optional
-        Custom index URL.
-    extra_index_url : str, optional
-        Extra index URL.
-    pre : bool, optional
-        Allow pre-releases (--pre flag).
-    line_limit : int, default=30
-        Maximum number of output lines to return. Use -1 for unlimited output.
-        Warning: Using -1 may consume a large number of tokens.
-    timeout : int, default=240
-        Timeout for pip install in seconds.
-
-    Returns
-    -------
-    dict
-        Dictionary including status, returncode, stdout, stderr, command,
-        and output_id for retrieving full output if truncated.
-    """
-    return await NapariMCPTools.install_packages(
-        packages=packages,
-        upgrade=upgrade,
-        no_deps=no_deps,
-        index_url=index_url,
-        extra_index_url=extra_index_url,
-        pre=pre,
-        line_limit=line_limit,
-        timeout=timeout,
-    )
-
-
-async def read_output(
-    output_id: str, start: int | str = 0, end: int | str = -1
-) -> dict[str, Any]:
-    """
-    Read stored tool output with optional line range.
-
-    Parameters
-    ----------
-    output_id : str
-        Unique ID of the stored output.
-    start : int, default=0
-        Starting line number (0-indexed).
-    end : int, default=-1
-        Ending line number (exclusive). If -1, read to end.
-
-    Returns
-    -------
-    dict
-        Dictionary containing the requested output lines and metadata.
-    """
-    return await NapariMCPTools.read_output(output_id=output_id, start=start, end=end)
 
+# ---------------------------------------------------------------------------
+# Typer CLI
+# ---------------------------------------------------------------------------
 
 app = typer.Typer(
     name="napari-mcp",
@@ -2133,15 +1939,22 @@ async def read_output(
 
 
 @app.command()
-def run() -> None:
+def run(
+    auto_detect: bool = typer.Option(
+        False, "--auto-detect", help="Auto-detect external napari viewers at startup"
+    ),
+    port: int = typer.Option(9999, "--port", help="Bridge port for auto-detect mode"),
+) -> None:
     """Run the MCP server."""
-    server.run()
+    mode = StartupMode.AUTO_DETECT if auto_detect else StartupMode.STANDALONE
+    state = ServerState(mode=mode, bridge_port=port)
+    srv = create_server(state)
+    srv.run()
 
 
 @app.command()
 def install() -> None:
-    """
-    Install napari-mcp in various AI clients.
+    """Install napari-mcp in various AI clients.
 
     NOTE: This command is deprecated. Use 'napari-mcp-install' instead.
     """
@@ -2149,55 +1962,30 @@ def install() -> None:
 
     console = Console()
     console.print(
-        "\n[bold yellow]⚠️  Deprecated Command[/bold yellow]\n",
+        "\n[bold yellow]Deprecated Command[/bold yellow]\n",
         style="yellow",
     )
     console.print(
         "The 'napari-mcp install' command has been replaced by 'napari-mcp-install'.",
     )
     console.print("\n[bold green]To install napari-mcp:[/bold green]")
-    console.print("  • Run: [bold cyan]napari-mcp-install --help[/bold cyan]")
+    console.print("  Run: [bold cyan]napari-mcp-install --help[/bold cyan]")
     console.print(
-        "  • Or: [bold cyan]napari-mcp-install claude-desktop[/bold cyan] (for example)\n"
+        "  Or: [bold cyan]napari-mcp-install install claude-desktop[/bold cyan] (for example)\n"
     )
-
     console.print("[yellow]Please use 'napari-mcp-install' instead.[/yellow]\n")
-
     raise typer.Exit(1)
 
 
 def main() -> None:
     """Entry point that defaults to running the server."""
-    # If no arguments provided, default to running the server
     if len(sys.argv) == 1:
-        server.run()
+        state = ServerState()
+        srv = create_server(state)
+        srv.run()
     else:
         app()
 
 
-# Register tools with the FastMCP server without replacing the callables
-server.tool()(detect_viewers)
-server.tool()(init_viewer)
-server.tool()(close_viewer)
-server.tool()(session_information)
-server.tool()(list_layers)
-server.tool()(add_image)
-server.tool()(add_labels)
-server.tool()(add_points)
-server.tool()(remove_layer)
-server.tool()(set_layer_properties)
-server.tool()(reorder_layer)
-server.tool()(set_active_layer)
-server.tool()(reset_view)
-server.tool()(set_camera)
-server.tool()(set_ndisplay)
-server.tool()(set_dims_current_step)
-server.tool()(set_grid)
-server.tool()(screenshot)
-server.tool()(timelapse_screenshot)
-server.tool()(execute_code)
-server.tool()(install_packages)
-server.tool()(read_output)
-
 if __name__ == "__main__":
     main()
diff --git a/src/napari_mcp/state.py b/src/napari_mcp/state.py
new file mode 100644
index 0000000..6696475
--- /dev/null
+++ b/src/napari_mcp/state.py
@@ -0,0 +1,240 @@
+"""Server state management for napari-mcp."""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+import json
+import logging
+import os
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from napari_mcp.viewer_protocol import ViewerProtocol
+
+logger = logging.getLogger(__name__)
+
+
+class StartupMode(Enum):
+    """Server startup mode for external viewer detection."""
+
+    STANDALONE = "standalone"
+    AUTO_DETECT = "auto-detect"
+
+
+class ServerState:
+    """Encapsulates all mutable state for one MCP server instance."""
+
+    def __init__(
+        self,
+        mode: StartupMode = StartupMode.STANDALONE,
+        bridge_port: int | None = None,
+    ):
+        # Viewer
+        self.viewer: ViewerProtocol | None = None
+        self.viewer_lock: asyncio.Lock = asyncio.Lock()
+
+        # Mode
+        self.mode: StartupMode = mode
+        self.bridge_port: int = bridge_port or int(
+            os.environ.get("NAPARI_MCP_BRIDGE_PORT", "9999")
+        )
+
+        # Qt state
+        self.qt_app: Any | None = None
+        self.qt_pump_task: asyncio.Task | None = None
+        self.window_close_connected: bool = False
+        self.gui_executor: Any | None = None
+
+        # Server lifecycle
+        self._event_loop: asyncio.AbstractEventLoop | None = None
+        self._shutdown_requested: bool = False
+
+        # Execution namespace (persists across execute_code calls)
+        self.exec_globals: dict[str, Any] = {}
+
+        # Output storage
+        self.output_storage: dict[str, dict[str, Any]] = {}
+        self.output_storage_lock: asyncio.Lock = asyncio.Lock()
+        self.next_output_id: int = 1
+        try:
+            self.max_output_items: int = int(
+                os.environ.get("NAPARI_MCP_MAX_OUTPUT_ITEMS", "1000")
+            )
+        except Exception:
+            self.max_output_items = 1000
+
+    def request_shutdown(self, delay: float = 1.0) -> None:
+        """Request the MCP server to shut down.
+
+        Safe to call from any thread (e.g. the Qt main thread when the
+        viewer window is destroyed).
+
+        Parameters
+        ----------
+        delay : float
+            Seconds to wait before stopping the event loop.  A short delay
+            allows any in-flight MCP responses (e.g. from ``close_viewer``)
+            to be flushed before the loop halts.
+        """
+        if self._shutdown_requested:
+            return
+        self._shutdown_requested = True
+        logger.info("Server shutdown requested (viewer closed)")
+
+        loop = self._event_loop
+        if loop is not None and not loop.is_closed():
+            try:
+                loop.call_soon_threadsafe(lambda: loop.call_later(delay, loop.stop))
+            except RuntimeError:
+                pass
+
+    def gui_execute(self, operation: Any) -> Any:
+        """Run operation through GUI executor if set, else directly."""
+        if self.gui_executor is not None:
+            return self.gui_executor(operation)
+        return operation()
+
+    async def store_output(
+        self,
+        tool_name: str,
+        stdout: str = "",
+        stderr: str = "",
+        result_repr: str | None = None,
+        **metadata: Any,
+    ) -> str:
+        """Store tool output and return a unique ID."""
+        async with self.output_storage_lock:
+            output_id = str(self.next_output_id)
+            self.next_output_id += 1
+
+            self.output_storage[output_id] = {
+                "tool_name": tool_name,
+                "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+                "stdout": stdout,
+                "stderr": stderr,
+                "result_repr": result_repr,
+                **metadata,
+            }
+            # Evict oldest items if exceeding capacity
+            if (
+                self.max_output_items > 0
+                and len(self.output_storage) > self.max_output_items
+            ):
+                overflow = len(self.output_storage) - self.max_output_items
+                for victim in sorted(self.output_storage.keys(), key=lambda k: int(k))[
+                    :overflow
+                ]:
+                    self.output_storage.pop(victim, None)
+
+            return output_id
+
+    async def proxy_to_external(
+        self, tool_name: str, params: dict[str, Any] | None = None
+    ) -> Any | None:
+        """Proxy a tool call to an external viewer if in AUTO_DETECT mode.
+
+        Returns None immediately in STANDALONE mode (zero overhead).
+        """
+        if self.mode != StartupMode.AUTO_DETECT:
+            return None
+
+        try:
+            from fastmcp import Client
+
+            client = Client(f"http://localhost:{self.bridge_port}/mcp")
+            async with client:
+                result = await client.call_tool(tool_name, params or {})
+                if hasattr(result, "content"):
+                    content = result.content
+                    if content[0].type == "text":
+                        response = (
+                            content[0].text
+                            if hasattr(content[0], "text")
+                            else str(content[0])
+                        )
+                        try:
+                            return json.loads(response)
+                        except json.JSONDecodeError:
+                            return {
+                                "status": "error",
+                                "message": f"Invalid JSON response: {response}",
+                            }
+                    else:
+                        return content
+                return {
+                    "status": "error",
+                    "message": "Invalid response format from external viewer",
+                }
+        except Exception:
+            return None
+
+    async def detect_external_viewer(
+        self,
+    ) -> tuple[bool, dict[str, Any] | None]:
+        """Detect if an external napari viewer is available via MCP bridge.
+
+        Returns
+        -------
+        tuple of (found, info)
+            found is True if an external bridge was detected, False otherwise.
+            info is the session information dict when found, else None.
+        """
+        if self.mode != StartupMode.AUTO_DETECT:
+            return False, None
+
+        try:
+            from fastmcp import Client
+
+            client = Client(f"http://localhost:{self.bridge_port}/mcp")
+            async with client:
+                result = await client.call_tool("session_information")
+                if result and hasattr(result, "content"):
+                    content = result.content
+                    if isinstance(content, list) and len(content) > 0:
+                        info = (
+                            content[0].text
+                            if hasattr(content[0], "text")
+                            else str(content[0])
+                        )
+                        info_dict = json.loads(info) if isinstance(info, str) else info
+                        if info_dict.get("session_type") == "napari_bridge_session":
+                            return True, info_dict
+                return False, None
+        except Exception:
+            return False, None
+
+    async def external_session_information(self) -> dict[str, Any]:
+        """Get session information from the external viewer."""
+        from fastmcp import Client
+
+        test_client = Client(f"http://localhost:{self.bridge_port}/mcp")
+        async with test_client:
+            result = await test_client.call_tool("session_information")
+            if hasattr(result, "content"):
+                content = result.content
+                if isinstance(content, list) and len(content) > 0:
+                    info = (
+                        content[0].text
+                        if hasattr(content[0], "text")
+                        else str(content[0])
+                    )
+                    info_dict = json.loads(info) if isinstance(info, str) else info
+                    if info_dict.get("session_type") == "napari_bridge_session":
+                        return {
+                            "status": "ok",
+                            "viewer_type": "external",
+                            "title": info_dict.get("viewer", {}).get(
+                                "title", "External Viewer"
+                            ),
+                            "layers": info_dict.get("viewer", {}).get(
+                                "layer_names", []
+                            ),
+                            "port": info_dict.get("bridge_port", self.bridge_port),
+                        }
+
+        return {
+            "status": "error",
+            "message": "Failed to get session information from external viewer",
+        }
diff --git a/src/napari_mcp/viewer_protocol.py b/src/napari_mcp/viewer_protocol.py
new file mode 100644
index 0000000..cb5c968
--- /dev/null
+++ b/src/napari_mcp/viewer_protocol.py
@@ -0,0 +1,61 @@
+"""Protocol definition for napari viewer backends."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ViewerProtocol(Protocol):
+    """Structural protocol for viewer backends.
+
+    Both a real ``napari.Viewer`` and a bridge-proxied viewer satisfy this
+    protocol without requiring inheritance.
+    """
+
+    title: str
+    layers: Any  # napari LayerList or compatible collection
+    dims: Any  # .ndisplay, .current_step, .set_current_step(), .nsteps
+    camera: Any  # .center, .zoom, .angles
+    grid: Any  # .enabled
+    window: Any  # ._qt_window (optional, used for Qt integration)
+
+    def add_image(self, data: Any, **kwargs: Any) -> Any:
+        """Add an image layer."""
+        ...
+
+    def add_labels(self, data: Any, **kwargs: Any) -> Any:
+        """Add a labels layer."""
+        ...
+
+    def add_points(self, data: Any, **kwargs: Any) -> Any:
+        """Add a points layer."""
+        ...
+
+    def add_shapes(self, data: Any, **kwargs: Any) -> Any:
+        """Add a shapes layer."""
+        ...
+
+    def add_vectors(self, data: Any, **kwargs: Any) -> Any:
+        """Add a vectors layer."""
+        ...
+
+    def add_tracks(self, data: Any, **kwargs: Any) -> Any:
+        """Add a tracks layer."""
+        ...
+
+    def add_surface(self, data: Any, **kwargs: Any) -> Any:
+        """Add a surface layer."""
+        ...
+
+    def screenshot(self, **kwargs: Any) -> Any:
+        """Take a screenshot, returning a numpy array."""
+        ...
+
+    def reset_view(self) -> None:
+        """Reset camera view to fit data."""
+        ...
+
+    def close(self) -> None:
+        """Close the viewer."""
+        ...
diff --git a/src/napari_mcp/widget.py b/src/napari_mcp/widget.py
index cc4e3d8..7c17d70 100644
--- a/src/napari_mcp/widget.py
+++ b/src/napari_mcp/widget.py
@@ -167,13 +167,14 @@ def _setup_ui(self):
     def _on_port_changed(self, value: int):
         """Handle port change."""
         self.port = value
-        if self.server and self.server.is_running:
-            self.info_text.append("Note: Port change will take effect after restart.")
-        # Always warn the user that the LLM agent must use the same port
-        self.info_text.append(
-            f"WARNING: Port changed to {self.port}. Make sure your LLM agent "
-            f"is configured to connect to http://localhost:{self.port}/mcp."
+        msg = (
+            f"Port set to {self.port}.\n\n"
+            f"Make sure your LLM agent is configured to connect to "
+            f"http://localhost:{self.port}/mcp."
         )
+        if self.server and self.server.is_running:
+            msg += "\n\nNote: Port change will take effect after restart."
+        self.info_text.setPlainText(msg)
 
     def _start_server(self):
         """Start the MCP server."""
@@ -188,6 +189,12 @@ def _start_server(self):
                     f"customize the port, ensure your LLM agent is configured to "
                     f"use the same URL."
                 )
+            else:
+                self._update_ui_state(running=False)
+                self.info_text.setPlainText(
+                    f"Failed to start server on port {self.port}.\n\n"
+                    f"The port may already be in use. Try a different port."
+                )
 
     def _stop_server(self):
         """Stop the MCP server."""
diff --git a/tests/conftest.py b/tests/conftest.py
index 5db505b..25f06d1 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,16 +1,10 @@
 """Pytest configuration for napari-mcp tests."""
 
-# Import napari's official pytest fixtures (e.g., make_napari_viewer)
-# pytest_plugins = ("napari.utils._testsupport",)
-
-import contextlib
-import os
-import sys
+import logging
 
 import pytest
 
-# Add src directories to path for all tests
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+logger = logging.getLogger(__name__)
 
 
 # =============================================================================
@@ -22,56 +16,60 @@
 def patch_viewer_creation(monkeypatch):
     """Patch viewer creation to prevent creating viewers without make_napari_viewer.
 
-    This ensures that init_viewer() and other functions don't create new viewers
+    This ensures that ensure_viewer() and other functions don't create new viewers
     when we already have one from make_napari_viewer.
     """
     from napari_mcp import server as napari_mcp_server
+    from napari_mcp.qt_helpers import ensure_viewer as original_ensure_viewer
 
-    # Store the original _ensure_viewer function
-    original_ensure_viewer = napari_mcp_server._ensure_viewer
-
-    def patched_ensure_viewer():
+    def patched_ensure_viewer(state):
         """Patched version that returns existing viewer if available."""
-        # If a viewer already exists (set by make_napari_viewer), return it
-        if napari_mcp_server._viewer is not None:
-            return napari_mcp_server._viewer
-        # Otherwise call the original function
-        return original_ensure_viewer()
-
-    # Monkey-patch the function
-    monkeypatch.setattr(napari_mcp_server, "_ensure_viewer", patched_ensure_viewer)
+        if state.viewer is not None:
+            return state.viewer
+        return original_ensure_viewer(state)
+
+    monkeypatch.setattr("napari_mcp.qt_helpers.ensure_viewer", patched_ensure_viewer)
+    # Also patch the imported reference in server module
+    monkeypatch.setattr(napari_mcp_server, "ensure_viewer", patched_ensure_viewer)
     yield
 
 
 @pytest.fixture(autouse=True)
-def reset_server_state():
-    """Reset all global state in server module before and after each test."""
+def reset_server_state(monkeypatch):
+    """Reset all server state before and after each test.
+
+    Creates a fresh ServerState in STANDALONE mode (proxy always returns None)
+    and calls create_server() to register tool functions as module-level names.
+
+    """
     try:
         from napari_mcp import server as napari_mcp_server
+        from napari_mcp.server import create_server
+        from napari_mcp.state import ServerState, StartupMode
 
-        # Reset state before test
-        napari_mcp_server._viewer = None
-        napari_mcp_server._window_close_connected = False
-        napari_mcp_server._exec_globals = {}
-        if hasattr(napari_mcp_server, "_qt_pump_task"):
-            napari_mcp_server._qt_pump_task = None
+        # Create fresh state for each test in STANDALONE mode
+        fresh_state = ServerState(mode=StartupMode.STANDALONE)
+        napari_mcp_server._state = fresh_state
+
+        # Register tool functions as module-level names
+        create_server(fresh_state)
 
         yield
 
         # Clean up after test
-        if napari_mcp_server._viewer is not None:
+        if fresh_state.viewer is not None:
             try:
-                napari_mcp_server._viewer.close()
-            except Exception:  # noqa: BLE001
-                pass  # Cleanup, ignore errors
-        napari_mcp_server._viewer = None
-        napari_mcp_server._window_close_connected = False
-        napari_mcp_server._exec_globals = {}
-        if hasattr(napari_mcp_server, "_qt_pump_task"):
-            napari_mcp_server._qt_pump_task = None
+                fresh_state.viewer.close()
+            except Exception:
+                pass
+        fresh_state.viewer = None
+        fresh_state.window_close_connected = False
+        fresh_state.exec_globals = {}
+        fresh_state.qt_pump_task = None
+        fresh_state._shutdown_requested = False
+        fresh_state._event_loop = None
 
     except ImportError:
-        # Server module not imported in this test
         yield
 
 
@@ -79,27 +77,16 @@ def reset_server_state():
 def _materialize_viewer_when_requested(request):
     """If a test declares the make_napari_viewer fixture but never calls it,
     create one proactively so napari's leak checker tracks and cleans it.
-
-    This prevents leftover QtViewer instances when our server lazily creates
-    a viewer (e.g., on reset_view()) even if the test didn't explicitly call
-    make_napari_viewer().
     """
-    if "make_napari_viewer" in getattr(request, "fixturenames", ()):  # type: ignore[attr-defined]
+    if "make_napari_viewer" in getattr(request, "fixturenames", ()):
         try:
             factory = request.getfixturevalue("make_napari_viewer")
-            # Only create if none exist yet to avoid duplicates when tests call it
             created = getattr(request.node, "_auto_created_napari_viewer", False)
             if not created:
-                viewer = factory()
+                factory()
                 request.node._auto_created_napari_viewer = True
-                # ensure window exists so pytest-qt can manage it
-                with contextlib.suppress(Exception):
-                    if hasattr(viewer, "window") and hasattr(
-                        viewer.window, "_qt_window"
-                    ):
-                        pass
         except Exception:
-            pass
+            logger.debug("Failed to auto-create napari viewer", exc_info=True)
 
 
 # =============================================================================
diff --git a/tests/fixtures/__init__.py b/tests/fixtures/__init__.py
deleted file mode 100644
index f5233f9..0000000
--- a/tests/fixtures/__init__.py
+++ /dev/null
@@ -1,6 +0,0 @@
-"""Test fixtures for napari-mcp."""
-
-# This module now contains no exports as all mocking has been removed
-# in favor of using napari's built-in make_napari_viewer fixture
-
-__all__ = []
diff --git a/tests/fixtures/async_utils.py b/tests/fixtures/async_utils.py
deleted file mode 100644
index fc146fa..0000000
--- a/tests/fixtures/async_utils.py
+++ /dev/null
@@ -1,258 +0,0 @@
-"""Async utilities for proper test synchronization and timing."""
-
-import asyncio
-import time
-from collections.abc import Callable
-from contextlib import asynccontextmanager
-from typing import Any
-
-
-async def wait_for_condition(
-    condition: Callable[[], bool],
-    timeout: float = 1.0,
-    poll_interval: float = 0.01,
-    error_message: str | None = None,
-) -> None:
-    """Wait for a condition to become true with timeout.
-
-    Args:
-        condition: Callable that returns True when condition is met
-        timeout: Maximum time to wait in seconds
-        poll_interval: Time between condition checks in seconds
-        error_message: Custom error message if timeout occurs
-
-    Raises:
-        TimeoutError: If condition is not met within timeout
-    """
-    start_time = time.time()
-    while not condition():
-        if time.time() - start_time > timeout:
-            msg = error_message or f"Condition not met within {timeout} seconds"
-            raise TimeoutError(msg)
-        await asyncio.sleep(poll_interval)
-
-
-async def wait_for_async_condition(
-    async_condition: Callable[[], Any],
-    timeout: float = 1.0,
-    poll_interval: float = 0.01,
-    error_message: str | None = None,
-) -> None:
-    """Wait for an async condition to become true with timeout.
-
-    Args:
-        async_condition: Async callable that returns True when condition is met
-        timeout: Maximum time to wait in seconds
-        poll_interval: Time between condition checks in seconds
-        error_message: Custom error message if timeout occurs
-
-    Raises:
-        TimeoutError: If condition is not met within timeout
-    """
-    start_time = time.time()
-    while not await async_condition():
-        if time.time() - start_time > timeout:
-            msg = error_message or f"Async condition not met within {timeout} seconds"
-            raise TimeoutError(msg)
-        await asyncio.sleep(poll_interval)
-
-
-@asynccontextmanager
-async def timeout_context(seconds: float, error_message: str | None = None):
-    """Context manager for operations with timeout.
-
-    Args:
-        seconds: Timeout in seconds
-        error_message: Custom error message if timeout occurs
-
-    Raises:
-        asyncio.TimeoutError: If operation doesn't complete within timeout
-    """
-    try:
-        async with asyncio.timeout(seconds):
-            yield
-    except asyncio.TimeoutError as err:
-        msg = error_message or f"Operation timed out after {seconds} seconds"
-        raise asyncio.TimeoutError(msg) from err
-
-
-class AsyncTestHelper:
-    """Helper class for async testing with proper cleanup."""
-
-    def __init__(self):
-        self.tasks = []
-        self.background_tasks = []
-
-    async def run_with_timeout(
-        self, coro, timeout: float = 1.0, cleanup: Callable | None = None
-    ) -> Any:
-        """Run a coroutine with timeout and optional cleanup.
-
-        Args:
-            coro: Coroutine to run
-            timeout: Timeout in seconds
-            cleanup: Optional cleanup function to call on timeout
-
-        Returns:
-            Result of the coroutine
-
-        Raises:
-            asyncio.TimeoutError: If coroutine doesn't complete within timeout
-        """
-        try:
-            async with asyncio.timeout(timeout):
-                return await coro
-        except asyncio.TimeoutError:
-            if cleanup:
-                await cleanup() if asyncio.iscoroutinefunction(cleanup) else cleanup()
-            raise
-
-    def create_background_task(self, coro) -> asyncio.Task:
-        """Create a background task that will be cleaned up automatically.
-
-        Args:
-            coro: Coroutine to run in background
-
-        Returns:
-            The created task
-        """
-        task = asyncio.create_task(coro)
-        self.background_tasks.append(task)
-        return task
-
-    async def cleanup_tasks(self) -> None:
-        """Cancel and cleanup all background tasks."""
-        for task in self.background_tasks:
-            if not task.done():
-                task.cancel()
-                try:
-                    await task
-                except asyncio.CancelledError:
-                    pass
-        self.background_tasks.clear()
-
-    async def wait_for_tasks(self, timeout: float = 1.0) -> None:
-        """Wait for all background tasks to complete.
-
-        Args:
-            timeout: Maximum time to wait for all tasks
-
-        Raises:
-            asyncio.TimeoutError: If tasks don't complete within timeout
-        """
-        if self.background_tasks:
-            async with asyncio.timeout(timeout):
-                await asyncio.gather(*self.background_tasks, return_exceptions=True)
-
-
-def replace_sleep_with_event(test_func):
-    """Decorator to replace time.sleep with proper event-based waiting.
-
-    This decorator patches time.sleep to use asyncio.sleep when in async context.
-    """
-    import functools
-    from unittest.mock import patch
-
-    @functools.wraps(test_func)
-    async def wrapper(*args, **kwargs):
-        original_sleep = time.sleep
-
-        def smart_sleep(seconds):
-            """Sleep that works in both sync and async contexts."""
-            try:
-                # Check if we're in an async context
-                loop = asyncio.get_event_loop()
-                if loop.is_running():
-                    # We're in async context, create a task
-                    loop.create_task(asyncio.sleep(seconds))
-                else:
-                    original_sleep(seconds)
-            except RuntimeError:
-                # No event loop, use regular sleep
-                original_sleep(seconds)
-
-        with patch("time.sleep", smart_sleep):
-            return await test_func(*args, **kwargs)
-
-    return wrapper
-
-
-class ServerStartupHelper:
-    """Helper for properly starting and stopping test servers."""
-
-    def __init__(self, server, startup_timeout: float = 2.0):
-        self.server = server
-        self.startup_timeout = startup_timeout
-
-    async def start_and_verify(self) -> bool:
-        """Start server and verify it's running.
-
-        Returns:
-            True if server started successfully
-
-        Raises:
-            TimeoutError: If server doesn't start within timeout
-        """
-        # Start the server
-        result = self.server.start()
-        if not result:
-            return False
-
-        # Wait for server to be fully running
-        await wait_for_condition(
-            lambda: self.server.is_running,
-            timeout=self.startup_timeout,
-            error_message="Server failed to start",
-        )
-
-        return True
-
-    async def stop_and_verify(self) -> bool:
-        """Stop server and verify it's stopped.
-
-        Returns:
-            True if server stopped successfully
-        """
-        if not self.server.is_running:
-            return True
-
-        result = self.server.stop()
-        if not result:
-            return False
-
-        # Wait for server to fully stop
-        await wait_for_condition(
-            lambda: not self.server.is_running,
-            timeout=1.0,
-            error_message="Server failed to stop",
-        )
-
-        return True
-
-
-# Qt-specific timing utilities
-
-
-def qt_process_events(qtbot, wait_ms: int = 10):
-    """Process Qt events with proper waiting.
-
-    Args:
-        qtbot: pytest-qt fixture
-        wait_ms: Time to wait in milliseconds
-    """
-    qtbot.wait(wait_ms)
-
-
-def qt_wait_for_signal(qtbot, signal, timeout: int = 1000):
-    """Wait for a Qt signal with timeout.
-
-    Args:
-        qtbot: pytest-qt fixture
-        signal: Qt signal to wait for
-        timeout: Timeout in milliseconds
-
-    Returns:
-        The signal arguments when emitted
-    """
-    with qtbot.waitSignal(signal, timeout=timeout) as blocker:
-        return blocker.args
diff --git a/tests/test_base_installer.py b/tests/test_base_installer.py
index 0b25182..ff8bfcd 100644
--- a/tests/test_base_installer.py
+++ b/tests/test_base_installer.py
@@ -54,6 +54,15 @@ def test_initialization_with_options(self):
         assert installer.backup is False
         assert installer.dry_run is True
 
+    def test_initialization_with_napari_backend(self):
+        """Test installer initialization with a uv napari backend."""
+        installer = ConcreteInstaller(
+            app_key="test-app",
+            napari_backend="napari[pyqt6]",
+        )
+
+        assert installer.napari_backend == "napari[pyqt6]"
+
     @patch("napari_mcp.cli.install.base.get_app_display_name")
     def test_app_name_resolution(self, mock_get_name):
         """Test application display name is resolved."""
@@ -136,6 +145,45 @@ def test_install_new_config(
         # Verify build_server_config was called with correct signature
         mock_build_config.assert_called_with(False, None, {"timeout": 60000})
 
+    @patch("napari_mcp.cli.install.base.read_json_config")
+    @patch("napari_mcp.cli.install.base.write_json_config")
+    @patch("napari_mcp.cli.install.base.build_server_config")
+    @patch("napari_mcp.cli.install.base.get_python_executable")
+    @patch("napari_mcp.cli.install.base.console")
+    def test_install_new_config_with_napari_backend(
+        self, mock_console, mock_get_exe, mock_build_config, mock_write, mock_read
+    ):
+        """Test installing with an extra napari backend requirement."""
+        mock_read.return_value = {}
+        mock_write.return_value = True
+        mock_get_exe.return_value = ("uv", "ephemeral uv")
+        mock_build_config.return_value = {
+            "command": "uv",
+            "args": [
+                "run",
+                "--with",
+                "napari-mcp",
+                "--with",
+                "napari[pyqt6]",
+                "napari-mcp",
+            ],
+        }
+
+        installer = ConcreteInstaller(
+            app_key="test-app",
+            napari_backend="napari[pyqt6]",
+        )
+        success, message = installer.install()
+
+        assert success is True
+        assert "successful" in message.lower()
+        mock_build_config.assert_called_with(
+            False,
+            None,
+            {"timeout": 60000},
+            napari_requirement="napari[pyqt6]",
+        )
+
     @patch("napari_mcp.cli.install.base.read_json_config")
     @patch("napari_mcp.cli.install.base.write_json_config")
     @patch("napari_mcp.cli.install.base.check_existing_server")
diff --git a/tests/test_bridge_server.py b/tests/test_bridge_server.py
index 4624a43..828881c 100644
--- a/tests/test_bridge_server.py
+++ b/tests/test_bridge_server.py
@@ -4,15 +4,15 @@
 
 import numpy as np
 import pytest
+from qtpy.QtCore import QThread
 
-# Add the plugin to path for testing (no longer needed with unified package)
 from napari_mcp.bridge_server import NapariBridgeServer, QtBridge
 
 
 @pytest.fixture
-def bridge_server(make_napari_viewer_proxy):
+def bridge_server(make_napari_viewer):
     """Create a bridge server instance with proper cleanup."""
-    viewer = make_napari_viewer_proxy()
+    viewer = make_napari_viewer()
     viewer.title = "Test Viewer"  # Set expected title
     server = NapariBridgeServer(viewer, port=9999)
     yield server
@@ -61,17 +61,35 @@ def test_start_stop(self, mock_thread_class, bridge_server):
         assert result is True
         assert not bridge_server.is_running
 
-    def test_encode_png_base64(self, bridge_server):
-        """Test PNG encoding."""
-        # Create a simple test image
-        img = np.ones((10, 10, 3), dtype=np.uint8) * 255
-        result = bridge_server._encode_png_base64(img)
+    def test_server_has_tools_registered(self, make_napari_viewer):
+        """Test that server has tools registered after setup."""
+        viewer = make_napari_viewer()
+        server = NapariBridgeServer(viewer)
+        assert hasattr(server.server, "tool")
+
+    def test_lifecycle_tools_excluded(self, make_napari_viewer):
+        """Bridge server must NOT expose viewer lifecycle tools.
 
-        assert "mime_type" in result
-        assert result["mime_type"] == "image/png"
-        assert "base64_data" in result
-        assert isinstance(result["base64_data"], str)
-        assert len(result["base64_data"]) > 0
+        When running from napari, the viewer is managed by napari itself.
+        Allowing an agent to close/init/detect viewers would be disruptive.
+        """
+        viewer = make_napari_viewer()
+        server = NapariBridgeServer(viewer)
+        tool_names = set(server.server._tool_manager._tools.keys())
+        for excluded in ("close_viewer", "init_viewer"):
+            assert excluded not in tool_names, (
+                f"{excluded} should not be available in bridge mode"
+            )
+        # Sanity: other tools should still be present
+        for expected in (
+            "session_information",
+            "execute_code",
+            "list_layers",
+            "screenshot",
+        ):
+            assert expected in tool_names, (
+                f"{expected} should be available in bridge mode"
+            )
 
 
 class TestQtBridge:
@@ -86,35 +104,98 @@ def test_run_in_main_thread(self, qtbot):
         """Test running operation in main thread."""
         from threading import Thread
 
-        # Create bridge
         bridge = QtBridge()
-
-        # Track results
         results = []
 
         def test_operation():
-            """Operation to run in main thread."""
             results.append("executed")
             return "test_result"
 
-        # Test from a different thread
         def run_from_thread():
             result = bridge.run_in_main_thread(test_operation)
             results.append(result)
 
-        # Run operation from a separate thread
         thread = Thread(target=run_from_thread)
         thread.start()
-
-        # Process Qt events to handle the signal
-        qtbot.wait(100)  # Wait for signal to be processed
-
+        qtbot.wait(100)
         thread.join(timeout=1.0)
 
-        # Check results
         assert "executed" in results
         assert "test_result" in results
 
+    @patch("napari_mcp.bridge_server.Future")
+    def test_operation_execution(self, mock_future_class):
+        """Test operation execution mechanism."""
+        bridge = QtBridge()
+        mock_future = Mock()
+        mock_future_class.return_value = mock_future
+
+        test_result = "test_result"
+        operation = Mock(return_value=test_result)
+
+        bridge._execute_operation(operation, mock_future)
+        mock_future.set_result.assert_called_once_with(test_result)
+
+    @patch("napari_mcp.bridge_server.Future")
+    def test_operation_exception(self, mock_future_class):
+        """Test exception handling in operation execution."""
+        bridge = QtBridge()
+        mock_future = Mock()
+        mock_future_class.return_value = mock_future
+
+        test_error = ValueError("Test error")
+        operation = Mock(side_effect=test_error)
+
+        bridge._execute_operation(operation, mock_future)
+        mock_future.set_exception.assert_called_once_with(test_error)
+
+
+class TestBridgeServerIntegration:
+    """Integration tests for the bridge server."""
+
+    def test_viewer_operations(self, make_napari_viewer):
+        """Test that viewer operations are properly set up."""
+        viewer = make_napari_viewer()
+        server = NapariBridgeServer(viewer)
+        assert server.viewer == viewer
+        assert isinstance(server.state.exec_globals, dict)
+
+    def test_multiple_server_instances(self, make_napari_viewer):
+        """Test creating multiple server instances with different ports."""
+        viewer1 = make_napari_viewer()
+        server1 = NapariBridgeServer(viewer1, port=9998)
+        viewer2 = make_napari_viewer()
+        server2 = NapariBridgeServer(viewer2, port=9999)
+
+        assert server1.port == 9998
+        assert server2.port == 9999
+        assert server1.server != server2.server
+
+    @patch("threading.Thread")
+    def test_start_stop_threading(self, mock_thread_class, make_napari_viewer):
+        """Test server start/stop with threading."""
+        viewer = make_napari_viewer()
+        server = NapariBridgeServer(viewer)
+
+        mock_thread = Mock()
+        mock_thread.is_alive.return_value = False
+        mock_thread_class.return_value = mock_thread
+
+        result = server.start()
+        assert result is True
+        mock_thread_class.assert_called_once()
+        mock_thread.start.assert_called_once()
+
+        mock_thread.is_alive.return_value = True
+        result = server.start()
+        assert result is False
+
+        server.thread = mock_thread
+        server.loop = Mock()
+        result = server.stop()
+        assert result is True
+        mock_thread.join.assert_called_once_with(timeout=2)
+
 
 class TestBridgeServerTools:
     """Test the MCP tools exposed by the bridge server."""
@@ -122,15 +203,13 @@ class TestBridgeServerTools:
     @pytest.mark.asyncio
     async def test_session_information_tool(self, bridge_server):
         """Test session_information tool."""
-        # Mock the Qt bridge to avoid thread issues in tests
         with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
-            # Set up mock to execute the function directly
-            def execute_directly(func):
+
+            def execute_directly(func, **kwargs):
                 return func()
 
             mock_run.side_effect = execute_directly
 
-            # Find and execute the session_information tool
             tools = await bridge_server.server.get_tools()
             for name, tool in tools.items():
                 if name == "session_information":
@@ -139,7 +218,6 @@ def execute_directly(func):
             else:
                 pytest.fail("session_information tool not found")
 
-            # Check result
             assert result["status"] == "ok"
             assert result["session_type"] == "napari_bridge_session"
             assert result["bridge_port"] == 9999
@@ -151,7 +229,7 @@ async def test_list_layers_empty(self, bridge_server):
         """Test list_layers with no layers."""
         with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
 
-            def execute_directly(func):
+            def execute_directly(func, **kwargs):
                 return func()
 
             mock_run.side_effect = execute_directly
@@ -170,7 +248,6 @@ def execute_directly(func):
     @pytest.mark.asyncio
     async def test_list_layers_with_layers(self, bridge_server):
         """Test list_layers with some layers."""
-
         bridge_server.viewer.add_image(
             np.random.random((100, 100)), name="Layer 1", colormap="viridis"
         )
@@ -183,7 +260,7 @@ async def test_list_layers_with_layers(self, bridge_server):
 
         with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
 
-            def execute_directly(func):
+            def execute_directly(func, **kwargs):
                 return func()
 
             mock_run.side_effect = execute_directly
@@ -207,7 +284,7 @@ async def test_execute_code_simple(self, bridge_server):
         """Test execute_code with simple Python code."""
         with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
 
-            def execute_directly(func):
+            def execute_directly(func, **kwargs):
                 return func()
 
             mock_run.side_effect = execute_directly
@@ -230,7 +307,7 @@ async def test_execute_code_with_viewer(self, bridge_server):
         """Test execute_code with viewer access."""
         with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
 
-            def execute_directly(func):
+            def execute_directly(func, **kwargs):
                 return func()
 
             mock_run.side_effect = execute_directly
@@ -249,7 +326,7 @@ async def test_execute_code_error(self, bridge_server):
         """Test execute_code with error."""
         with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
 
-            def execute_directly(func):
+            def execute_directly(func, **kwargs):
                 return func()
 
             mock_run.side_effect = execute_directly
@@ -263,6 +340,108 @@ def execute_directly(func):
             assert result["status"] == "error"
             assert "ZeroDivisionError" in result["stderr"]
 
+    @pytest.mark.asyncio
+    async def test_screenshot_tool(self, bridge_server):
+        """Test screenshot tool returns PNG data."""
+        # Add an image so there's something to screenshot
+        bridge_server.viewer.add_image(np.random.random((50, 50)), name="test_img")
+
+        with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
+
+            def execute_directly(func, **kwargs):
+                return func()
+
+            mock_run.side_effect = execute_directly
+
+            tools = await bridge_server.server.get_tools()
+            for name, tool in tools.items():
+                if name == "screenshot":
+                    result = await tool.fn(True)
+                    break
+            else:
+                pytest.fail("screenshot tool not found")
+
+            # Result is an ImageContent object from FastMCP
+            assert hasattr(result, "mimeType") or isinstance(result, dict)
+            if hasattr(result, "mimeType"):
+                assert result.mimeType.lower() in ("png", "image/png")
+                assert result.data is not None
+                assert len(result.data) > 0
+            else:
+                assert result["mime_type"] == "image/png"
+                assert len(result["base64_data"]) > 0
+
+
+class TestBridgeTimeoutBehavior:
+    """Test timeout handling in the bridge server."""
+
+    @pytest.mark.asyncio
+    async def test_execute_code_timeout_returns_error_dict(self, bridge_server):
+        """Test that execute_code returns a structured error on timeout."""
+        with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
+            mock_run.side_effect = TimeoutError("timed out")
+
+            tools = await bridge_server.server.get_tools()
+            for name, tool in tools.items():
+                if name == "execute_code":
+                    result = await tool.fn("import time; time.sleep(9999)")
+                    break
+            else:
+                pytest.fail("execute_code tool not found")
+
+            assert result["status"] == "error"
+            assert "timed out" in result["stderr"]
+            assert "600s" in result["stderr"]
+            assert result["stdout"] == ""
+
+    def test_run_in_main_thread_timeout_message(self, qtbot):
+        """Test that QtBridge timeout produces an actionable error message."""
+        bridge = QtBridge()
+        mock_future = Mock()
+        mock_future.result.side_effect = TimeoutError()
+
+        with (
+            patch("napari_mcp.bridge_server.Future", return_value=mock_future),
+            patch.object(QThread, "currentThread") as mock_ct,
+        ):
+            # Ensure we take the cross-thread path
+            mock_ct.return_value = Mock()
+
+            with pytest.raises(
+                TimeoutError, match="napari bridge operation timed out after 10s"
+            ):
+                bridge.run_in_main_thread(lambda: None, timeout=10.0)
+
+    def test_run_in_main_thread_custom_timeout_forwarded(self, qtbot):
+        """Test that custom timeout value is forwarded to Future.result()."""
+        bridge = QtBridge()
+        mock_future = Mock()
+        mock_future.result.return_value = "ok"
+
+        with (
+            patch("napari_mcp.bridge_server.Future", return_value=mock_future),
+            patch.object(QThread, "currentThread") as mock_ct,
+        ):
+            mock_ct.return_value = Mock()
+
+            bridge.run_in_main_thread(lambda: None, timeout=42.0)
+            mock_future.result.assert_called_once_with(timeout=42.0)
+
+    def test_run_in_main_thread_default_timeout(self, qtbot):
+        """Test that default timeout is 300s (5 minutes)."""
+        bridge = QtBridge()
+        mock_future = Mock()
+        mock_future.result.return_value = "ok"
+
+        with (
+            patch("napari_mcp.bridge_server.Future", return_value=mock_future),
+            patch.object(QThread, "currentThread") as mock_ct,
+        ):
+            mock_ct.return_value = Mock()
+
+            bridge.run_in_main_thread(lambda: None)
+            mock_future.result.assert_called_once_with(timeout=300.0)
+
 
 class TestBridgeServerLayerOperations:
     """Test layer manipulation operations."""
@@ -270,10 +449,9 @@ class TestBridgeServerLayerOperations:
     @pytest.mark.asyncio
     async def test_add_image_from_data(self, bridge_server):
         """Test adding an image from data."""
-
         with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
 
-            def execute_directly(func):
+            def execute_directly(func, **kwargs):
                 return func()
 
             mock_run.side_effect = execute_directly
@@ -282,8 +460,10 @@ def execute_directly(func):
 
             tools = await bridge_server.server.get_tools()
             for name, tool in tools.items():
-                if name == "add_image":
-                    result = await tool.fn(data=test_data, name="test", colormap="gray")
+                if name == "add_layer":
+                    result = await tool.fn(
+                        layer_type="image", data=test_data, name="test", colormap="gray"
+                    )
                     break
 
             assert result["status"] == "ok"
@@ -294,18 +474,36 @@ def execute_directly(func):
             assert bridge_server.viewer.layers["test"].data.shape == (2, 2)
             assert bridge_server.viewer.layers["test"].colormap.name == "gray"
 
+    @pytest.mark.asyncio
+    async def test_add_points_from_data(self, bridge_server):
+        """Test adding points via bridge add_layer — verifies type normalization."""
+        with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
+
+            def execute_directly(func, **kwargs):
+                return func()
+
+            mock_run.side_effect = execute_directly
+
+            tools = await bridge_server.server.get_tools()
+            tool = tools["add_layer"]
+            result = await tool.fn(
+                layer_type="points", data=[[1, 2], [3, 4]], name="pts"
+            )
+
+            assert result["status"] == "ok"
+            assert result["n_points"] == 2
+            assert "pts" in bridge_server.viewer.layers
+
     @pytest.mark.asyncio
     async def test_remove_layer(self, bridge_server):
         """Test removing a layer."""
-        # Ensure membership check succeeds by creating a real layer with that name
         import numpy as np
 
         layer = bridge_server.viewer.add_points(np.array([[0, 0]]), name="test_layer")
-        # Use real removal behavior; no patching needed on proxy
 
         with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
 
-            def execute_directly(func):
+            def execute_directly(func, **kwargs):
                 return func()
 
             mock_run.side_effect = execute_directly
@@ -313,12 +511,10 @@ def execute_directly(func):
             tools = await bridge_server.server.get_tools()
             for name, tool in tools.items():
                 if name == "remove_layer":
-                    # Pass the layer object to satisfy membership semantics
                     result = await tool.fn(layer)
                     break
 
             assert result["status"] == "removed"
-            # Verify layer is actually removed
             assert "test_layer" not in [lyr.name for lyr in bridge_server.viewer.layers]
 
     @pytest.mark.asyncio
@@ -328,7 +524,7 @@ async def test_remove_layer_not_found(self, bridge_server):
 
         with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
 
-            def execute_directly(func):
+            def execute_directly(func, **kwargs):
                 return func()
 
             mock_run.side_effect = execute_directly
@@ -341,3 +537,191 @@ def execute_directly(func):
 
             assert result["status"] == "not_found"
             assert result["name"] == "nonexistent"
+
+
+class TestBridgeAddLayerValidation:
+    """Test bridge add_layer validation matches standalone server."""
+
+    @pytest.mark.asyncio
+    async def test_path_rejected_for_non_image_types(self, bridge_server):
+        """Bridge add_layer should reject path for non-image/labels types."""
+        tools = await bridge_server.server.get_tools()
+        tool = tools["add_layer"]
+
+        result = await tool.fn(layer_type="points", path="/some/file.csv")
+        assert result["status"] == "error"
+        assert "only supported for image/labels" in result["message"]
+
+    @pytest.mark.asyncio
+    async def test_surface_requires_data_var(self, bridge_server):
+        """Bridge add_layer should require data_var for surface layers."""
+        tools = await bridge_server.server.get_tools()
+        tool = tools["add_layer"]
+
+        result = await tool.fn(layer_type="surface")
+        assert result["status"] == "error"
+        assert "data_var" in result["message"]
+        assert "surface" in result["message"].lower()
+
+    @pytest.mark.asyncio
+    async def test_multiple_data_sources_rejected(self, bridge_server):
+        """Bridge add_layer should reject multiple data sources."""
+        tools = await bridge_server.server.get_tools()
+        tool = tools["add_layer"]
+
+        result = await tool.fn(
+            layer_type="image", data=[[1, 2]], data_var="x", path="/nonexistent/img.tif"
+        )
+        assert result["status"] == "error"
+        assert "only ONE" in result["message"]
+
+    @pytest.mark.asyncio
+    async def test_unknown_layer_type_rejected(self, bridge_server):
+        """Bridge add_layer should reject unknown layer types."""
+        tools = await bridge_server.server.get_tools()
+        tool = tools["add_layer"]
+
+        result = await tool.fn(layer_type="mesh", data=[[1, 2]])
+        assert result["status"] == "error"
+        assert "Unknown" in result["message"]
+
+
+class TestBridgeExecuteCodeParity:
+    """Test that bridge execute_code matches server response shape."""
+
+    @pytest.mark.asyncio
+    async def test_execute_code_returns_output_id(self, bridge_server):
+        """Test that bridge execute_code returns output_id for later retrieval."""
+        with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
+
+            def execute_directly(func, **kwargs):
+                return func()
+
+            mock_run.side_effect = execute_directly
+
+            tools = await bridge_server.server.get_tools()
+            for name, tool in tools.items():
+                if name == "execute_code":
+                    result = await tool.fn("42")
+                    break
+
+            assert "output_id" in result
+            assert result["output_id"] == "1"
+
+            # Verify output is retrievable via read_output
+            for name, tool in tools.items():
+                if name == "read_output":
+                    stored = await tool.fn(result["output_id"])
+                    break
+            assert stored["status"] == "ok"
+            assert stored["tool_name"] == "execute_code"
+
+    @pytest.mark.asyncio
+    async def test_execute_code_line_limit_truncation(self, bridge_server):
+        """Test that bridge execute_code truncates output with line_limit."""
+        with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
+
+            def execute_directly(func, **kwargs):
+                return func()
+
+            mock_run.side_effect = execute_directly
+
+            tools = await bridge_server.server.get_tools()
+            for name, tool in tools.items():
+                if name == "execute_code":
+                    result = await tool.fn(
+                        "for i in range(50): print(f'line {i}')",
+                        line_limit=5,
+                    )
+                    break
+
+            assert result["status"] == "ok"
+            assert result["truncated"] is True
+            assert "output_id" in result
+            # stdout should have only 5 lines
+            assert result["stdout"].count("\n") <= 5
+
+    @pytest.mark.asyncio
+    async def test_execute_code_unlimited_output(self, bridge_server):
+        """Test that bridge execute_code with line_limit=-1 returns all output."""
+        with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
+
+            def execute_directly(func, **kwargs):
+                return func()
+
+            mock_run.side_effect = execute_directly
+
+            tools = await bridge_server.server.get_tools()
+            for name, tool in tools.items():
+                if name == "execute_code":
+                    result = await tool.fn("print('hello')", line_limit=-1)
+                    break
+
+            assert result["status"] == "ok"
+            assert "warning" in result
+            assert "large number of tokens" in result["warning"]
+
+
+class TestBridgeExecNamespace:
+    """Test that bridge execute_code injects correct namespace."""
+
+    @pytest.mark.asyncio
+    async def test_napari_module_available(self, bridge_server):
+        """Regression: bridge used to inject napari=None instead of the real module."""
+        with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
+
+            def execute_directly(func, **kwargs):
+                return func()
+
+            mock_run.side_effect = execute_directly
+
+            tools = await bridge_server.server.get_tools()
+            for name, tool in tools.items():
+                if name == "execute_code":
+                    result = await tool.fn("type(napari).__name__")
+                    break
+            else:
+                pytest.fail("execute_code tool not found")
+
+            assert result["status"] == "ok"
+            assert result["result_repr"] == "'module'"
+
+    @pytest.mark.asyncio
+    async def test_np_available(self, bridge_server):
+        """numpy should be available as 'np' in the exec namespace."""
+        with patch.object(bridge_server.qt_bridge, "run_in_main_thread") as mock_run:
+
+            def execute_directly(func, **kwargs):
+                return func()
+
+            mock_run.side_effect = execute_directly
+
+            tools = await bridge_server.server.get_tools()
+            for name, tool in tools.items():
+                if name == "execute_code":
+                    result = await tool.fn("int(np.array([1, 2, 3]).sum())")
+                    break
+
+            assert result["status"] == "ok"
+            assert result["result_repr"] == "6"
+
+
+class TestBridgeServerState:
+    """Test that bridge server properly creates its own state."""
+
+    def test_bridge_creates_standalone_state(self, make_napari_viewer):
+        from napari_mcp.state import StartupMode
+
+        viewer = make_napari_viewer()
+        bridge = NapariBridgeServer(viewer, port=9876)
+        assert bridge.state.mode == StartupMode.STANDALONE
+        assert bridge.state.viewer is viewer
+        assert bridge.state.gui_executor is not None
+        assert bridge.port == 9876
+
+    @pytest.mark.asyncio
+    async def test_bridge_does_not_proxy(self, make_napari_viewer):
+        viewer = make_napari_viewer()
+        bridge = NapariBridgeServer(viewer)
+        result = await bridge.state.proxy_to_external("any_tool")
+        assert result is None
diff --git a/tests/test_bridge_simplified.py b/tests/test_bridge_simplified.py
deleted file mode 100644
index fb65424..0000000
--- a/tests/test_bridge_simplified.py
+++ /dev/null
@@ -1,148 +0,0 @@
-"""Simplified tests for napari-mcp-bridge server functionality."""
-
-from unittest.mock import Mock, patch
-
-import numpy as np
-
-# Removed offscreen mode - it causes segfaults
-from napari_mcp.bridge_server import NapariBridgeServer, QtBridge
-
-# Removed custom make_napari_viewer fixture - using make_napari_viewer instead
-
-
-class TestNapariBridgeServer:
-    """Test the bridge server basic functionality."""
-
-    def test_initialization(self, make_napari_viewer):
-        """Test server initialization."""
-        viewer = make_napari_viewer()
-        server = NapariBridgeServer(viewer, port=8888)
-        assert server.viewer == viewer
-        assert server.port == 8888
-        assert server.server is not None
-        assert not server.is_running
-
-    def test_encode_png_base64(self, make_napari_viewer):
-        """Test PNG encoding."""
-        viewer = make_napari_viewer()
-        server = NapariBridgeServer(viewer)
-        # Create a simple test image
-        img = np.ones((10, 10, 3), dtype=np.uint8) * 255
-        result = server._encode_png_base64(img)
-
-        assert "mime_type" in result
-        assert result["mime_type"] == "image/png"
-        assert "base64_data" in result
-        assert isinstance(result["base64_data"], str)
-        assert len(result["base64_data"]) > 0
-
-    def test_server_has_tools_registered(self, make_napari_viewer):
-        """Test that server has tools registered after setup."""
-        viewer = make_napari_viewer()
-        server = NapariBridgeServer(viewer)
-        # The tools are registered during __init__ via _setup_tools()
-        # We can check that the server has tools by checking tool_manager
-        assert hasattr(server.server, "tool")
-        # FastMCP automatically registers tools when using @server.tool decorator
-
-
-class TestQtBridge:
-    """Test the Qt bridge for thread safety."""
-
-    def test_initialization(self):
-        """Test Qt bridge initialization."""
-        bridge = QtBridge()
-        assert bridge is not None
-
-    @patch("napari_mcp.bridge_server.Future")
-    def test_operation_execution(self, mock_future_class):
-        """Test operation execution mechanism."""
-        # Create bridge
-        bridge = QtBridge()
-
-        # Create a mock future
-        mock_future = Mock()
-        mock_future_class.return_value = mock_future
-
-        # Create a mock operation
-        test_result = "test_result"
-        operation = Mock(return_value=test_result)
-
-        # Simulate the execution (directly call the slot)
-        bridge._execute_operation(operation, mock_future)
-
-        # Check that the result was set on the future
-        mock_future.set_result.assert_called_once_with(test_result)
-
-    @patch("napari_mcp.bridge_server.Future")
-    def test_operation_exception(self, mock_future_class):
-        """Test exception handling in operation execution."""
-        bridge = QtBridge()
-
-        mock_future = Mock()
-        mock_future_class.return_value = mock_future
-
-        # Create an operation that raises an exception
-        test_error = ValueError("Test error")
-        operation = Mock(side_effect=test_error)
-
-        # Execute the operation
-        bridge._execute_operation(operation, mock_future)
-
-        # Check that the exception was set on the future
-        mock_future.set_exception.assert_called_once_with(test_error)
-
-
-class TestBridgeServerIntegration:
-    """Integration tests for the bridge server."""
-
-    def test_viewer_operations(self, make_napari_viewer):
-        """Test that viewer operations are properly set up."""
-        viewer = make_napari_viewer()
-        server = NapariBridgeServer(viewer)
-
-        # The server should have the viewer reference
-        assert server.viewer == viewer
-
-        # The exec globals should be initialized
-        assert isinstance(server._exec_globals, dict)
-
-    def test_multiple_server_instances(self, make_napari_viewer):
-        """Test creating multiple server instances with different ports."""
-        viewer1 = make_napari_viewer()
-        server1 = NapariBridgeServer(viewer1, port=9998)
-        viewer2 = make_napari_viewer()
-        server2 = NapariBridgeServer(viewer2, port=9999)
-
-        assert server1.port == 9998
-        assert server2.port == 9999
-        assert server1.server != server2.server
-
-    @patch("threading.Thread")
-    def test_start_stop_threading(self, mock_thread_class, make_napari_viewer):
-        """Test server start/stop with threading."""
-        server = viewer = make_napari_viewer()
-        server = NapariBridgeServer(viewer)
-
-        # Mock thread
-        mock_thread = Mock()
-        mock_thread.is_alive.return_value = False
-        mock_thread_class.return_value = mock_thread
-
-        # Start server
-        result = server.start()
-        assert result is True
-        mock_thread_class.assert_called_once()
-        mock_thread.start.assert_called_once()
-
-        # Try to start again (should return False)
-        mock_thread.is_alive.return_value = True
-        result = server.start()
-        assert result is False
-
-        # Stop server
-        server.thread = mock_thread
-        server.loop = Mock()
-        result = server.stop()
-        assert result is True
-        mock_thread.join.assert_called_once_with(timeout=2)
diff --git a/tests/test_cli_installer.py b/tests/test_cli_installer.py
index 91a993b..da19fcd 100644
--- a/tests/test_cli_installer.py
+++ b/tests/test_cli_installer.py
@@ -1,12 +1,24 @@
 """Tests for main CLI installer commands."""
 
+import re
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 import pytest
 from typer.testing import CliRunner
 
-from napari_mcp.cli.main import app
+from napari_mcp.cli.main import (
+    InstallTarget,
+    _get_installer_class,
+    app,
+)
+
+ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from CLI output."""
+    return ANSI_ESCAPE_RE.sub("", text)
 
 
 @pytest.fixture
@@ -39,8 +51,21 @@ def test_help_command(self, cli_runner):
         result = cli_runner.invoke(app, ["--help"])
         assert result.exit_code == 0
         assert "napari-mcp-install" in result.stdout
-        assert "claude-desktop" in result.stdout
-        assert "claude-code" in result.stdout
+        assert "install" in result.stdout
+
+    def test_install_help(self, cli_runner):
+        """Test install subcommand help."""
+        result = cli_runner.invoke(
+            app,
+            ["install", "--help"],
+            env={"FORCE_COLOR": "1"},
+        )
+        clean_output = strip_ansi(result.stdout)
+
+        assert result.exit_code == 0
+        assert "--backend" in clean_output
+        assert "claude-desktop" in clean_output
+        assert "cursor" in clean_output
 
     @patch("napari_mcp.cli.main.ClaudeDesktopInstaller")
     def test_claude_desktop_install(
@@ -49,7 +74,7 @@ def test_claude_desktop_install(
         """Test claude-desktop installation command."""
         mock_installer_class.return_value = mock_installer
 
-        result = cli_runner.invoke(app, ["claude-desktop"])
+        result = cli_runner.invoke(app, ["install", "claude-desktop"])
         assert result.exit_code == 0
         mock_installer.install.assert_called_once()
 
@@ -58,9 +83,14 @@ def test_claude_desktop_install_with_options(
         self, mock_installer_class, cli_runner
     ):
         """Test claude-desktop installation with options."""
+        mock = MagicMock()
+        mock.install.return_value = (True, "Success")
+        mock_installer_class.return_value = mock
+
         _ = cli_runner.invoke(
             app,
             [
+                "install",
                 "claude-desktop",
                 "--persistent",
                 "--python-path",
@@ -79,6 +109,60 @@ def test_claude_desktop_install_with_options(
         assert call_kwargs["backup"] is False
         assert call_kwargs["dry_run"] is True
 
+    @patch("napari_mcp.cli.main.ClaudeDesktopInstaller")
+    def test_claude_desktop_install_with_backend(
+        self, mock_installer_class, cli_runner
+    ):
+        """Test claude-desktop installation with a preset napari backend."""
+        mock = MagicMock()
+        mock.install.return_value = (True, "Success")
+        mock_installer_class.return_value = mock
+
+        result = cli_runner.invoke(
+            app,
+            ["install", "claude-desktop", "--backend", "pyqt6"],
+        )
+
+        assert result.exit_code == 0
+        call_kwargs = mock_installer_class.call_args[1]
+        assert call_kwargs["napari_backend"] == "napari[pyqt6]"
+
+    @patch("napari_mcp.cli.main.ClaudeDesktopInstaller")
+    def test_claude_desktop_install_with_custom_backend(
+        self, mock_installer_class, cli_runner
+    ):
+        """Test claude-desktop installation with a custom napari backend."""
+        mock = MagicMock()
+        mock.install.return_value = (True, "Success")
+        mock_installer_class.return_value = mock
+
+        result = cli_runner.invoke(
+            app,
+            ["install", "claude-desktop", "--backend", "pyside6"],
+        )
+
+        assert result.exit_code == 0
+        call_kwargs = mock_installer_class.call_args[1]
+        assert call_kwargs["napari_backend"] == "napari[pyside6]"
+
+    @patch("napari_mcp.cli.main.ClaudeDesktopInstaller")
+    def test_claude_desktop_install_with_backend_none(
+        self, mock_installer_class, cli_runner
+    ):
+        """Test claude-desktop installation can skip extra napari backend."""
+        mock = MagicMock()
+        mock.install.return_value = (True, "Success")
+        mock_installer_class.return_value = mock
+
+        result = cli_runner.invoke(
+            app,
+            ["install", "claude-desktop", "--backend", "none"],
+        )
+
+        assert result.exit_code == 0
+        call_kwargs = mock_installer_class.call_args[1]
+        assert call_kwargs["napari_backend"] is None
+
     @patch("napari_mcp.cli.main.ClaudeCodeInstaller")
     def test_claude_code_install(
         self, mock_installer_class, cli_runner, mock_installer
@@ -86,7 +170,7 @@ def test_claude_code_install(
         """Test claude-code installation command."""
         mock_installer_class.return_value = mock_installer
 
-        result = cli_runner.invoke(app, ["claude-code"])
+        result = cli_runner.invoke(app, ["install", "claude-code"])
         assert result.exit_code == 0
         mock_installer.install.assert_called_once()
 
@@ -97,7 +181,7 @@ def test_cursor_install_global(
         """Test cursor global installation."""
         mock_installer_class.return_value = mock_installer
 
-        result = cli_runner.invoke(app, ["cursor", "--global"])
+        result = cli_runner.invoke(app, ["install", "cursor", "--global"])
         assert result.exit_code == 0
 
         call_kwargs = mock_installer_class.call_args[1]
@@ -110,7 +194,9 @@ def test_cursor_install_project(
         """Test cursor project-specific installation."""
         mock_installer_class.return_value = mock_installer
 
-        result = cli_runner.invoke(app, ["cursor", "--project", "/path/to/project"])
+        result = cli_runner.invoke(
+            app, ["install", "cursor", "--project", "/path/to/project"]
+        )
         assert result.exit_code == 0
 
         call_kwargs = mock_installer_class.call_args[1]
@@ -123,7 +209,7 @@ def test_cline_vscode_install(
         """Test cline-vscode installation."""
         mock_installer_class.return_value = mock_installer
 
-        result = cli_runner.invoke(app, ["cline-vscode"])
+        result = cli_runner.invoke(app, ["install", "cline-vscode"])
         assert result.exit_code == 0
         mock_installer.install.assert_called_once()
 
@@ -134,7 +220,7 @@ def test_cline_cursor_install(
         """Test cline-cursor installation."""
         mock_installer_class.return_value = mock_installer
 
-        result = cli_runner.invoke(app, ["cline-cursor"])
+        result = cli_runner.invoke(app, ["install", "cline-cursor"])
         assert result.exit_code == 0
         mock_installer.install.assert_called_once()
 
@@ -143,7 +229,7 @@ def test_gemini_install(self, mock_installer_class, cli_runner, mock_installer):
         """Test gemini installation."""
         mock_installer_class.return_value = mock_installer
 
-        result = cli_runner.invoke(app, ["gemini", "--global"])
+        result = cli_runner.invoke(app, ["install", "gemini", "--global"])
         assert result.exit_code == 0
 
         call_kwargs = mock_installer_class.call_args[1]
@@ -154,7 +240,7 @@ def test_codex_install(self, mock_installer_class, cli_runner, mock_installer):
         """Test codex installation."""
         mock_installer_class.return_value = mock_installer
 
-        result = cli_runner.invoke(app, ["codex"])
+        result = cli_runner.invoke(app, ["install", "codex"])
         assert result.exit_code == 0
         mock_installer.install.assert_called_once()
 
@@ -165,7 +251,7 @@ def test_install_failure(self, mock_installer_class, cli_runner):
         mock.install.return_value = (False, "Installation failed")
         mock_installer_class.return_value = mock
 
-        result = cli_runner.invoke(app, ["claude-desktop"])
+        result = cli_runner.invoke(app, ["install", "claude-desktop"])
         assert result.exit_code == 1
 
 
@@ -191,7 +277,6 @@ def test_install_all_success(
         cli_runner,
     ):
         """Test successful installation for all applications."""
-        # Setup all mocks to return success
         for mock_class in [
             mock_claude_desktop,
             mock_claude_code,
@@ -205,7 +290,7 @@ def test_install_all_success(
             mock_instance.install.return_value = (True, "Success")
             mock_class.return_value = mock_instance
 
-        result = cli_runner.invoke(app, ["all"])
+        result = cli_runner.invoke(app, ["install", "all"])
         assert result.exit_code == 0
         assert "Installing napari-mcp for all supported applications" in result.stdout
 
@@ -215,17 +300,14 @@ def test_install_all_partial_failure(
         self, mock_claude_code, mock_claude_desktop, cli_runner
     ):
         """Test partial failure in install-all."""
-        # Claude Desktop succeeds
         mock_desktop = MagicMock()
         mock_desktop.install.return_value = (True, "Success")
         mock_claude_desktop.return_value = mock_desktop
 
-        # Claude Code fails
         mock_code = MagicMock()
         mock_code.install.return_value = (False, "Failed")
         mock_claude_code.return_value = mock_code
 
-        # Mock other installers to prevent actual instantiation
         with (
             patch("napari_mcp.cli.main.CursorInstaller"),
             patch("napari_mcp.cli.main.ClineVSCodeInstaller"),
@@ -233,7 +315,7 @@ def test_install_all_partial_failure(
             patch("napari_mcp.cli.main.GeminiCLIInstaller"),
             patch("napari_mcp.cli.main.CodexCLIInstaller"),
         ):
-            result = cli_runner.invoke(app, ["all"])
+            result = cli_runner.invoke(app, ["install", "all"])
             assert result.exit_code == 1
 
 
@@ -254,6 +336,10 @@ def test_uninstall_single_app(
     @patch("napari_mcp.cli.main.ClaudeDesktopInstaller")
     def test_uninstall_with_options(self, mock_installer_class, cli_runner):
         """Test uninstall with options."""
+        mock = MagicMock()
+        mock.uninstall.return_value = (True, "Success")
+        mock_installer_class.return_value = mock
+
         _ = cli_runner.invoke(
             app, ["uninstall", "claude-desktop", "--force", "--no-backup", "--dry-run"]
         )
@@ -266,20 +352,17 @@ def test_uninstall_with_options(self, mock_installer_class, cli_runner):
     def test_uninstall_invalid_app(self, cli_runner):
         """Test uninstall with invalid application name."""
         result = cli_runner.invoke(app, ["uninstall", "invalid-app"])
-        assert result.exit_code == 1
-        assert "Unknown application: invalid-app" in result.stdout
+        assert result.exit_code != 0
 
     @patch("napari_mcp.cli.main.ClaudeDesktopInstaller")
     @patch("napari_mcp.cli.main.ClaudeCodeInstaller")
     def test_uninstall_all(self, mock_claude_code, mock_claude_desktop, cli_runner):
         """Test uninstalling from all applications."""
-        # Setup mocks
         for mock_class in [mock_claude_desktop, mock_claude_code]:
             mock_instance = MagicMock()
             mock_instance.uninstall.return_value = (True, "Success")
             mock_class.return_value = mock_instance
 
-        # Mock other installers
         with (
             patch("napari_mcp.cli.main.CursorInstaller"),
             patch("napari_mcp.cli.main.ClineVSCodeInstaller"),
@@ -300,7 +383,6 @@ def test_list_installations(
         self, mock_claude_code, mock_claude_desktop, cli_runner
     ):
         """Test listing installations."""
-        # Setup mock config paths
         mock_desktop = MagicMock()
         mock_desktop.get_config_path.return_value = Path(
             "/mock/claude-desktop/config.json"
@@ -311,7 +393,6 @@ def test_list_installations(
         mock_code.get_config_path.return_value = Path("/mock/claude-code/config.json")
         mock_claude_code.return_value = mock_code
 
-        # Mock other installers
         with (
             patch("napari_mcp.cli.main.CursorInstaller"),
             patch("napari_mcp.cli.main.ClineVSCodeInstaller"),
@@ -323,40 +404,6 @@ def test_list_installations(
             assert result.exit_code == 0
             assert "napari-mcp Installation Status" in result.stdout
 
-    @patch("napari_mcp.cli.main.CodexCLIInstaller")
-    @patch("toml.load")
-    @patch("pathlib.Path.exists")
-    def test_list_codex_toml_config(
-        self, mock_exists, mock_toml_load, mock_codex, cli_runner
-    ):
-        """Test listing with Codex TOML configuration."""
-        mock_exists.return_value = True
-        mock_toml_load.return_value = {
-            "mcp_servers": {
-                "napari_mcp": {
-                    "command": "uv",
-                    "args": ["run", "--with", "napari-mcp", "napari-mcp"],
-                }
-            }
-        }
-
-        mock_instance = MagicMock()
-        mock_instance.get_config_path.return_value = Path("/mock/.codex/config.toml")
-        mock_codex.return_value = mock_instance
-
-        # Mock other installers
-        with (
-            patch("napari_mcp.cli.main.ClaudeDesktopInstaller"),
-            patch("napari_mcp.cli.main.ClaudeCodeInstaller"),
-            patch("napari_mcp.cli.main.CursorInstaller"),
-            patch("napari_mcp.cli.main.ClineVSCodeInstaller"),
-            patch("napari_mcp.cli.main.ClineCursorInstaller"),
-            patch("napari_mcp.cli.main.GeminiCLIInstaller"),
-            patch("builtins.open", create=True),
-        ):
-            result = cli_runner.invoke(app, ["list"])
-            assert result.exit_code == 0
-
 
 class TestErrorHandling:
     """Test error handling in CLI commands."""
@@ -366,9 +413,7 @@ def test_installer_exception(self, mock_installer_class, cli_runner):
         """Test handling of installer exceptions."""
         mock_installer_class.side_effect = Exception("Test exception")
 
-        # The all command catches exceptions
-        result = cli_runner.invoke(app, ["all"])
-        # Should still complete but with error status
+        result = cli_runner.invoke(app, ["install", "all"])
         assert result.exit_code == 1
 
     @patch("napari_mcp.cli.main.ClaudeDesktopInstaller")
@@ -378,9 +423,28 @@ def test_dry_run_mode(self, mock_installer_class, cli_runner):
         mock.install.return_value = (True, "Dry run successful")
         mock_installer_class.return_value = mock
 
-        result = cli_runner.invoke(app, ["claude-desktop", "--dry-run"])
+        result = cli_runner.invoke(app, ["install", "claude-desktop", "--dry-run"])
         assert result.exit_code == 0
 
-        # Verify dry_run was passed
         call_kwargs = mock_installer_class.call_args[1]
         assert call_kwargs["dry_run"] is True
+
+
+class TestInstallTarget:
+    """Test the InstallTarget enum and installer class lookup."""
+
+    def test_install_target_enum_values(self):
+        assert InstallTarget.CLAUDE_DESKTOP.value == "claude-desktop"
+        assert InstallTarget.CODEX.value == "codex"
+        assert InstallTarget.ALL.value == "all"
+
+    def test_installer_class_lookup(self):
+        cls = _get_installer_class(InstallTarget.CLAUDE_DESKTOP)
+        assert cls.__name__ == "ClaudeDesktopInstaller"
+
+    def test_all_targets_have_installer_classes(self):
+        for target in InstallTarget:
+            if target == InstallTarget.ALL:
+                continue
+            cls = _get_installer_class(target)
+            assert cls is not None, f"No installer class for {target.value}"
diff --git a/tests/test_cli_installers/test_platform_installers.py b/tests/test_cli_installers/test_platform_installers.py
index 694f255..f095d97 100644
--- a/tests/test_cli_installers/test_platform_installers.py
+++ b/tests/test_cli_installers/test_platform_installers.py
@@ -197,7 +197,7 @@ def test_no_extra_config(self):
     @patch("builtins.open", new_callable=mock_open)
     @patch("pathlib.Path.exists")
     @patch("pathlib.Path.mkdir")
-    @patch("toml.load")
+    @patch("napari_mcp.cli.install.codex_cli.tomllib.load")
     @patch("toml.dump")
     def test_install_toml_format(
         self, mock_dump, mock_load, mock_mkdir, mock_exists, mock_file
@@ -223,7 +223,7 @@ def test_install_toml_format(
 
     @patch("builtins.open", new_callable=mock_open)
     @patch("pathlib.Path.exists")
-    @patch("toml.load")
+    @patch("napari_mcp.cli.install.codex_cli.tomllib.load")
     @patch("toml.dump")
     def test_uninstall_toml_format(self, mock_dump, mock_load, mock_exists, mock_file):
         """Test Codex uninstaller handles TOML format."""
diff --git a/tests/test_cli_utils.py b/tests/test_cli_utils.py
index 10573e5..b37c045 100644
--- a/tests/test_cli_utils.py
+++ b/tests/test_cli_utils.py
@@ -7,6 +7,8 @@
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
+import pytest
+
 from napari_mcp.cli.install.utils import (
     build_server_config,
     check_existing_server,
@@ -14,8 +16,11 @@
     get_app_display_name,
     get_platform,
     get_python_executable,
+    normalize_napari_requirement,
+    prompt_napari_requirement,
     prompt_update_existing,
     read_json_config,
+    resolve_napari_requirement,
     show_installation_summary,
     validate_python_environment,
     write_json_config,
@@ -123,14 +128,15 @@ def test_read_json_config_preserves_order(self, tmp_path):
         assert list(result.keys()) == ["z", "a", "m"]
 
     def test_read_json_config_invalid_json(self, tmp_path):
-        """Test reading invalid JSON returns empty dict."""
+        """Test reading invalid JSON raises an error."""
         config_file = tmp_path / "config.json"
         config_file.write_text("invalid json{")
 
-        with patch("napari_mcp.cli.install.utils.console") as mock_console:
-            result = read_json_config(config_file)
-            assert result == {}
-            mock_console.print.assert_called()
+        with (
+            patch("napari_mcp.cli.install.utils.console"),
+            pytest.raises(json.JSONDecodeError),
+        ):
+            read_json_config(config_file)
 
     def test_write_json_config_create_parent(self, tmp_path):
         """Test writing config creates parent directories."""
@@ -292,6 +298,24 @@ def test_build_server_config_with_extras(self):
         assert config["timeout"] == 60000
         assert config["cwd"] == "/project"
 
+    def test_build_server_config_with_napari_backend(self):
+        """Test building config with an extra napari backend package."""
+        config = build_server_config(
+            persistent=False,
+            python_path=None,
+            napari_requirement="napari[pyqt6]",
+        )
+
+        assert config["command"] == "uv"
+        assert config["args"] == [
+            "run",
+            "--with",
+            "napari-mcp",
+            "--with",
+            "napari[pyqt6]",
+            "napari-mcp",
+        ]
+
     def test_check_existing_server_found(self):
         """Test checking for existing server configuration."""
         config = {
@@ -354,6 +378,56 @@ def test_prompt_update_existing_no(self, mock_ask):
         assert result is False
         mock_ask.assert_called_once()
 
+    @patch("rich.prompt.Prompt.ask")
+    def test_prompt_napari_requirement_default_all(self, mock_ask):
+        """Test napari backend prompt defaults to all."""
+        mock_ask.return_value = "all"
+        assert prompt_napari_requirement() == "napari[all]"
+
+    @patch("rich.prompt.Prompt.ask")
+    def test_prompt_napari_requirement_other(self, mock_ask):
+        """Test napari backend prompt supports custom values."""
+        mock_ask.side_effect = ["other", "pyside6"]
+        assert prompt_napari_requirement() == "napari[pyside6]"
+
+
+class TestNapariBackendResolution:
+    """Test napari backend normalization and resolution."""
+
+    def test_normalize_napari_requirement_presets(self):
+        """Test known backend presets are normalized correctly."""
+        assert normalize_napari_requirement("all") == "napari[all]"
+        assert normalize_napari_requirement("pyqt5") == "napari[pyqt5]"
+        assert normalize_napari_requirement("pyqt6") == "napari[pyqt6]"
+        assert normalize_napari_requirement("pyside") == "napari[pyside]"
+
+    def test_normalize_napari_requirement_none(self):
+        """Test none disables extra napari dependency installation."""
+        assert normalize_napari_requirement("none") is None
+        assert normalize_napari_requirement(None) is None
+
+    def test_normalize_napari_requirement_custom_values(self):
+        """Test custom backend values are wrapped into napari extras."""
+        assert normalize_napari_requirement("pyside6") == "napari[pyside6]"
+        assert normalize_napari_requirement("napari[pyside6]") == "napari[pyside6]"
+
+    def test_resolve_napari_requirement_defaults_to_all(self):
+        """Test non-interactive resolution defaults to all."""
+        assert resolve_napari_requirement(None) == "napari[all]"
+
+    def test_resolve_napari_requirement_other_requires_interaction(self):
+        """Test non-interactive custom selection raises a helpful error."""
+        with pytest.raises(ValueError, match="Pass a specific value to --backend"):
+            resolve_napari_requirement("other")
+
+    @patch("rich.prompt.Prompt.ask")
+    def test_resolve_napari_requirement_other_interactive(self, mock_ask):
+        """Test interactive custom selection prompts for a specific backend."""
+        mock_ask.return_value = "pyside6"
+        assert (
+            resolve_napari_requirement("other", prompt_user=True) == "napari[pyside6]"
+        )
+
 
 class TestInstallationSummary:
     """Test installation summary display."""
@@ -423,15 +497,18 @@ def test_write_json_config_readonly_directory(self, tmp_path):
             config_file.parent.chmod(0o755)
 
     def test_read_json_config_permission_denied(self, tmp_path):
-        """Test reading config with permission denied."""
+        """Test reading config with permission denied raises an error."""
         config_file = tmp_path / "config.json"
         config_file.write_text('{"test": "value"}')
         config_file.chmod(0o000)
 
         try:
             with patch("napari_mcp.cli.install.utils.console"):
-                result = read_json_config(config_file)
-                # Might succeed on some systems
-                assert isinstance(result, dict)
+                try:
+                    result = read_json_config(config_file)
+                    # Might succeed on some systems (e.g., root)
+                    assert isinstance(result, dict)
+                except PermissionError:
+                    pass  # Expected on most systems
         finally:
             config_file.chmod(0o644)
diff --git a/tests/test_coverage.py b/tests/test_coverage.py
deleted file mode 100644
index 3725c5c..0000000
--- a/tests/test_coverage.py
+++ /dev/null
@@ -1,365 +0,0 @@
-"""
-Comprehensive test coverage for napari-mcp-server functions.
-
-This test file aims to cover edge cases and error paths that weren't covered
-in the main test suite.
-"""
-
-from pathlib import Path
-
-import numpy as np
-import pytest
-
-# Ensure Qt runs headless for CI
-# os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
-from napari_mcp.server import (  # noqa: E402
-    _ensure_qt_app,
-    add_image,
-    add_points,
-    close_viewer,
-    execute_code,
-    init_viewer,
-    install_packages,
-    list_layers,
-    remove_layer,
-    reorder_layer,
-    screenshot,
-    session_information,
-    set_active_layer,
-    set_camera,
-    set_dims_current_step,
-    set_grid,
-    set_layer_properties,
-    set_ndisplay,
-)
-
-
-@pytest.mark.asyncio
-async def test_init_viewer_with_size(make_napari_viewer):
-    """Test viewer initialization with custom size."""
-    # Create and set viewer first
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Now init_viewer will use the existing viewer thanks to our patch
-    res = await init_viewer(title="Test", width=640, height=480)
-    assert res["status"] == "ok"
-    assert res["title"] == "Test"
-
-
-@pytest.mark.asyncio
-async def test_gui_lifecycle(make_napari_viewer):
-    """Test GUI lifecycle now handled by init_viewer/close_viewer."""
-    # Create viewer and set as current
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Initialize viewer (starts GUI pump implicitly)
-    res = await init_viewer(title="Test", width=400, height=300)
-    assert res["status"] == "ok"
-
-    # Session shows GUI pump running when a viewer exists
-    sess = await session_information()
-    assert sess["status"] == "ok"
-    assert sess["viewer"] is not None
-    assert sess["session"]["gui_pump_running"] is True
-
-    # Close viewer (stops GUI pump)
-    res = await close_viewer()
-    assert res["status"] == "closed"
-
-    # Session shows no viewer
-    sess = await session_information()
-    assert sess["viewer"] is None
-
-
-@pytest.mark.asyncio
-async def test_layer_error_cases(make_napari_viewer):
-    """Test error handling in layer operations."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Test removing non-existent layer
-    res = await remove_layer("nonexistent")
-    assert res["status"] == "not_found"
-
-    # Test renaming non-existent layer via set_layer_properties
-    res = await set_layer_properties("nonexistent", new_name="new_name")
-    assert res["status"] == "not_found"
-
-    # Test setting properties on non-existent layer
-    res = await set_layer_properties("nonexistent", visible=False)
-    assert res["status"] == "not_found"
-
-    # Test reordering non-existent layer
-    res = await reorder_layer("nonexistent", index=0)
-    assert res["status"] == "not_found"
-
-    # Test setting active layer to non-existent
-    res = await set_active_layer("nonexistent")
-    assert res["status"] == "not_found"
-
-
-@pytest.mark.asyncio
-async def test_reorder_layer_edge_cases(make_napari_viewer):
-    """Test edge cases in layer reordering."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Add some layers
-    await add_points([[1, 1]], name="layer1")
-    await add_points([[2, 2]], name="layer2")
-    await add_points([[3, 3]], name="layer3")
-
-    # Test invalid parameter combinations
-    res = await reorder_layer("layer1")  # No target specified
-    assert res["status"] == "error"
-    assert "exactly one" in res["message"]
-
-    res = await reorder_layer("layer1", index=0, before="layer2")  # Multiple targets
-    assert res["status"] == "error"
-    assert "exactly one" in res["message"]
-
-    # Test before/after with non-existent targets
-    res = await reorder_layer("layer1", before="nonexistent")
-    assert res["status"] == "not_found"
-
-    res = await reorder_layer("layer1", after="nonexistent")
-    assert res["status"] == "not_found"
-
-    # Test valid reordering
-    res = await reorder_layer("layer1", after="layer2")
-    assert res["status"] == "ok"
-
-
-@pytest.mark.asyncio
-async def test_set_layer_properties_comprehensive(make_napari_viewer):
-    """Test comprehensive layer property setting."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-    await add_points([[1, 1]], name="test_layer")
-
-    # Test setting all properties
-    res = await set_layer_properties(
-        "test_layer",
-        visible=False,
-        opacity=0.5,
-        colormap="viridis",
-        blending="additive",
-        contrast_limits=[0.1, 0.9],
-        gamma=1.5,
-    )
-    assert res["status"] == "ok"
-
-
-@pytest.mark.asyncio
-async def test_execute_code_error_cases(make_napari_viewer):
-    """Test error handling in code execution."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Test syntax error
-    res = await execute_code("invalid python syntax !!!")
-    assert res["status"] == "error"
-    assert res["stderr"]
-
-    # Test runtime error
-    res = await execute_code("raise ValueError('test error')")
-    assert res["status"] == "error"
-    assert "test error" in res["stderr"]
-
-    # Test stdout/stderr capture
-    res = await execute_code(
-        "import sys; print('stdout'); print('stderr', file=sys.stderr)"
-    )
-    assert res["status"] == "ok"
-    assert "stdout" in res["stdout"]
-    assert "stderr" in res["stderr"]
-
-    # Test expression evaluation
-    res = await execute_code("x = 42\nx")
-    assert res["status"] == "ok"
-    assert res.get("result_repr") == "42"
-
-
-@pytest.mark.asyncio
-async def test_install_packages_validation(make_napari_viewer):
-    """Test package installation parameter validation."""
-    # Test empty package list
-    res = await install_packages([])
-    assert res["status"] == "error"
-    assert "non-empty list" in res["message"]
-
-    # Test invalid package list type
-    res = await install_packages("not_a_list")  # type: ignore
-    assert res["status"] == "error"
-    assert "non-empty list" in res["message"]
-
-
-@pytest.mark.asyncio
-async def test_screenshot_with_different_dtypes(make_napari_viewer):
-    """Test screenshot with different image data types."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Create a temporary image file
-    import tempfile
-
-    import imageio
-
-    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
-        # Create test image data
-        test_image = (np.random.rand(20, 20, 3) * 255).astype(np.uint8)
-        imageio.imwrite(f.name, test_image)
-
-        # Add the image
-        await add_image(path=f.name, name="test_float")
-
-    # Take screenshot - should work with any data type napari supports
-    res = await screenshot()
-    assert res.mimeType.lower() in ("png", "image/png")
-    assert res.data is not None
-
-    # Clean up viewer
-    await close_viewer()
-
-
-@pytest.mark.asyncio
-async def test_close_viewer_no_viewer(make_napari_viewer):
-    """Test closing viewer when none exists."""
-    # Reset global viewer state
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = None
-
-    res = await close_viewer()
-    assert res["status"] == "no_viewer"
-
-
-@pytest.mark.asyncio
-async def test_camera_operations(make_napari_viewer):
-    """Test comprehensive camera operations."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Set to 2D mode for consistent testing
-    await set_ndisplay(2)
-
-    # Test individual camera operations
-    res = await set_camera(zoom=2.5)
-    assert res["status"] == "ok"
-    assert abs(res["zoom"] - 2.5) < 0.01
-
-    # Test camera with all parameters
-    res = await set_camera(center=[100, 200], zoom=1.5, angle=45.0)
-    assert res["status"] == "ok"
-    assert res["zoom"] == 1.5
-    # Camera center might be 2D or 3D depending on implementation
-    center = res["center"]
-    if len(center) == 3:
-        # If 3D, check last two values match our input
-        assert center[1:] == [100.0, 200.0]
-    else:
-        assert center == [100.0, 200.0]
-
-    # Test camera with partial parameters
-    res = await set_camera(zoom=3.0)
-    assert res["status"] == "ok"
-    assert res["zoom"] == 3.0
-
-
-@pytest.mark.asyncio
-async def test_dims_operations(make_napari_viewer):
-    """Test dimension-related operations."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Test ndisplay
-    res = await set_ndisplay(3)
-    assert res["status"] == "ok"
-    assert res["ndisplay"] == 3
-
-    # Test dims current step
-    res = await set_dims_current_step(0, 5)
-    assert res["status"] == "ok"
-    assert res["axis"] == 0
-    assert res["value"] == 5
-
-
-@pytest.mark.asyncio
-async def test_grid_operations(make_napari_viewer):
-    """Test grid enable/disable."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Enable grid
-    res = await set_grid(True)
-    assert res["status"] == "ok"
-    assert res["grid"] is True
-
-    # Disable grid
-    res = await set_grid(False)
-    assert res["status"] == "ok"
-    assert res["grid"] is False
-
-
-@pytest.mark.asyncio
-async def test_list_layers_with_properties(make_napari_viewer):
-    """Test layer listing with various properties."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Add layer and set properties
-    await add_points([[1, 1]], name="test_points")
-    await set_layer_properties("test_points", opacity=0.8, visible=False)
-
-    layers = await list_layers()
-    assert len(layers) >= 1
-
-    points_layer = next(
-        (layer for layer in layers if layer["name"] == "test_points"), None
-    )
-    assert points_layer is not None
-    assert points_layer["opacity"] == 0.8
-    assert points_layer["visible"] is False
-
-
-def test_qt_app_singleton(make_napari_viewer):
-    """Test Qt application singleton behavior."""
-    app1 = _ensure_qt_app()
-    app2 = _ensure_qt_app()
-    assert app1 is app2  # Should be the same instance
-
-
-@pytest.mark.asyncio
-async def test_image_loading_error(make_napari_viewer, tmp_path: Path):
-    """Test error handling when loading invalid image files."""
-    # Create an invalid file
-    bad_file = tmp_path / "bad_image.tif"
-    bad_file.write_text("not an image")
-
-    # This should raise an exception that gets propagated
-    with pytest.raises((ValueError, OSError, RuntimeError)):
-        await add_image(str(bad_file))
diff --git a/tests/test_edge_cases.py b/tests/test_edge_cases.py
deleted file mode 100644
index 4a91c95..0000000
--- a/tests/test_edge_cases.py
+++ /dev/null
@@ -1,209 +0,0 @@
-"""
-Additional edge case tests to maximize coverage.
-"""
-
-import asyncio
-import os
-from unittest.mock import MagicMock, patch
-
-import numpy as np
-import pytest
-
-from napari_mcp.server import (  # noqa: E402
-    _connect_window_destroyed_signal,
-    _ensure_qt_app,
-    _process_events,
-    _qt_event_pump,
-    close_viewer,
-    init_viewer,
-    install_packages,
-)
-
-
-def test_qt_app_creation(make_napari_viewer):
-    """Test Qt application creation and error handling."""
-    # Create a viewer to ensure Qt is initialized
-    viewer = make_napari_viewer()  # noqa: F841
-
-    # Test successful creation
-    app = _ensure_qt_app()
-    assert app is not None
-
-    # Test error handling in setQuitOnLastWindowClosed
-    with patch.dict(os.environ, {"TEST_QT_FAILURE": "1"}):
-        # Should not raise exception, just continue
-        app = _ensure_qt_app()
-        assert app is not None
-
-
-def test_process_events(make_napari_viewer):
-    """Test Qt event processing."""
-    # Create a viewer to ensure Qt is initialized
-    viewer = make_napari_viewer()  # noqa: F841
-
-    # Test with different cycle counts
-    _process_events(1)
-    _process_events(5)
-    _process_events(0)  # Should default to 1
-
-
-def test_connect_window_destroyed_signal(make_napari_viewer):
-    """Test window destroyed signal connection."""
-    # Import the module-level variable
-    from napari_mcp import server as napari_mcp_server
-
-    # Reset the global flag first to ensure we test properly
-    original_flag = napari_mcp_server._window_close_connected
-    napari_mcp_server._window_close_connected = False
-
-    try:
-        # Create a real napari viewer
-        viewer = make_napari_viewer()  # noqa: F841
-
-        # Test connecting the signal (first time)
-        _connect_window_destroyed_signal(viewer)
-        assert napari_mcp_server._window_close_connected is True
-
-        # Test that it doesn't connect again
-        _connect_window_destroyed_signal(viewer)
-        assert napari_mcp_server._window_close_connected is True
-
-    finally:
-        # Restore original state
-        napari_mcp_server._window_close_connected = original_flag
-
-
-@pytest.mark.asyncio
-async def test_qt_event_pump(make_napari_viewer):
-    """Test Qt event pump behavior."""
-    # Create a viewer to ensure Qt is initialized
-    viewer = make_napari_viewer()  # noqa: F841
-
-    # Test that event pump can be created and runs
-    task = asyncio.create_task(_qt_event_pump())
-
-    # Let it run briefly then cancel
-    await asyncio.sleep(0.01)
-    task.cancel()
-
-    # Should handle cancellation gracefully
-    try:
-        await task
-    except asyncio.CancelledError:
-        pass  # Expected
-
-
-@pytest.mark.asyncio
-async def test_gui_control_functions(make_napari_viewer):
-    """Test GUI lifecycle handled implicitly."""
-    # Create a viewer to ensure Qt is initialized
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # init_viewer starts the GUI pump
-    result = await init_viewer()
-    assert result["status"] == "ok"
-
-    # Close viewer stops the GUI pump
-    result = await close_viewer()
-    assert result["status"] == "closed"
-
-
-@pytest.mark.asyncio
-@patch("asyncio.create_subprocess_exec")
-async def test_install_packages(mock_create_subprocess, make_napari_viewer):
-    """Test package installation function."""
-    from unittest.mock import AsyncMock
-
-    # Mock the subprocess properly
-    mock_process = AsyncMock()
-    mock_process.returncode = 0
-    mock_process.communicate.return_value = (
-        b"Successfully installed test-package",
-        b"",
-    )
-    mock_create_subprocess.return_value = mock_process
-
-    result = await install_packages(packages=["test-package"])
-    assert result["status"] == "ok"
-    assert "test-package" in result["stdout"]
-
-    # Test failed installation
-    mock_process.returncode = 1
-    mock_process.communicate.return_value = (b"", b"Package not found")
-
-    result = await install_packages(packages=["bad-package"])
-    assert result["status"] == "error"
-    assert "Package not found" in result["stderr"]
-
-
-@pytest.mark.asyncio
-async def test_error_recovery(make_napari_viewer):
-    """Test error recovery in various scenarios."""
-    from napari_mcp import server as napari_mcp_server
-
-    # Create viewer
-    viewer = make_napari_viewer()
-    napari_mcp_server._viewer = viewer
-
-    # Test with real viewer - should work normally
-    _connect_window_destroyed_signal(viewer)
-
-    # Test with mock viewer that has no window attribute - should not crash
-    mock_viewer = MagicMock(spec=[])  # No window attribute
-    _connect_window_destroyed_signal(mock_viewer)  # Should not crash
-
-
-def test_layer_operations(make_napari_viewer):
-    """Test various layer operations."""
-    viewer = make_napari_viewer()
-
-    # Add layers with different types
-    img_data = np.random.random((100, 100))
-    viewer.add_image(img_data, name="test_image")
-
-    points_data = np.array([[10, 10], [20, 20]])
-    viewer.add_points(points_data, name="test_points")
-
-    labels_data = np.zeros((100, 100), dtype=np.uint8)
-    viewer.add_labels(labels_data, name="test_labels")
-
-    # Test layer access
-    assert "test_image" in viewer.layers
-    assert len(viewer.layers) == 3
-
-    # Test layer removal
-    viewer.layers.remove("test_points")
-    assert len(viewer.layers) == 2
-    assert "test_points" not in viewer.layers
-
-    # Test layer reordering
-    initial_index = viewer.layers.index("test_image")
-    viewer.layers.move(initial_index, 0)
-    assert viewer.layers.index("test_image") == 0
-
-
-def test_viewer_properties(make_napari_viewer):
-    """Test viewer property access and modification."""
-    viewer = make_napari_viewer()
-
-    # Test title
-    viewer.title = "Test Viewer"
-    assert viewer.title == "Test Viewer"
-
-    # Test camera properties
-    viewer.camera.center = [50.0, 50.0]
-    viewer.camera.zoom = 2.0
-
-    # Test dims properties
-    viewer.dims.ndisplay = 2
-
-    # Test grid
-    viewer.grid.enabled = True
-    assert viewer.grid.enabled is True
-
-    # Test screenshot
-    screenshot = viewer.screenshot(canvas_only=True)
-    assert screenshot.shape[-1] == 4  # RGBA
diff --git a/tests/test_external_viewer.py b/tests/test_external_viewer.py
index f952167..3b53e93 100644
--- a/tests/test_external_viewer.py
+++ b/tests/test_external_viewer.py
@@ -1,22 +1,12 @@
 """Tests for external viewer detection and proxy functionality."""
 
 import json
-import os
-import sys
 from unittest.mock import AsyncMock, Mock, patch
 
 import pytest
 
-# Add src to path
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
-
-from napari_mcp.server import (
-    _detect_external_viewer,
-    _detect_external_viewer_sync,
-    _parse_bool,
-    _proxy_to_external,
-    detect_viewers,
-)
+from napari_mcp._helpers import parse_bool as _parse_bool
+from napari_mcp.state import ServerState, StartupMode
 
 
 class TestBooleanParsing:
@@ -62,9 +52,11 @@ class TestExternalViewerDetection:
     """Test detection of external napari viewers."""
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
+    @patch("fastmcp.Client")
     async def test_detect_external_viewer_success(self, mock_client_class):
         """Test successful detection of external viewer."""
+        state = ServerState(mode=StartupMode.AUTO_DETECT)
+
         # Setup mock client
         mock_client = AsyncMock()
         mock_client_class.return_value = mock_client
@@ -89,17 +81,19 @@ async def test_detect_external_viewer_success(self, mock_client_class):
         mock_client.call_tool.return_value = mock_result
 
         # Test detection
-        client, info = await _detect_external_viewer()
+        found, info = await state.detect_external_viewer()
 
-        assert client is not None
+        assert found is True
         assert info["session_type"] == "napari_bridge_session"
         assert info["viewer"]["title"] == "External Viewer"
         assert info["bridge_port"] == 9999
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
+    @patch("fastmcp.Client")
     async def test_detect_external_viewer_not_bridge(self, mock_client_class):
         """Test detection when server exists but is not a bridge."""
+        state = ServerState(mode=StartupMode.AUTO_DETECT)
+
         mock_client = AsyncMock()
         mock_client_class.return_value = mock_client
 
@@ -120,46 +114,51 @@ async def test_detect_external_viewer_not_bridge(self, mock_client_class):
         ]
         mock_client.call_tool.return_value = mock_result
 
-        client, info = await _detect_external_viewer()
+        found, info = await state.detect_external_viewer()
 
-        assert client is None
+        assert found is False
         assert info is None
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
+    @patch("fastmcp.Client")
     async def test_detect_external_viewer_connection_error(self, mock_client_class):
         """Test detection when connection fails."""
+        state = ServerState(mode=StartupMode.AUTO_DETECT)
+
         mock_client_class.side_effect = Exception("Connection refused")
 
-        client, info = await _detect_external_viewer()
+        found, info = await state.detect_external_viewer()
 
-        assert client is None
+        assert found is False
         assert info is None
 
-    def test_detect_external_viewer_sync(self):
-        """Test synchronous wrapper for external viewer detection."""
-        # Patch the function to return a synchronous result directly
-        with patch("napari_mcp.server._detect_external_viewer") as mock_detect:
-            # Mock successful detection - return tuple directly, not a coroutine
-            mock_detect.return_value = (Mock(), {"test": "info"})
+    @pytest.mark.asyncio
+    async def test_detect_external_viewer_standalone_mode(self):
+        """Test that STANDALONE mode skips detection entirely."""
+        state = ServerState(mode=StartupMode.STANDALONE)
 
-            result = _detect_external_viewer_sync()
-            assert result is True
+        found, info = await state.detect_external_viewer()
+        assert found is False
+        assert info is None
 
-            # Mock failed detection - return tuple directly, not a coroutine
-            mock_detect.return_value = (None, None)
+    def test_detect_external_viewer_sync(self):
+        """Test synchronous wrapper for external viewer detection."""
+        from napari_mcp.server import detect_external_viewer_sync
 
-            result = _detect_external_viewer_sync()
-            assert result is False
+        # In STANDALONE mode (set by conftest), sync detection returns False
+        result = detect_external_viewer_sync()
+        assert result is False
 
 
 class TestProxyFunctionality:
     """Test proxying tool calls to external viewer."""
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
+    @patch("fastmcp.Client")
     async def test_proxy_to_external_success(self, mock_client_class):
         """Test successful proxy to external viewer."""
+        state = ServerState(mode=StartupMode.AUTO_DETECT)
+
         # Setup mock client instance
         mock_client_instance = AsyncMock()
         mock_result = Mock()
@@ -173,7 +172,7 @@ async def test_proxy_to_external_success(self, mock_client_class):
         mock_client_instance.__aenter__ = AsyncMock(return_value=mock_client_instance)
         mock_client_instance.__aexit__ = AsyncMock(return_value=None)
 
-        result = await _proxy_to_external("test_tool", {"param": "value"})
+        result = await state.proxy_to_external("test_tool", {"param": "value"})
 
         assert result is not None
         assert result["status"] == "ok"
@@ -184,16 +183,20 @@ async def test_proxy_to_external_success(self, mock_client_class):
         mock_client_class.assert_called_once_with("http://localhost:9999/mcp")
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client", side_effect=Exception("Connection refused"))
+    @patch("fastmcp.Client", side_effect=Exception("Connection refused"))
     async def test_proxy_to_external_unavailable(self, _):
         """Test proxy when external viewer is unavailable."""
-        result = await _proxy_to_external("test_tool", {"param": "value"})
+        state = ServerState(mode=StartupMode.AUTO_DETECT)
+
+        result = await state.proxy_to_external("test_tool", {"param": "value"})
         assert result is None
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
+    @patch("fastmcp.Client")
     async def test_proxy_to_external_initialize_client(self, mock_client_class):
         """Test proxy initializes client if not present."""
+        state = ServerState(mode=StartupMode.AUTO_DETECT)
+
         # Setup mock client
         mock_client = AsyncMock()
         mock_client_class.return_value = mock_client
@@ -206,16 +209,18 @@ async def test_proxy_to_external_initialize_client(self, mock_client_class):
         mock_client.__aenter__ = AsyncMock(return_value=mock_client)
         mock_client.__aexit__ = AsyncMock(return_value=None)
 
-        result = await _proxy_to_external("test_tool")
+        result = await state.proxy_to_external("test_tool")
 
         assert result is not None
         assert result["status"] == "ok"
         mock_client_class.assert_called_once_with("http://localhost:9999/mcp")
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
+    @patch("fastmcp.Client")
     async def test_proxy_to_external_invalid_json(self, mock_client_class):
         """Test proxy with invalid JSON response."""
+        state = ServerState(mode=StartupMode.AUTO_DETECT)
+
         mock_client_instance = AsyncMock()
         mock_result = Mock()
         mock_result.content = [Mock(text="invalid json", type="text")]
@@ -225,24 +230,30 @@ async def test_proxy_to_external_invalid_json(self, mock_client_class):
         mock_client_instance.__aenter__ = AsyncMock(return_value=mock_client_instance)
         mock_client_instance.__aexit__ = AsyncMock(return_value=None)
 
-        result = await _proxy_to_external("test_tool")
+        result = await state.proxy_to_external("test_tool")
 
         assert result is not None
         assert result["status"] == "error"
         assert "Invalid JSON response" in result["message"]
 
+    @pytest.mark.asyncio
+    async def test_proxy_standalone_returns_none(self):
+        """Test proxy returns None immediately in STANDALONE mode."""
+        state = ServerState(mode=StartupMode.STANDALONE)
+        result = await state.proxy_to_external("test_tool", {"param": "value"})
+        assert result is None
+
 
 class TestViewerDetectionAndSelection:
     """Test detect_viewers behavior."""
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server._detect_external_viewer")
-    @patch("napari_mcp.server._viewer", None)
-    async def test_detect_viewers_no_viewers(self, mock_detect):
-        """Test detecting viewers when none exist."""
-        mock_detect.return_value = (None, None)
+    async def test_detect_viewers_no_viewers(self):
+        """Test detecting viewers when none exist (STANDALONE mode)."""
+        from napari_mcp import server as napari_mcp_server
 
-        result = await detect_viewers()
+        # In STANDALONE mode, external is always unavailable
+        result = await napari_mcp_server.init_viewer(detect_only=True)
 
         assert result["status"] == "ok"
         assert result["viewers"]["external"]["available"] is False
@@ -250,14 +261,37 @@ async def test_detect_viewers_no_viewers(self, mock_detect):
         assert result["viewers"]["local"]["type"] == "not_initialized"
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server._detect_external_viewer")
-    async def test_detect_viewers_with_external(self, mock_detect):
+    @patch("fastmcp.Client")
+    async def test_detect_viewers_with_external(self, mock_client_class):
         """Test detecting viewers with external available."""
-        mock_client = Mock()
-        mock_info = {"bridge_port": 9999, "viewer": {"title": "External"}}
-        mock_detect.return_value = (mock_client, mock_info)
+        from napari_mcp import server as napari_mcp_server
+        from napari_mcp.server import create_server
+
+        # Create state in AUTO_DETECT mode
+        state = ServerState(mode=StartupMode.AUTO_DETECT)
+        napari_mcp_server._state = state
+        create_server(state)
+
+        mock_client = AsyncMock()
+        mock_client_class.return_value = mock_client
+        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_client.__aexit__ = AsyncMock(return_value=None)
+
+        mock_result = Mock()
+        mock_result.content = [
+            Mock(
+                text=json.dumps(
+                    {
+                        "session_type": "napari_bridge_session",
+                        "bridge_port": 9999,
+                        "viewer": {"title": "External"},
+                    }
+                )
+            )
+        ]
+        mock_client.call_tool.return_value = mock_result
 
-        result = await detect_viewers()
+        result = await napari_mcp_server.init_viewer(detect_only=True)
 
         assert result["status"] == "ok"
         assert result["viewers"]["external"]["available"] is True
diff --git a/tests/test_helpers.py b/tests/test_helpers.py
new file mode 100644
index 0000000..84a1bf6
--- /dev/null
+++ b/tests/test_helpers.py
@@ -0,0 +1,610 @@
+"""Tests for napari_mcp._helpers shared module."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, PropertyMock
+
+import numpy as np
+import pytest
+
+from napari_mcp._helpers import (
+    build_layer_detail,
+    build_truncated_response,
+    create_layer_on_viewer,
+    parse_bool,
+    resolve_layer_type,
+    run_code,
+)
+
+# ---------------------------------------------------------------------------
+# resolve_layer_type
+# ---------------------------------------------------------------------------
+
+
+class TestResolveLayerType:
+    """Test layer type resolution and alias handling."""
+
+    @pytest.mark.parametrize(
+        "input_val,expected",
+        [
+            ("image", "image"),
+            ("Image", "image"),
+            ("  IMAGE  ", "image"),
+            ("images", "image"),
+            ("labels", "labels"),
+            ("label", "labels"),
+            ("points", "points"),
+            ("point", "points"),
+            ("shapes", "shapes"),
+            ("shape", "shapes"),
+            ("vectors", "vectors"),
+            ("vector", "vectors"),
+            ("tracks", "tracks"),
+            ("track", "tracks"),
+            ("surface", "surface"),
+            ("surfaces", "surface"),
+        ],
+    )
+    def test_valid_types(self, input_val, expected):
+        assert resolve_layer_type(input_val) == expected
+
+    @pytest.mark.parametrize("input_val", ["unknown", "mesh", "", "123", "im age"])
+    def test_invalid_types(self, input_val):
+        assert resolve_layer_type(input_val) is None
+
+
+# ---------------------------------------------------------------------------
+# create_layer_on_viewer
+# ---------------------------------------------------------------------------
+
+
+class TestCreateLayerOnViewer:
+    """Test the shared layer creation helper."""
+
+    def _make_viewer(self):
+        """Create a mock viewer with all add_* methods."""
+        viewer = MagicMock()
+        # Each add method returns a mock layer with a .name
+        for method in [
+            "add_image",
+            "add_labels",
+            "add_points",
+            "add_shapes",
+            "add_vectors",
+            "add_tracks",
+            "add_surface",
+        ]:
+            layer = MagicMock()
+            layer.name = f"test_{method}"
+            layer.nshapes = 1
+            getattr(viewer, method).return_value = layer
+        return viewer
+
+    def test_image_basic(self):
+        viewer = self._make_viewer()
+        data = np.zeros((10, 10))
+        result = create_layer_on_viewer(viewer, data, "image", name="img")
+        assert result["status"] == "ok"
+        assert result["shape"] == [10, 10]
+        viewer.add_image.assert_called_once()
+
+    def test_image_with_colormap(self):
+        viewer = self._make_viewer()
+        data = np.zeros((10, 10))
+        result = create_layer_on_viewer(
+            viewer, data, "image", name="img", colormap="viridis", blending="additive"
+        )
+        assert result["status"] == "ok"
+        call_kwargs = viewer.add_image.call_args[1]
+        assert call_kwargs["colormap"] == "viridis"
+        assert call_kwargs["blending"] == "additive"
+
+    def test_image_with_channel_axis(self):
+        viewer = self._make_viewer()
+        data = np.zeros((3, 10, 10))
+        create_layer_on_viewer(viewer, data, "image", channel_axis="0")
+        call_kwargs = viewer.add_image.call_args[1]
+        assert call_kwargs["channel_axis"] == 0
+
+    def test_labels(self):
+        viewer = self._make_viewer()
+        data = np.zeros((10, 10), dtype=int)
+        result = create_layer_on_viewer(viewer, data, "labels", name="lbl")
+        assert result["status"] == "ok"
+        viewer.add_labels.assert_called_once()
+
+    def test_points(self):
+        viewer = self._make_viewer()
+        data = [[0, 0], [1, 1], [2, 2]]
+        result = create_layer_on_viewer(viewer, data, "points", name="pts")
+        assert result["status"] == "ok"
+        assert result["n_points"] == 3
+        viewer.add_points.assert_called_once()
+
+    def test_points_custom_size(self):
+        viewer = self._make_viewer()
+        data = [[0, 0]]
+        create_layer_on_viewer(viewer, data, "points", size=20.0)
+        call_kwargs = viewer.add_points.call_args[1]
+        assert call_kwargs["size"] == 20.0
+
+    def test_shapes(self):
+        viewer = self._make_viewer()
+        data = [np.array([[0, 0], [0, 1], [1, 1], [1, 0]])]
+        result = create_layer_on_viewer(
+            viewer,
+            data,
+            "shapes",
+            name="shp",
+            shape_type="polygon",
+            edge_color="red",
+            face_color="blue",
+            edge_width=2.0,
+        )
+        assert result["status"] == "ok"
+        call_kwargs = viewer.add_shapes.call_args[1]
+        assert call_kwargs["shape_type"] == "polygon"
+        assert call_kwargs["edge_color"] == "red"
+        assert call_kwargs["face_color"] == "blue"
+        assert call_kwargs["edge_width"] == 2.0
+
+    def test_vectors(self):
+        viewer = self._make_viewer()
+        data = np.array([[[0, 0], [1, 1]]])
+        result = create_layer_on_viewer(viewer, data, "vectors", name="vec")
+        assert result["status"] == "ok"
+        viewer.add_vectors.assert_called_once()
+
+    def test_tracks(self):
+        viewer = self._make_viewer()
+        data = np.array([[0, 0, 0], [0, 1, 1], [1, 0, 0], [1, 1, 1]])
+        result = create_layer_on_viewer(viewer, data, "tracks", name="trk")
+        assert result["status"] == "ok"
+        assert result["n_tracks"] == 2  # track IDs 0 and 1
+
+    def test_surface(self):
+        viewer = self._make_viewer()
+        verts = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]])
+        faces = np.array([[0, 1, 2]])
+        result = create_layer_on_viewer(viewer, (verts, faces), "surface", name="srf")
+        assert result["status"] == "ok"
+        assert result["n_vertices"] == 3
+        assert result["n_faces"] == 1
+
+    def test_unknown_type(self):
+        viewer = self._make_viewer()
+        result = create_layer_on_viewer(viewer, None, "unknown")
+        assert result["status"] == "error"
+        assert "Unknown" in result["message"]
+
+    # --- Bug fixes: validation ---
+
+    def test_empty_image_rejected(self):
+        """Bug 1: empty array should return error, not crash."""
+        viewer = self._make_viewer()
+        result = create_layer_on_viewer(viewer, np.zeros((0, 0)), "image")
+        assert result["status"] == "error"
+        assert "empty" in result["message"].lower()
+
+    def test_empty_labels_rejected(self):
+        viewer = self._make_viewer()
+        result = create_layer_on_viewer(viewer, np.zeros((0,), dtype=int), "labels")
+        assert result["status"] == "error"
+        assert "empty" in result["message"].lower()
+
+    def test_empty_points_rejected(self):
+        viewer = self._make_viewer()
+        result = create_layer_on_viewer(viewer, np.zeros((0, 2)), "points")
+        assert result["status"] == "error"
+        assert "empty" in result["message"].lower()
+
+    def test_complex_dtype_rejected(self):
+        """Bug 2: complex dtype should return error, not crash."""
+        viewer = self._make_viewer()
+        data = np.array([[1 + 2j, 3 + 4j]], dtype=np.complex128)
+        result = create_layer_on_viewer(viewer, data, "image")
+        assert result["status"] == "error"
+        assert "complex" in result["message"].lower()
+
+    def test_channel_axis_returns_list(self):
+        """Bug 13: channel_axis makes napari return a list of layers."""
+        viewer = self._make_viewer()
+        # Mock add_image to return a list (like napari does with channel_axis)
+        layer1 = MagicMock()
+        layer1.name = "ch0"
+        layer2 = MagicMock()
+        layer2.name = "ch1"
+        viewer.add_image.return_value = [layer1, layer2]
+
+        data = np.zeros((2, 10, 10))
+        result = create_layer_on_viewer(viewer, data, "image", channel_axis=0)
+        assert result["status"] == "ok"
+        assert result["name"] == ["ch0", "ch1"]
+        assert result["n_channels"] == 2
+
+
+# ---------------------------------------------------------------------------
+# build_layer_detail
+# ---------------------------------------------------------------------------
+
+
+class TestBuildLayerDetail:
+    """Test layer detail dict building."""
+
+    def test_basic_layer(self):
+        layer = MagicMock()
+        layer.name = "test"
+        layer.__class__.__name__ = "Image"
+        layer.visible = True
+        layer.opacity = 0.8
+        layer.data.shape = (100, 100)
+        layer.data.dtype = np.dtype("uint8")
+        layer.blending = "translucent"
+        type(layer).colormap = PropertyMock(return_value=MagicMock(name="viridis"))
+        layer.colormap.name = "viridis"
+        layer.gamma = 1.0
+
+        detail = build_layer_detail(layer)
+        assert detail["name"] == "test"
+        assert detail["type"] == "Image"
+        assert detail["visible"] is True
+        assert detail["opacity"] == 0.8
+        assert detail["data_shape"] == [100, 100]
+        assert detail["data_dtype"] == "uint8"
+
+    def test_visible_uses_bool_not_parse_bool(self):
+        """visible field should use bool(), not parse_bool(), on napari attributes."""
+        layer = MagicMock(spec=["name", "visible", "opacity"])
+        layer.name = "test"
+        layer.__class__.__name__ = "Image"
+        layer.opacity = 1.0
+
+        # numpy bool_ (common from napari)
+        layer.visible = np.bool_(True)
+        detail = build_layer_detail(layer)
+        assert detail["visible"] is True
+        assert type(detail["visible"]) is bool  # Should be Python bool, not numpy
+
+        layer.visible = np.bool_(False)
+        detail = build_layer_detail(layer)
+        assert detail["visible"] is False
+
+    def test_layer_without_data(self):
+        layer = MagicMock(spec=["name", "visible", "opacity"])
+        layer.name = "empty"
+        layer.__class__.__name__ = "Shapes"
+        layer.visible = False
+        layer.opacity = 1.0
+
+        detail = build_layer_detail(layer)
+        assert detail["name"] == "empty"
+        assert "data_shape" not in detail
+        assert "colormap" not in detail
+
+
+# ---------------------------------------------------------------------------
+# run_code
+# ---------------------------------------------------------------------------
+
+
+class TestRunCode:
+    """Test the shared code execution helper."""
+
+    def test_simple_expression(self):
+        ns = {}
+        stdout, stderr, result_repr, error = run_code("1 + 1", ns)
+        assert result_repr == "2"
+        assert error is None
+        assert stdout == ""
+        assert stderr == ""
+
+    def test_print_output(self):
+        ns = {}
+        stdout, stderr, result_repr, error = run_code("print('hello')", ns)
+        assert stdout == "hello\n"
+        # print() is an expression returning None, so result_repr is 'None'
+        assert result_repr == "None"
+        assert error is None
+
+    def test_assignment_no_result(self):
+        """Pure assignment (not an expression) should have no result_repr."""
+        ns = {}
+        stdout, stderr, result_repr, error = run_code("x = 42", ns)
+        assert result_repr is None
+        assert error is None
+
+    def test_multi_statement_with_expression(self):
+        ns = {}
+        stdout, stderr, result_repr, error = run_code("x = 5\nx * 2", ns)
+        assert result_repr == "10"
+        assert ns["x"] == 5
+        assert error is None
+
+    def test_error_captured(self):
+        ns = {}
+        stdout, stderr, result_repr, error = run_code("1/0", ns)
+        assert error is not None
+        assert isinstance(error, ZeroDivisionError)
+        assert "ZeroDivisionError" in stderr
+
+    def test_namespace_persistence(self):
+        ns = {}
+        run_code("x = 42", ns)
+        _, _, result_repr, _ = run_code("x", ns)
+        assert result_repr == "42"
+
+    def test_source_label(self):
+        ns = {}
+        _, stderr, _, error = run_code(
+            "raise ValueError('test')", ns, source_label="<test>"
+        )
+        assert error is not None
+        assert "<test>" in stderr
+
+    def test_eval_label_derived_from_exec_label(self):
+        """The eval label should be derived from the exec label by replacing -exec with -eval."""
+        ns = {}
+        # This should use <bridge-eval> for the last expression
+        run_code("42", ns, source_label="<bridge-exec>")
+        # Just verify it doesn't crash - label is internal
+
+
+# ---------------------------------------------------------------------------
+# build_truncated_response
+# ---------------------------------------------------------------------------
+
+
+class TestBuildTruncatedResponse:
+    """Test truncated response building."""
+
+    def test_unlimited(self):
+        resp = build_truncated_response(
+            status="ok",
+            output_id="id1",
+            stdout_full="long output",
+            stderr_full="",
+            result_repr=None,
+            line_limit=-1,
+        )
+        assert resp["stdout"] == "long output"
+        assert "warning" in resp
+        assert "truncated" not in resp
+
+    def test_within_limit(self):
+        resp = build_truncated_response(
+            status="ok",
+            output_id="id1",
+            stdout_full="line1\nline2\n",
+            stderr_full="",
+            result_repr="42",
+            line_limit=10,
+        )
+        assert resp["stdout"] == "line1\nline2\n"
+        assert resp["result_repr"] == "42"
+        assert "truncated" not in resp
+
+    def test_truncated(self):
+        stdout = "\n".join(f"line{i}" for i in range(100)) + "\n"
+        resp = build_truncated_response(
+            status="ok",
+            output_id="id1",
+            stdout_full=stdout,
+            stderr_full="",
+            result_repr=None,
+            line_limit=5,
+        )
+        assert resp["truncated"] is True
+        assert "read_output" in resp["message"]
+
+    def test_error_summary_injected(self):
+        resp = build_truncated_response(
+            status="error",
+            output_id="id1",
+            stdout_full="",
+            stderr_full="",
+            result_repr=None,
+            line_limit=30,
+            error=ValueError("test error"),
+        )
+        assert "ValueError: test error" in resp["stderr"]
+
+    def test_string_line_limit(self):
+        """line_limit as string should work."""
+        resp = build_truncated_response(
+            status="ok",
+            output_id="id1",
+            stdout_full="hello\n",
+            stderr_full="",
+            result_repr=None,
+            line_limit="30",
+        )
+        assert resp["stdout"] == "hello\n"
+
+    def test_string_minus_one(self):
+        """line_limit='-1' as string should trigger unlimited mode."""
+        resp = build_truncated_response(
+            status="ok",
+            output_id="id1",
+            stdout_full="hello\n",
+            stderr_full="",
+            result_repr=None,
+            line_limit="-1",
+        )
+        assert "warning" in resp
+
+    def test_invalid_line_limit_falls_back(self):
+        """Invalid line_limit string should fall back to 30, not crash."""
+        resp = build_truncated_response(
+            status="ok",
+            output_id="id1",
+            stdout_full="hello\n",
+            stderr_full="",
+            result_repr=None,
+            line_limit="invalid",
+        )
+        assert resp["status"] == "ok"
+        assert resp["stdout"] == "hello\n"
+        assert "truncated" not in resp  # 1 line < 30 limit
+
+    def test_none_line_limit_falls_back(self):
+        """None line_limit should fall back to 30, not crash."""
+        resp = build_truncated_response(
+            status="ok",
+            output_id="id1",
+            stdout_full="hello\n",
+            stderr_full="",
+            result_repr=None,
+            line_limit=None,
+        )
+        assert resp["status"] == "ok"
+
+
+# ---------------------------------------------------------------------------
+# parse_bool (already tested via test_property_based.py, but add edge cases)
+# ---------------------------------------------------------------------------
+
+
+class TestParseBool:
+    def test_none_default(self):
+        assert parse_bool(None) is False
+        assert parse_bool(None, default=True) is True
+
+    def test_bool_passthrough(self):
+        assert parse_bool(True) is True
+        assert parse_bool(False) is False
+
+    def test_non_bool_non_string(self):
+        assert parse_bool(1) is True
+        assert parse_bool(0) is False
+
+
+# ---------------------------------------------------------------------------
+# Package name regex (from server.py)
+# ---------------------------------------------------------------------------
+
+
+class TestPackageNameRegex:
+    """Test the _PKG_NAME_RE regex used by install_packages."""
+
+    @pytest.fixture(autouse=True)
+    def _load_regex(self):
+        from napari_mcp.server import _PKG_NAME_RE
+
+        self.regex = _PKG_NAME_RE
+
+    @pytest.mark.parametrize(
+        "pkg",
+        [
+            "numpy",
+            "numpy>=1.20",
+            "numpy>=1.20,<2.0",
+            "scikit-image",
+            "torch[cuda]",
+            "torch[cuda,cpu]>=2.0",
+            "Pillow==10.0",
+            "package~=1.0",
+            "napari-mcp",
+            "a",
+            "a2",
+            "package!=1.0",
+        ],
+    )
+    def test_valid_packages(self, pkg):
+        assert self.regex.match(pkg.strip()), f"{pkg!r} should be valid"
+
+    @pytest.mark.parametrize(
+        "pkg",
+        [
+            "https://evil.com/pkg",
+            "package @ https://evil.com",
+            "--index-url http://evil",
+            "pkg;rm -rf /",
+            "",
+            " ",
+            # Security: pip flag injection
+            "--target /tmp/evil",
+            "-e git+https://evil.com/repo",
+            # Security: URL-based specifiers
+            "package @ https://evil.com/payload.tar.gz",
+            # Security: newline injection
+            "package\nmalicious",
+        ],
+    )
+    def test_invalid_packages(self, pkg):
+        assert not self.regex.match(pkg.strip()), f"{pkg!r} should be rejected"
+
+
+# ---------------------------------------------------------------------------
+# list_layers consistency with build_layer_detail
+# ---------------------------------------------------------------------------
+
+
+class TestListLayersBuildLayerDetailConsistency:
+    """Verify list_layers returns the same fields as build_layer_detail."""
+
+    @pytest.mark.asyncio
+    async def test_list_layers_returns_build_layer_detail_fields(self):
+        """list_layers should include all fields from build_layer_detail."""
+
+        # The conftest fixture creates fresh state; set up a mock viewer
+        mock_layer = MagicMock()
+        mock_layer.name = "test_layer"
+        mock_layer.__class__.__name__ = "Image"
+        mock_layer.visible = True
+        mock_layer.opacity = 0.8
+        mock_layer.data.shape = (100, 100)
+        mock_layer.data.dtype = np.dtype("float32")
+        mock_layer.blending = "translucent"
+        mock_layer.colormap.name = "viridis"
+        mock_layer.gamma = 1.5
+
+        # Compare: what build_layer_detail returns vs what list_layers would build
+        detail = build_layer_detail(mock_layer)
+
+        # build_layer_detail should include all these keys
+        assert "name" in detail
+        assert "type" in detail
+        assert "visible" in detail
+        assert "opacity" in detail
+        assert "data_shape" in detail
+        assert "data_dtype" in detail
+        assert "colormap" in detail
+        assert "blending" in detail
+        assert "gamma" in detail
+
+
+class TestBuildTruncatedResponseForInstallPackages:
+    """Test that build_truncated_response works correctly for install_packages use case."""
+
+    def test_extra_fields_can_be_added(self):
+        """install_packages adds returncode and command after building response."""
+        resp = build_truncated_response(
+            status="ok",
+            output_id="pip_123",
+            stdout_full="Successfully installed numpy\n",
+            stderr_full="",
+            result_repr=None,
+            line_limit=30,
+        )
+        # Simulate what install_packages does
+        resp["returncode"] = 0
+        resp["command"] = "pip install numpy"
+
+        assert resp["status"] == "ok"
+        assert resp["returncode"] == 0
+        assert resp["command"] == "pip install numpy"
+        assert resp["stdout"] == "Successfully installed numpy\n"
+        assert "result_repr" not in resp  # None should not be included
+
+    def test_string_line_limit_minus_one(self):
+        """Ensure string '-1' triggers unlimited mode (was a bug in old install_packages)."""
+        resp = build_truncated_response(
+            status="ok",
+            output_id="pip_456",
+            stdout_full="output\n",
+            stderr_full="",
+            result_repr=None,
+            line_limit="-1",
+        )
+        assert "warning" in resp
+        assert "truncated" not in resp
diff --git a/tests/test_integration.py b/tests/test_integration.py
index 3931098..ef2c48c 100644
--- a/tests/test_integration.py
+++ b/tests/test_integration.py
@@ -1,8 +1,7 @@
-"""Integration tests for napari-mcp with external viewer."""
+"""Integration tests for napari-mcp: multi-step workflows and concurrent calls."""
 
 import asyncio
-import json
-from unittest.mock import AsyncMock, Mock, patch
+from unittest.mock import Mock, patch
 
 import pytest
 
@@ -13,110 +12,16 @@ class TestEndToEndIntegration:
     """Test end-to-end integration between main server and bridge."""
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
-    async def test_execute_code_via_proxy(self, mock_client_class):
-        """Test executing code through proxy to external viewer."""
-        # Setup mock client
-        mock_client = AsyncMock()
-        mock_client_class.return_value = mock_client
+    async def test_execute_code_via_proxy(self):
+        """Test execute_code falls through to local when proxy is unavailable.
 
-        # Mock successful code execution
-        mock_result = Mock()
-        mock_result.content = [
-            Mock(
-                text=json.dumps(
-                    {"status": "ok", "result_repr": "42", "stdout": "", "stderr": ""}
-                )
-            )
-        ]
-        mock_client.call_tool.return_value = mock_result
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=None)
-
-        # Mock the Client class instead of global variable
-        with patch("napari_mcp.server.Client", return_value=mock_client):
-            result = await napari_mcp_server.execute_code("21 * 2")
+        In STANDALONE mode (set by conftest), proxy always returns None.
+        """
+        result = await napari_mcp_server.execute_code("21 * 2")
 
         assert result["status"] == "ok"
         assert result["result_repr"] == "42"
 
-    @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
-    async def test_list_layers_via_proxy(self, mock_client_class):
-        """Test listing layers through proxy."""
-        pytest.skip(reason="This test is not working")
-
-        mock_client = AsyncMock()
-        mock_client_class.return_value = mock_client
-
-        # Mock layer list response - _proxy_to_external returns the parsed JSON directly
-        mock_layers = [
-            {"name": "Layer1", "type": "Image"},
-            {"name": "Layer2", "type": "Labels"},
-        ]
-        mock_result = Mock()
-        mock_result.content = [Mock(text=json.dumps(mock_layers))]
-        mock_client.call_tool.return_value = mock_result
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=None)
-
-        result = await napari_mcp_server.list_layers()
-
-        assert len(result) == 2
-        assert result[0]["name"] == "Layer1"
-        assert result[1]["name"] == "Layer2"
-
-    @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client", side_effect=Exception("Connection refused"))
-    async def test_fallback_to_local_on_proxy_failure(self, _):
-        """Test fallback to local viewer when proxy fails."""
-        pytest.skip(reason="This test is not working")
-
-        # Mock local viewer
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-
-        with (
-            patch("napari_mcp.server._ensure_viewer", return_value=mock_viewer),
-            patch("napari_mcp.server._viewer_lock", asyncio.Lock()),
-        ):
-            result = await napari_mcp_server.list_layers()
-
-        # Should get empty list from local viewer
-        assert result == []
-
-    @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
-    async def test_init_viewer_with_external(self, mock_client_class):
-        """Test initializing viewer with external preference."""
-        pytest.skip(reason="This test is not working")
-
-        # Setup mock client
-        mock_client = AsyncMock()
-        mock_client_class.return_value = mock_client
-
-        # Mock session info
-        mock_result = Mock()
-        mock_info = {
-            "session_type": "napari_bridge_session",
-            "viewer": {"title": "External Viewer", "layer_names": ["Layer1", "Layer2"]},
-            "bridge_port": 9999,
-        }
-        mock_result.content = [Mock(text=json.dumps(mock_info))]
-        mock_client.call_tool.return_value = mock_result
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=None)
-
-        # Test init_viewer auto-detects external when available (port can be provided)
-        with patch("napari_mcp.server._viewer_lock", asyncio.Lock()):
-            result = await napari_mcp_server.init_viewer(port=9999)
-
-        assert result["status"] == "ok"
-        assert result["viewer_type"] == "external"
-        assert result["title"] == "External Viewer"
-        assert result["layers"] == ["Layer1", "Layer2"]
-        assert result["port"] == 9999
-
     @pytest.mark.asyncio
     async def test_init_viewer_with_local(self):
         """Test initializing viewer with local preference."""
@@ -134,11 +39,11 @@ async def test_init_viewer_with_local(self):
 
         with (
             patch(
-                "napari_mcp.server._detect_external_viewer", return_value=(None, None)
+                "napari_mcp.qt_helpers.ensure_viewer",
+                return_value=mock_viewer,
             ),
-            patch("napari_mcp.server._ensure_viewer", return_value=mock_viewer),
-            patch("napari_mcp.server._viewer_lock", asyncio.Lock()),
-            patch("napari_mcp.server._process_events"),
+            patch.object(napari_mcp_server, "ensure_viewer", return_value=mock_viewer),
+            patch("napari_mcp.qt_helpers.process_events"),
         ):
             result = await napari_mcp_server.init_viewer()
 
@@ -147,157 +52,88 @@ async def test_init_viewer_with_local(self):
         assert result["title"] == "Local Viewer"
 
 
-class TestBridgeWidget:
-    """Test the bridge widget integration."""
-
-    def test_widget_initialization(self, make_napari_viewer, qtbot):
-        """Test widget can be initialized with viewer."""
-        viewer = make_napari_viewer()
-        viewer.title = "Test Viewer"
-
-        from napari_mcp.widget import MCPControlWidget
+class TestMultiStepWorkflows:
+    """Test realistic multi-step tool workflows."""
 
-        widget = MCPControlWidget(napari_viewer=viewer)
-        qtbot.addWidget(widget)  # Add widget to qtbot for proper cleanup
-        assert widget.viewer == viewer
-        assert widget.port == 9999
-        assert widget.server is None
-
-    def test_widget_initialization_without_viewer(self, make_napari_viewer, qtbot):
-        """Test widget uses current_viewer when no viewer provided."""
+    @pytest.mark.asyncio
+    async def test_execute_code_adds_layer_visible_via_tools(self, make_napari_viewer):
+        """execute_code adds a layer, then list_layers and session_information see it."""
         viewer = make_napari_viewer()
-        viewer.title = "Current Viewer"
-
-        # Patch napari.current_viewer to return our viewer
-        import napari
-
-        with patch.object(napari, "current_viewer", return_value=viewer):
-            from napari_mcp.widget import MCPControlWidget
+        napari_mcp_server._state.viewer = viewer
 
-            widget = MCPControlWidget()
-            qtbot.addWidget(widget)
-            assert widget.viewer == viewer
-
-    def test_widget_initialization_no_viewer_error(self, qtbot):
-        """Test widget raises error when no viewer available."""
-        # Patch napari.current_viewer to return None
-        import napari
+        code = (
+            "import numpy as np; viewer.add_image(np.zeros((10, 10)), name='from_code')"
+        )
+        res = await napari_mcp_server.execute_code(code)
+        assert res["status"] == "ok"
 
-        with patch.object(napari, "current_viewer", return_value=None):
-            from napari_mcp.widget import MCPControlWidget
+        layers = await napari_mcp_server.list_layers()
+        assert any(lyr["name"] == "from_code" for lyr in layers)
 
-            with pytest.raises(RuntimeError, match="No napari viewer found"):
-                MCPControlWidget()
+        sess = await napari_mcp_server.session_information()
+        assert "from_code" in sess["viewer"]["layer_names"]
 
-    @patch("napari_mcp.widget.NapariBridgeServer")
-    def test_widget_start_server(self, mock_server_class, make_napari_viewer, qtbot):
-        """Test starting server from widget."""
+    @pytest.mark.asyncio
+    async def test_output_storage_across_multiple_executions(self, make_napari_viewer):
+        """Multiple execute_code calls store separate outputs, all retrievable."""
         viewer = make_napari_viewer()
-        mock_server = Mock()
-        mock_server.start.return_value = True
-        mock_server.is_running = True
-        mock_server_class.return_value = mock_server
+        napari_mcp_server._state.viewer = viewer
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
-        from napari_mcp.widget import MCPControlWidget
-
-        widget = MCPControlWidget(napari_viewer=viewer)
-        qtbot.addWidget(widget)
-        widget._start_server()
-
-        assert widget.server == mock_server
-        mock_server.start.assert_called_once()
-        assert widget.start_button.isEnabled() is False
-        assert widget.stop_button.isEnabled() is True
+        res1 = await napari_mcp_server.execute_code(
+            "for i in range(100): print(f'batch1_{i}')", line_limit=5
+        )
+        assert res1["status"] == "ok"
+        assert res1.get("truncated") is True
+        oid1 = res1["output_id"]
 
-    @patch("napari_mcp.widget.NapariBridgeServer")
-    def test_widget_stop_server(self, mock_server_class, make_napari_viewer, qtbot):
-        """Test stopping server from widget."""
-        viewer = make_napari_viewer()
-        mock_server = Mock()
-        mock_server.stop.return_value = True
-        mock_server.is_running = False
+        res2 = await napari_mcp_server.execute_code(
+            "for i in range(50): print(f'batch2_{i}')", line_limit=5
+        )
+        assert res2["status"] == "ok"
+        oid2 = res2["output_id"]
 
-        from napari_mcp.widget import MCPControlWidget
+        assert oid1 != oid2
 
-        widget = MCPControlWidget(napari_viewer=viewer)
-        qtbot.addWidget(widget)
-        widget.server = mock_server
-        widget._stop_server()
+        full1 = await napari_mcp_server.read_output(oid1)
+        assert full1["total_lines"] == 100
 
-        mock_server.stop.assert_called_once()
-        assert widget.start_button.isEnabled() is True
-        assert widget.stop_button.isEnabled() is False
+        full2 = await napari_mcp_server.read_output(oid2)
+        assert full2["total_lines"] == 50
 
 
-class TestProxyPatterns:
-    """Test various proxy patterns and edge cases."""
+class TestConcurrentToolCalls:
+    """Test concurrent tool access doesn't corrupt state."""
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
-    async def test_add_image_with_path_via_proxy(self, mock_client_class):
-        """Test adding image with file path through proxy."""
-        pytest.skip(reason="This test is not working")
-
-        mock_client = AsyncMock()
-        mock_client_class.return_value = mock_client
-
-        mock_result = Mock()
-        mock_result.content = [
-            Mock(
-                text=json.dumps(
-                    {"status": "ok", "name": "test_image", "shape": [512, 512, 3]}
-                )
-            )
-        ]
-        mock_client.call_tool.return_value = mock_result
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=None)
-
-        with patch("napari_mcp.server.Client", return_value=mock_client):
-            result = await napari_mcp_server.add_image(
-                path="/path/to/image.png", name="test", colormap="viridis"
-            )
-
-        assert result["status"] == "ok"
-        assert result["name"] == "test_image"
-        assert result["shape"] == [512, 512, 3]
+    async def test_concurrent_list_layers(self, make_napari_viewer):
+        """Multiple simultaneous list_layers calls return consistent results."""
+        viewer = make_napari_viewer()
+        napari_mcp_server._state.viewer = viewer
+        viewer.add_points([[1, 1]], name="pts")
 
-        # Verify correct parameters were passed
-        mock_client.call_tool.assert_called_once()
-        call_args = mock_client.call_tool.call_args
-        assert call_args[0][0] == "add_image"
-        assert call_args[0][1]["path"] == "/path/to/image.png"
-        assert call_args[0][1]["name"] == "test"
-        assert call_args[0][1]["colormap"] == "viridis"
+        results = await asyncio.gather(
+            napari_mcp_server.list_layers(),
+            napari_mcp_server.list_layers(),
+            napari_mcp_server.list_layers(),
+        )
+        for r in results:
+            assert isinstance(r, list)
+            assert any(lyr["name"] == "pts" for lyr in r)
 
     @pytest.mark.asyncio
-    @patch("napari_mcp.server.Client")
-    async def test_screenshot_via_proxy(self, mock_client_class):
-        """Test taking screenshot through proxy."""
-        pytest.skip(reason="This test is not working")
-
-        mock_client = AsyncMock()
-        mock_client_class.return_value = mock_client
-
-        # Mock base64 screenshot data
-        mock_result = Mock()
-        mock_screenshot = {
-            "mime_type": "image/png",
-            "base64_data": (
-                "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mN"
-                "kYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
-            ),
-        }
-        mock_result.content = [Mock(text=json.dumps(mock_screenshot))]
-        mock_client.call_tool.return_value = mock_result
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=None)
-
-        with patch("napari_mcp.server.Client", return_value=mock_client):
-            result = await napari_mcp_server.screenshot(canvas_only=True)
+    async def test_concurrent_execute_code(self, make_napari_viewer):
+        """Concurrent execute_code calls all return valid results."""
+        viewer = make_napari_viewer()
+        napari_mcp_server._state.viewer = viewer
 
-        assert result["mime_type"] == "image/png"
-        assert len(result["base64_data"]) > 0
-        mock_client.call_tool.assert_called_once_with(
-            "screenshot", {"canvas_only": True}
+        results = await asyncio.gather(
+            napari_mcp_server.execute_code("1 + 1"),
+            napari_mcp_server.execute_code("2 + 2"),
+            napari_mcp_server.execute_code("3 + 3"),
         )
+        expected = ["2", "4", "6"]
+        for r, exp in zip(results, expected, strict=False):
+            assert r["status"] == "ok"
+            assert r["result_repr"] == exp
diff --git a/tests/test_napari_server_coverage.py b/tests/test_napari_server_coverage.py
deleted file mode 100644
index 2fe65a2..0000000
--- a/tests/test_napari_server_coverage.py
+++ /dev/null
@@ -1,223 +0,0 @@
-"""
-Additional test coverage for napari_mcp_server module.
-
-This file provides additional tests to cover edge cases and error paths
-in napari_mcp_server.py to achieve 90% coverage.
-"""
-
-from unittest.mock import patch
-
-import numpy as np
-import pytest
-
-# Removed offscreen mode - it causes segfaults
-from napari_mcp.server import (
-    add_image,
-    add_points,
-    close_viewer,
-    execute_code,
-    init_viewer,
-    install_packages,
-    list_layers,
-    reset_view,
-    screenshot,
-    session_information,
-    set_active_layer,
-    set_ndisplay,
-)
-
-
-@pytest.mark.asyncio
-async def test_error_handling_with_no_viewer(make_napari_viewer):
-    """Test various functions handle no viewer gracefully."""
-    # Reset global viewer
-    from napari_mcp import server as napari_mcp_server
-
-    # Save original viewer
-    original_viewer = napari_mcp_server._viewer
-    napari_mcp_server._viewer = None
-
-    try:
-        # These should all handle no viewer gracefully by returning error status
-        result = await list_layers()
-        assert result == []
-
-        result = await screenshot()
-        assert result.mimeType.lower() in ("png", "image/png")
-        assert result.data is not None
-
-        result = await reset_view()
-        assert result["status"] == "ok"  # reset_view creates viewer if needed
-    finally:
-        # Restore original viewer
-        try:
-            # Close any viewer that may have been created by reset_view()
-            from napari_mcp.server import close_viewer as _close_viewer
-
-            await _close_viewer()
-        except Exception:  # noqa: BLE001
-            pass
-        napari_mcp_server._viewer = original_viewer
-
-
-@pytest.mark.asyncio
-async def test_complex_execute_code_scenarios(make_napari_viewer):
-    """Test complex code execution scenarios."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Test multi-line code with imports
-    code = """
-import numpy as np
-data = np.ones((5, 5))
-viewer.add_image(data, name='generated')
-len(viewer.layers)
-"""
-    result = await execute_code(code)
-
-    assert result["status"] == "ok"
-    assert result.get("result_repr") == "1"
-
-    # Test code with exception handling
-    code = """
-try:
-    x = 1 / 0
-except ZeroDivisionError:
-    result = "Caught division by zero"
-result
-"""
-    result = await execute_code(code)
-
-    assert result["status"] == "ok"
-    assert "Caught division by zero" in result.get("result_repr", "")
-
-
-@pytest.mark.asyncio
-async def test_session_information_with_selected_layers(make_napari_viewer):
-    """Test session information with selected layers."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-    # Use path parameter for add_image in napari_mcp_server
-    import tempfile
-
-    import imageio.v3 as iio
-
-    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
-        iio.imwrite(f.name, np.zeros((10, 10), dtype=np.uint8))
-        await add_image(f.name, name="image1")
-
-    await add_points([[5, 5]], name="points1")
-    await set_active_layer("points1")
-
-    result = await session_information()
-
-    assert result["status"] == "ok"
-    assert "points1" in result["viewer"]["selected_layers"]
-
-
-@pytest.mark.asyncio
-async def test_viewer_with_3d_data(make_napari_viewer):
-    """Test viewer operations with 3D data."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Add 3D image using file path
-    import tempfile
-
-    import imageio.v3 as iio
-
-    data_3d = np.zeros((10, 20, 30), dtype=np.uint8)
-    with tempfile.NamedTemporaryFile(suffix=".tif", delete=False) as f:
-        iio.imwrite(f.name, data_3d)
-        result = await add_image(f.name, name="3d_image")
-
-    assert result["status"] == "ok"
-    assert result["shape"] == [10, 20, 30]
-
-    # Switch to 3D display
-    result = await set_ndisplay(3)
-    assert result["status"] == "ok"
-    assert result["ndisplay"] == 3
-
-
-@pytest.mark.asyncio
-async def test_install_packages_error_handling(make_napari_viewer):
-    """Test package installation error handling."""
-    # Test with invalid package name
-    with patch("subprocess.run") as mock_run:
-        mock_run.return_value.returncode = 1
-        mock_run.return_value.stderr = "Package not found"
-
-        result = await install_packages(["nonexistent_package_xyz"])
-
-        assert result["status"] == "error"
-        # Check for error indicators in the response
-        stderr_lower = result.get("stderr", "").lower()
-        assert (
-            "error" in stderr_lower
-            or "not found" in stderr_lower
-            or "no matching" in stderr_lower
-            or "no module named pip" in stderr_lower
-        )
-
-
-@pytest.mark.asyncio
-async def test_close_viewer_multiple_times(make_napari_viewer):
-    """Test closing viewer multiple times."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # First close should succeed
-    result = await close_viewer()
-    assert result["status"] == "closed"
-
-    # Second close should indicate no viewer
-    result = await close_viewer()
-    assert result["status"] == "no_viewer"
-
-
-@pytest.mark.asyncio
-async def test_gui_operations(make_napari_viewer):
-    """Test GUI lifecycle via init_viewer/close_viewer."""
-    # Initialize viewer (starts GUI pump)
-    result = await init_viewer(title="Test")
-    assert result["status"] == "ok"
-
-    sess = await session_information()
-    assert sess["session"]["gui_pump_running"] is True
-
-    # Close viewer (stops GUI pump)
-    result = await close_viewer()
-    assert result["status"] == "closed"
-
-
-@pytest.mark.asyncio
-async def test_execute_code_with_viewer_operations(make_napari_viewer):
-    """Test executing code that manipulates viewer."""
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
-
-    # Code that adds layers
-    code = """
-viewer.add_image(np.ones((10, 10)), name='from_code')
-viewer.layers['from_code'].opacity = 0.5
-'Layer added'
-"""
-    result = await execute_code(code)
-
-    assert result["status"] == "ok"
-    assert "Layer added" in result.get("result_repr", "")
-
-    # Verify layer was added
-    layers = await list_layers()
-    assert any(layer["name"] == "from_code" for layer in layers)
diff --git a/tests/test_output_storage.py b/tests/test_output_storage.py
index 7742aea..6b15ed9 100644
--- a/tests/test_output_storage.py
+++ b/tests/test_output_storage.py
@@ -2,14 +2,8 @@
 
 import pytest
 
-from napari_mcp.server import (
-    _store_output,
-    _truncate_output,
-    close_viewer,
-    execute_code,
-    install_packages,
-    read_output,
-)
+from napari_mcp import server as napari_mcp_server
+from napari_mcp.output import truncate_output as _truncate_output
 
 
 class TestOutputTruncation:
@@ -75,11 +69,11 @@ async def test_store_and_retrieve_output(self):
         # Clear any existing storage
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
         # Store output
-        output_id = await _store_output(
+        output_id = await napari_mcp_server._state.store_output(
             tool_name="test_tool",
             stdout="test stdout",
             stderr="test stderr",
@@ -90,7 +84,7 @@ async def test_store_and_retrieve_output(self):
         assert output_id == "1"
 
         # Retrieve output
-        result = await read_output(output_id)
+        result = await napari_mcp_server.read_output(output_id)
         assert result["status"] == "ok"
         assert result["tool_name"] == "test_tool"
         assert result["result_repr"] == "'test result'"
@@ -99,7 +93,7 @@ async def test_store_and_retrieve_output(self):
 
     async def test_read_output_not_found(self):
         """Test reading non-existent output."""
-        result = await read_output("999")
+        result = await napari_mcp_server.read_output("999")
         assert result["status"] == "error"
         assert "not found" in result["message"]
 
@@ -108,15 +102,17 @@ async def test_read_output_with_range(self):
         # Clear storage
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
         # Store multi-line output
         multiline_stdout = "\n".join([f"line {i}" for i in range(10)])
-        output_id = await _store_output(tool_name="test_tool", stdout=multiline_stdout)
+        output_id = await napari_mcp_server._state.store_output(
+            tool_name="test_tool", stdout=multiline_stdout
+        )
 
         # Read first 3 lines
-        result = await read_output(output_id, start=0, end=3)
+        result = await napari_mcp_server.read_output(output_id, start=0, end=3)
         assert result["status"] == "ok"
         assert result["line_range"]["start"] == 0
         assert result["line_range"]["end"] == 3
@@ -128,13 +124,15 @@ async def test_read_output_beyond_range(self):
         """Test reading output beyond available range."""
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
-        output_id = await _store_output(tool_name="test_tool", stdout="line1\nline2\n")
+        output_id = await napari_mcp_server._state.store_output(
+            tool_name="test_tool", stdout="line1\nline2\n"
+        )
 
         # Try to read beyond available lines
-        result = await read_output(output_id, start=5, end=10)
+        result = await napari_mcp_server.read_output(output_id, start=5, end=10)
         assert result["status"] == "ok"
         assert len(result["lines"]) == 0
         assert result["total_lines"] == 2
@@ -149,46 +147,46 @@ async def test_execute_code_default_limit(self, make_napari_viewer):
         viewer = make_napari_viewer()
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._viewer = viewer
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.viewer = viewer
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
         # Execute code that produces output
-        result = await execute_code('print("test output")')
+        result = await napari_mcp_server.execute_code('print("test output")')
         assert result["status"] == "ok"
         assert "output_id" in result
         assert "test output" in result["stdout"]
 
-        await close_viewer()
+        await napari_mcp_server.close_viewer()
 
     async def test_execute_code_unlimited_output(self, make_napari_viewer):
         """Test execute_code with unlimited output."""
         viewer = make_napari_viewer()
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._viewer = viewer
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.viewer = viewer
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
-        result = await execute_code('print("test")', line_limit=-1)
+        result = await napari_mcp_server.execute_code('print("test")', line_limit=-1)
         assert result["status"] == "ok"
         assert "warning" in result
         assert "large number of tokens" in result["warning"]
 
-        await close_viewer()
+        await napari_mcp_server.close_viewer()
 
     async def test_execute_code_with_truncation(self, make_napari_viewer):
         """Test execute_code that produces output requiring truncation."""
         viewer = make_napari_viewer()
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._viewer = viewer
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.viewer = viewer
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
         # Generate many lines of output
         code = "for i in range(50): print(f'line {i}')"
-        result = await execute_code(code, line_limit=5)
+        result = await napari_mcp_server.execute_code(code, line_limit=5)
 
         assert result["status"] == "ok"
         assert "truncated" in result
@@ -196,26 +194,28 @@ async def test_execute_code_with_truncation(self, make_napari_viewer):
         assert "Use read_output" in result["message"]
 
         # Verify we can read the full output
-        full_result = await read_output(result["output_id"])
+        full_result = await napari_mcp_server.read_output(result["output_id"])
         assert len(full_result["lines"]) == 50
 
-        await close_viewer()
+        await napari_mcp_server.close_viewer()
 
     async def test_execute_code_error_with_limiting(self, make_napari_viewer):
         """Test execute_code error handling with line limiting."""
         viewer = make_napari_viewer()
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._viewer = viewer
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.viewer = viewer
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
-        result = await execute_code('raise ValueError("test error")', line_limit=5)
+        result = await napari_mcp_server.execute_code(
+            'raise ValueError("test error")', line_limit=5
+        )
         assert result["status"] == "error"
         assert "output_id" in result
         assert "ValueError" in result["stderr"]
 
-        await close_viewer()
+        await napari_mcp_server.close_viewer()
 
 
 @pytest.mark.asyncio
@@ -226,11 +226,13 @@ async def test_install_packages_default_limit(self):
         """Test install_packages with default line limit."""
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
         # Use a package that should fail quickly to avoid long test times
-        result = await install_packages(["nonexistent-package-xyz-123"])
+        result = await napari_mcp_server.install_packages(
+            ["nonexistent-package-xyz-123"]
+        )
 
         assert "output_id" in result
         assert "status" in result
@@ -242,22 +244,24 @@ async def test_install_packages_unlimited_output(self):
         """Test install_packages with unlimited output."""
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
-        result = await install_packages(["nonexistent-package"], line_limit=-1)
+        result = await napari_mcp_server.install_packages(
+            ["nonexistent-package"], line_limit=-1
+        )
         assert "warning" in result
         assert "large number of tokens" in result["warning"]
 
     async def test_install_packages_empty_list(self):
         """Test install_packages with empty package list."""
-        result = await install_packages([])
+        result = await napari_mcp_server.install_packages([])
         assert result["status"] == "error"
         assert "non-empty list" in result["message"]
 
     async def test_install_packages_invalid_input(self):
         """Test install_packages with invalid input."""
-        result = await install_packages("not-a-list")  # type: ignore
+        result = await napari_mcp_server.install_packages("not-a-list")  # type: ignore
         assert result["status"] == "error"
         assert "non-empty list" in result["message"]
 
@@ -270,16 +274,18 @@ async def test_read_output_full_range(self):
         """Test reading full output range."""
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
         # Store test output
         lines = [f"line {i}\n" for i in range(10)]
         output_text = "".join(lines)
-        output_id = await _store_output(tool_name="test_tool", stdout=output_text)
+        output_id = await napari_mcp_server._state.store_output(
+            tool_name="test_tool", stdout=output_text
+        )
 
         # Read full range (default parameters)
-        result = await read_output(output_id)
+        result = await napari_mcp_server.read_output(output_id)
         assert result["status"] == "ok"
         assert result["total_lines"] == 10
         assert len(result["lines"]) == 10
@@ -288,15 +294,17 @@ async def test_read_output_partial_range(self):
         """Test reading partial output range."""
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
         lines = [f"line {i}\n" for i in range(20)]
         output_text = "".join(lines)
-        output_id = await _store_output(tool_name="test_tool", stdout=output_text)
+        output_id = await napari_mcp_server._state.store_output(
+            tool_name="test_tool", stdout=output_text
+        )
 
         # Read middle portion
-        result = await read_output(output_id, start=5, end=10)
+        result = await napari_mcp_server.read_output(output_id, start=5, end=10)
         assert result["status"] == "ok"
         assert result["line_range"]["start"] == 5
         assert result["line_range"]["end"] == 10
@@ -308,19 +316,80 @@ async def test_read_output_combined_stdout_stderr(self):
         """Test reading output with both stdout and stderr."""
         from napari_mcp import server as napari_mcp_server
 
-        napari_mcp_server._output_storage.clear()
-        napari_mcp_server._next_output_id = 1
+        napari_mcp_server._state.output_storage.clear()
+        napari_mcp_server._state.next_output_id = 1
 
-        output_id = await _store_output(
+        output_id = await napari_mcp_server._state.store_output(
             tool_name="test_tool",
             stdout="stdout line 1\nstdout line 2\n",
             stderr="stderr line 1\nstderr line 2\n",
         )
 
-        result = await read_output(output_id)
+        result = await napari_mcp_server.read_output(output_id)
         assert result["status"] == "ok"
 
         # Check that both stdout and stderr are included
         combined_output = "".join(result["lines"])
         assert "stdout line 1" in combined_output
         assert "stderr line 1" in combined_output
+
+
+@pytest.mark.asyncio
+class TestOutputEviction:
+    """Test output storage eviction when exceeding capacity."""
+
+    async def test_eviction_removes_oldest_entries(self):
+        """Test that oldest entries are evicted when capacity is exceeded."""
+        from napari_mcp import server as napari_mcp_server
+
+        # Save originals
+        orig_storage = napari_mcp_server._state.output_storage.copy()
+        orig_max = napari_mcp_server._state.max_output_items
+        orig_id = napari_mcp_server._state.next_output_id
+
+        try:
+            napari_mcp_server._state.output_storage.clear()
+            napari_mcp_server._state.next_output_id = 1
+            napari_mcp_server._state.max_output_items = 3
+
+            # Store 5 outputs
+            ids = []
+            for i in range(5):
+                oid = await napari_mcp_server._state.store_output(
+                    tool_name=f"tool_{i}", stdout=f"output {i}"
+                )
+                ids.append(oid)
+
+            # Only the last 3 should remain
+            assert len(napari_mcp_server._state.output_storage) == 3
+
+            # First 2 should be evicted
+            result1 = await napari_mcp_server.read_output(ids[0])
+            assert result1["status"] == "error"
+            assert "not found" in result1["message"]
+
+            result2 = await napari_mcp_server.read_output(ids[1])
+            assert result2["status"] == "error"
+
+            # Last 3 should still be accessible
+            for oid in ids[2:]:
+                result = await napari_mcp_server.read_output(oid)
+                assert result["status"] == "ok"
+
+        finally:
+            # Restore originals
+            napari_mcp_server._state.output_storage.clear()
+            napari_mcp_server._state.output_storage.update(orig_storage)
+            napari_mcp_server._state.max_output_items = orig_max
+            napari_mcp_server._state.next_output_id = orig_id
+
+
+class TestTruncateOutputCanonicalImport:
+    """Test canonical import of truncate_output from output module."""
+
+    def test_output_module_import(self):
+        from napari_mcp.output import truncate_output
+
+        result, was_truncated = truncate_output("a\nb\n", 1)
+        assert was_truncated is True
+        assert result == "a\n"
diff --git a/tests/test_performance.py b/tests/test_performance.py
index 2737165..6450a52 100644
--- a/tests/test_performance.py
+++ b/tests/test_performance.py
@@ -1,25 +1,16 @@
 """Performance and benchmark tests for napari-mcp."""
 
-import asyncio
-import os
 import time
 from collections.abc import Generator
 from contextlib import contextmanager
-from unittest.mock import Mock, patch
+from unittest.mock import Mock
 
 import numpy as np
 import pytest
 
-# Removed offscreen mode - it causes segfaults
-
 # Performance test configuration
 PERFORMANCE_THRESHOLD = {
-    "layer_add": 0.1,  # 100ms
-    "layer_remove": 0.05,  # 50ms
     "screenshot": 0.5,  # 500ms
-    "code_execution": 0.2,  # 200ms
-    "viewer_init": 1.0,  # 1s
-    "bulk_operations": 2.0,  # 2s
 }
 
 
@@ -35,76 +26,7 @@ def measure_time(operation: str) -> Generator[dict, None, None]:
 
 
 class TestPerformanceBenchmarks:
-    """Performance benchmark tests."""
-
-    @pytest.mark.benchmark
-    def test_layer_addition_performance(self):
-        """Benchmark layer addition operations."""
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-        mock_viewer.add_image = Mock(
-            side_effect=lambda data, **kwargs: mock_viewer.layers.append(
-                Mock(data=data)
-            )
-        )
-
-        # Generate test data
-        data_sizes = [(100, 100), (500, 500), (1000, 1000)]
-        results = []
-
-        for size in data_sizes:
-            data = np.random.random(size)
-
-            with measure_time(f"add_layer_{size}") as timer:
-                mock_viewer.add_image(data)
-
-            results.append(timer)
-            assert timer["duration"] < PERFORMANCE_THRESHOLD["layer_add"]
-
-        # Performance regression check
-        avg_time = sum(r["duration"] for r in results) / len(results)
-        assert avg_time < PERFORMANCE_THRESHOLD["layer_add"], (
-            f"Layer addition too slow: {avg_time:.3f}s"
-        )
-
-    @pytest.mark.benchmark
-    def test_bulk_layer_operations(self):
-        """Test performance of bulk layer operations."""
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-
-        with measure_time("bulk_add_100_layers") as timer:
-            for i in range(100):
-                layer = Mock(name=f"layer_{i}")
-                mock_viewer.layers.append(layer)
-
-        assert timer["duration"] < PERFORMANCE_THRESHOLD["bulk_operations"]
-
-        # Test bulk removal
-        with measure_time("bulk_remove_50_layers") as timer:
-            for _ in range(50):
-                if mock_viewer.layers:
-                    mock_viewer.layers.pop()
-
-        assert timer["duration"] < PERFORMANCE_THRESHOLD["bulk_operations"] / 2
-
-    @pytest.mark.benchmark
-    @pytest.mark.asyncio
-    async def test_concurrent_operations_performance(self):
-        """Test performance under concurrent operations."""
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-
-        async def add_layer(index: int):
-            await asyncio.sleep(0.001)  # Simulate async work
-            mock_viewer.layers.append(Mock(name=f"layer_{index}"))
-
-        with measure_time("concurrent_add_50_layers") as timer:
-            tasks = [add_layer(i) for i in range(50)]
-            await asyncio.gather(*tasks)
-
-        assert timer["duration"] < 1.0  # Should complete within 1 second
-        assert len(mock_viewer.layers) == 50
+    """Performance benchmark tests that exercise real code."""
 
     @pytest.mark.benchmark
     def test_memory_usage_layer_operations(self):
@@ -112,16 +34,15 @@ def test_memory_usage_layer_operations(self):
         import tracemalloc
 
         tracemalloc.start()
-        mock_viewer = Mock()
-        mock_viewer.layers = []
 
         # Baseline memory
         snapshot1 = tracemalloc.take_snapshot()
 
-        # Add large layers
+        # Allocate real numpy arrays (not just mocks)
+        arrays = []
         for _ in range(10):
             data = np.zeros((1000, 1000, 3), dtype=np.uint8)  # ~3MB each
-            mock_viewer.layers.append(Mock(data=data))
+            arrays.append(data)
 
         snapshot2 = tracemalloc.take_snapshot()
 
@@ -130,192 +51,47 @@ def test_memory_usage_layer_operations(self):
         total_memory = sum(stat.size_diff for stat in stats) / 1024 / 1024  # MB
 
         # Clean up
+        del arrays
         tracemalloc.stop()
 
         # Memory should be reasonable (less than 50MB for 10 layers)
         assert total_memory < 50, f"Excessive memory usage: {total_memory:.2f}MB"
 
     @pytest.mark.benchmark
-    def test_screenshot_performance(self):
-        """Test screenshot generation performance."""
-        mock_viewer = Mock()
-
-        # Mock screenshot with different sizes
+    def test_screenshot_encoding_performance(self):
+        """Test screenshot PNG encoding performance with real PIL."""
         sizes = [(100, 100), (800, 600), (1920, 1080)]
 
         for size in sizes:
             mock_data = np.zeros((*size, 4), dtype=np.uint8)
-            mock_viewer.screenshot = Mock(return_value=mock_data)
 
             with measure_time(f"screenshot_{size}") as timer:
-                result = mock_viewer.screenshot(canvas_only=True)
-                # Simulate encoding
                 import base64
                 from io import BytesIO
 
                 from PIL import Image
 
-                img = Image.fromarray(result[:, :, :3])
+                img = Image.fromarray(mock_data[:, :, :3])
                 buffer = BytesIO()
                 img.save(buffer, format="PNG")
-                _ = base64.b64encode(buffer.getvalue())  # Simulate encoding
+                _ = base64.b64encode(buffer.getvalue())
 
             assert timer["duration"] < PERFORMANCE_THRESHOLD["screenshot"]
 
 
-class TestScalabilityTests:
-    """Scalability tests for napari-mcp."""
-
-    @pytest.mark.slow
-    def test_layer_count_scalability(self):
-        """Test system behavior with many layers."""
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-
-        layer_counts = [10, 50, 100, 500]
-        timings = []
-
-        for count in layer_counts:
-            mock_viewer.layers.clear()
-
-            with measure_time(f"add_{count}_layers") as timer:
-                for i in range(count):
-                    mock_viewer.layers.append(Mock(name=f"layer_{i}"))
-
-            timings.append((count, timer["duration"]))
-
-        # Check for linear or better scaling
-        for i in range(1, len(timings)):
-            prev_count, prev_time = timings[i - 1]
-            curr_count, curr_time = timings[i]
-
-            # Time should not scale worse than O(n log n)
-            expected_max_time = (
-                prev_time
-                * (curr_count / prev_count)
-                * np.log2(curr_count / prev_count + 1)
-            )
-
-            assert curr_time < expected_max_time * 1.5, (
-                f"Poor scaling: {curr_count} layers took {curr_time:.3f}s"
-            )
-
-    @pytest.mark.slow
-    @pytest.mark.asyncio
-    async def test_concurrent_viewer_operations(self):
-        """Test concurrent operations on multiple viewers."""
-        viewers = [Mock() for _ in range(5)]
-
-        async def operate_on_viewer(viewer, viewer_id):
-            viewer.layers = []
-            for i in range(20):
-                await asyncio.sleep(0.001)
-                viewer.layers.append(Mock(name=f"viewer_{viewer_id}_layer_{i}"))
-
-        with measure_time("concurrent_5_viewers") as timer:
-            tasks = [operate_on_viewer(v, i) for i, v in enumerate(viewers)]
-            await asyncio.gather(*tasks)
-
-        assert timer["duration"] < 2.0  # Should complete within 2 seconds
-
-        # Verify all viewers have correct number of layers
-        for viewer in viewers:
-            assert len(viewer.layers) == 20
-
-    @pytest.mark.slow
-    def test_data_size_scalability(self):
-        """Test performance with different data sizes."""
-        mock_viewer = Mock()
-        mock_viewer.add_image = Mock()
-
-        data_sizes = [
-            (100, 100),
-            (500, 500),
-            (1000, 1000),
-            (2000, 2000),
-        ]
-
-        timings = []
-
-        for size in data_sizes:
-            data = np.random.random(size)
-
-            with measure_time(f"process_{size}") as timer:
-                mock_viewer.add_image(data)
-                # Simulate processing
-                _ = data.mean()
-                _ = data.std()
-
-            timings.append((np.prod(size), timer["duration"]))
-
-        # Check scaling is not worse than O(n)
-        for i in range(1, len(timings)):
-            prev_pixels, prev_time = timings[i - 1]
-            curr_pixels, curr_time = timings[i]
-
-            # Linear scaling with tolerance for CI variability
-            expected_time = prev_time * (curr_pixels / prev_pixels)
-            # Use 3x tolerance for CI environments (was 2x)
-            tolerance = 3.0 if os.environ.get("CI") else 2.0
-            assert curr_time < expected_time * tolerance, (
-                f"Poor data scaling: {curr_pixels} pixels took {curr_time:.3f}s"
-            )
-
-
 class TestPerformanceRegression:
     """Performance regression tests."""
 
-    @pytest.fixture
-    def performance_baseline(self):
-        """Load or create performance baseline."""
-        return {
-            "layer_add": 0.05,
-            "layer_remove": 0.02,
-            "screenshot_small": 0.1,
-            "screenshot_large": 0.3,
-            "bulk_operation": 0.5,
-        }
-
-    @pytest.mark.benchmark
-    def test_regression_layer_operations(self, performance_baseline):
-        """Test for performance regression in layer operations."""
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-
-        operations = {
-            "layer_add": lambda: mock_viewer.layers.append(Mock()),
-            "layer_remove": lambda: mock_viewer.layers.pop()
-            if mock_viewer.layers
-            else None,
-        }
-
-        for op_name, operation in operations.items():
-            # Prepare state
-            mock_viewer.layers = [Mock() for _ in range(10)]
-
-            # Measure operation
-            with measure_time(op_name) as timer:
-                for _ in range(100):
-                    operation()
-
-            avg_time = timer["duration"] / 100
-            baseline = performance_baseline.get(op_name, 0.1)
-
-            # Allow more tolerance in CI environments
-            tolerance = 1.5 if os.environ.get("CI") else 1.2
-            assert avg_time < baseline * tolerance, (
-                f"Performance regression in {op_name}: {avg_time:.4f}s vs baseline {baseline:.4f}s"
-            )
-
     @pytest.mark.benchmark
     @pytest.mark.asyncio
-    async def test_regression_async_operations(self, performance_baseline):
+    async def test_regression_async_operations(self):
         """Test for performance regression in async operations."""
         from napari_mcp import server as napari_mcp_server
 
         mock_viewer = Mock()
         mock_viewer.layers = []  # Make layers iterable
-        with patch("napari_mcp.server._viewer", mock_viewer):
+        napari_mcp_server._state.viewer = mock_viewer
+        try:
             operations = [("list_layers", napari_mcp_server.list_layers)]
 
             for op_name, operation in operations:
@@ -325,123 +101,28 @@ async def test_regression_async_operations(self, performance_baseline):
 
                 avg_time = timer["duration"] / 10
 
-                # These should be very fast
-                assert avg_time < 0.02, (
+                # In STANDALONE mode proxy is a no-op, so should be fast
+                assert avg_time < 0.1, (
                     f"Async operation {op_name} too slow: {avg_time:.4f}s"
                 )
+        finally:
+            napari_mcp_server._state.viewer = None
 
 
-class TestCachingPerformance:
-    """Test caching and memoization performance."""
-
-    def test_viewer_singleton_performance(self):
-        """Test that viewer singleton pattern improves performance."""
-        from napari_mcp import server as napari_mcp_server
-
-        with patch("napari.Viewer", Mock()) as mock_viewer_class:
-            mock_viewer_class.return_value = Mock()
-
-            # First access - should create viewer
-            with measure_time("first_viewer_access") as timer1:
-                napari_mcp_server._ensure_viewer()
-
-            # Subsequent accesses - should be cached
-            timings = []
-            for i in range(100):
-                with measure_time(f"cached_access_{i}") as timer:
-                    napari_mcp_server._ensure_viewer()
-                timings.append(timer["duration"])
-
-            avg_cached_time = sum(timings) / len(timings)
-
-            # Cached access should be at least 10x faster
-            assert avg_cached_time < timer1["duration"] / 10, (
-                "Viewer singleton not providing performance benefit"
-            )
-
-    def test_exec_globals_caching(self):
-        """Test that exec globals are properly cached."""
-        from napari_mcp.server import _exec_globals
-
-        # First execution - builds namespace
-        code1 = "x = 1"
-        with measure_time("first_exec") as timer1:
-            exec(code1, _exec_globals)
-
-        # Subsequent execution - uses cached namespace
-        code2 = "y = x + 1"
-        with measure_time("cached_exec") as timer2:
-            exec(code2, _exec_globals)
-
-        # Cached execution should be fast (more tolerance in CI)
-        tolerance = 4 if os.environ.get("CI") else 3
-        assert timer2["duration"] < timer1["duration"] * tolerance
-        assert _exec_globals.get("y") == 2
-
-
-@pytest.mark.benchmark
-class TestLoadTesting:
-    """Load testing for napari-mcp."""
+class TestExecGlobalsPersistence:
+    """Test that the execution namespace persists across calls."""
 
     @pytest.mark.asyncio
-    async def test_high_frequency_operations(self):
-        """Test system under high frequency operations."""
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-
-        operation_count = 1000
-
-        async def rapid_operation(index):
-            # Simulate rapid fire operations
-            if index % 2 == 0:
-                mock_viewer.layers.append(Mock(name=f"layer_{index}"))
-            elif mock_viewer.layers:
-                mock_viewer.layers.pop()
-
-        with measure_time(f"{operation_count}_rapid_operations") as timer:
-            tasks = [rapid_operation(i) for i in range(operation_count)]
-            await asyncio.gather(*tasks)
-
-        # Should handle 1000 operations in reasonable time
-        assert timer["duration"] < 5.0
-
-        # System should remain stable
-        assert isinstance(mock_viewer.layers, list)
-
-    def test_memory_stability_under_load(self):
-        """Test memory stability under sustained load."""
-        import gc
-        import tracemalloc
-
-        tracemalloc.start()
-        initial_snapshot = tracemalloc.take_snapshot()
-
-        mock_viewer = Mock()
-
-        # Simulate sustained load
-        for _ in range(10):
-            layers = []
-
-            # Add many layers
-            for _ in range(100):
-                layer = Mock(data=np.zeros((100, 100)))
-                layers.append(layer)
-
-            mock_viewer.layers = layers
-
-            # Clear and force garbage collection
-            mock_viewer.layers.clear()
-            gc.collect()
-
-        final_snapshot = tracemalloc.take_snapshot()
-        stats = final_snapshot.compare_to(initial_snapshot, "lineno")
+    async def test_exec_globals_persist_across_calls(self, make_napari_viewer):
+        """Variables set in one execute_code call are available in the next."""
+        from napari_mcp import server as napari_mcp_server
 
-        # Calculate leak
-        leak_mb = (
-            sum(stat.size_diff for stat in stats if stat.size_diff > 0) / 1024 / 1024
-        )
+        viewer = make_napari_viewer()
+        napari_mcp_server._state.viewer = viewer
 
-        tracemalloc.stop()
+        res = await napari_mcp_server.execute_code("my_var = 42")
+        assert res["status"] == "ok"
 
-        # Should not leak more than 10MB after cycles
-        assert leak_mb < 10, f"Memory leak detected: {leak_mb:.2f}MB"
+        res = await napari_mcp_server.execute_code("my_var * 2")
+        assert res["status"] == "ok"
+        assert res["result_repr"] == "84"
diff --git a/tests/test_property_based.py b/tests/test_property_based.py
index 39880b0..1bc599d 100644
--- a/tests/test_property_based.py
+++ b/tests/test_property_based.py
@@ -1,158 +1,103 @@
 """Property-based tests for napari-mcp using Hypothesis."""
 
-from unittest.mock import Mock
-
 import numpy as np
-import pytest
-from hypothesis import assume, given, settings
+from hypothesis import given, settings
 from hypothesis import strategies as st
 from hypothesis.extra.numpy import arrays
 
-# Removed offscreen mode - it causes segfaults
-# Use the mock napari from conftest
-from napari_mcp.server import NapariMCPTools
+from napari_mcp._helpers import parse_bool as _parse_bool
+from napari_mcp.output import truncate_output as _truncate_output
 
 
-class TestPropertyBasedLayerOperations:
-    """Property-based tests for layer operations."""
+class TestPropertyBasedParseBool:
+    """Property-based tests for _parse_bool."""
 
-    @given(
-        layer_names=st.lists(
-            st.text(
-                min_size=1,
-                max_size=50,
-                alphabet=st.characters(min_codepoint=65, max_codepoint=122),
-            ),
-            min_size=1,
-            max_size=10,
-            unique=True,
-        )
-    )
+    @given(value=st.booleans())
     @settings(max_examples=50, deadline=None)
-    def test_layer_name_uniqueness_invariant(self, layer_names):
-        """Test that layer names remain unique after operations."""
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-        _ = NapariMCPTools()  # Tools instance not used directly
-        _viewer = mock_viewer
-
-        # Property: Adding layers should maintain unique names
-        added_names = set()
-        for name in layer_names:
-            if name not in added_names:
-                layer = Mock()
-                layer.name = name
-                mock_viewer.layers.append(layer)
-                added_names.add(name)
-
-        # Verify uniqueness invariant
-        actual_names = [layer.name for layer in mock_viewer.layers]
-        assert len(actual_names) == len(set(actual_names))
+    def test_bool_passthrough(self, value):
+        """Test that bool values pass through unchanged."""
+        assert _parse_bool(value) is value
 
     @given(
-        dimensions=st.integers(min_value=2, max_value=4),
-        shape=st.lists(
-            st.integers(min_value=10, max_value=100), min_size=2, max_size=4
-        ),
+        true_str=st.sampled_from(
+            ["true", "True", "TRUE", "1", "yes", "Yes", "on", "ON"]
+        )
     )
-    @settings(max_examples=30, deadline=None)
-    def test_image_data_shape_preservation(self, dimensions, shape):
-        """Test that image data shapes are preserved correctly."""
-        # Adjust shape to match dimensions
-        shape = shape[:dimensions]
+    @settings(max_examples=50, deadline=None)
+    def test_true_strings(self, true_str):
+        """Test that all true-like strings return True."""
+        assert _parse_bool(true_str) is True
 
-        _viewer = None
-        mock_viewer = Mock()
-        mock_viewer.add_image = Mock()
-        _viewer = mock_viewer
-        _ = NapariMCPTools()  # Tools instance not used directly
+    @given(false_str=st.sampled_from(["false", "False", "0", "no", "off", ""]))
+    @settings(max_examples=50, deadline=None)
+    def test_false_strings(self, false_str):
+        """Test that all false-like strings return False."""
+        assert _parse_bool(false_str) is False
 
-        # Create random numpy array with given shape
-        data = np.random.random(shape)
+    @given(default=st.booleans())
+    @settings(max_examples=20, deadline=None)
+    def test_none_returns_default(self, default):
+        """Test that None returns the default value."""
+        assert _parse_bool(None, default=default) is default
 
-        # Property: Shape should be preserved when adding image
-        mock_viewer.add_image(data)
-        mock_viewer.add_image.assert_called_once()
-        call_args = mock_viewer.add_image.call_args[0]
 
-        assert call_args[0].shape == tuple(shape)
+class TestPropertyBasedTruncateOutput:
+    """Property-based tests for _truncate_output."""
 
     @given(
-        zoom_level=st.floats(
-            min_value=0.1, max_value=10.0, allow_nan=False, allow_infinity=False
+        lines=st.lists(
+            st.text(
+                min_size=1,
+                max_size=80,
+                alphabet=st.characters(min_codepoint=32, max_codepoint=126),
+            ),
+            min_size=0,
+            max_size=50,
         ),
-        center_x=st.floats(min_value=-1000, max_value=1000, allow_nan=False),
-        center_y=st.floats(min_value=-1000, max_value=1000, allow_nan=False),
+        line_limit=st.integers(min_value=0, max_value=100),
     )
-    @settings(max_examples=50, deadline=None)
-    def test_camera_state_consistency(self, zoom_level, center_x, center_y):
-        """Test camera state remains consistent after transformations."""
-        mock_viewer = Mock()
-        mock_viewer.camera = Mock()
-        mock_viewer.camera.zoom = 1.0
-        mock_viewer.camera.center = [0, 0]
-
-        # Property: Camera state should be retrievable after setting
-        mock_viewer.camera.zoom = zoom_level
-        mock_viewer.camera.center = [center_x, center_y]
-
-        assert mock_viewer.camera.zoom == zoom_level
-        assert mock_viewer.camera.center == [center_x, center_y]
+    @settings(max_examples=100, deadline=None)
+    def test_truncation_respects_limit(self, lines, line_limit):
+        """Test that truncated output never exceeds line_limit."""
+        output = "\n".join(lines) + ("\n" if lines else "")
+        result, was_truncated = _truncate_output(output, line_limit)
+
+        # Count non-empty trailing lines
+        actual_line_count = (
+            len([line for line in result.split("\n") if line]) if result else 0
+        )
 
-        # Property: Zoom level should remain positive
-        assert mock_viewer.camera.zoom > 0
+        assert actual_line_count <= max(line_limit, 0)
 
     @given(
-        opacity_values=st.lists(
-            st.floats(min_value=0.0, max_value=1.0, allow_nan=False),
+        lines=st.lists(
+            st.text(
+                min_size=1,
+                max_size=20,
+                alphabet=st.characters(min_codepoint=65, max_codepoint=90),
+            ),
             min_size=1,
-            max_size=5,
-        )
+            max_size=20,
+        ),
     )
     @settings(max_examples=50, deadline=None)
-    def test_layer_opacity_bounds(self, opacity_values):
-        """Test that layer opacity values stay within valid bounds."""
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-
-        for i, opacity in enumerate(opacity_values):
-            layer = Mock()
-            layer.name = f"layer_{i}"
-            layer.opacity = opacity
-            mock_viewer.layers.append(layer)
-
-        # Property: All opacity values should be in [0, 1]
-        for layer in mock_viewer.layers:
-            assert 0.0 <= layer.opacity <= 1.0
+    def test_unlimited_returns_full_output(self, lines):
+        """Test that line_limit=-1 returns full output."""
+        output = "\n".join(lines) + "\n"
+        result, was_truncated = _truncate_output(output, -1)
+        assert result == output
+        assert was_truncated is False
 
     @given(
-        layer_indices=st.lists(
-            st.integers(min_value=0, max_value=9), min_size=2, max_size=10
-        )
+        line_limit=st.integers(min_value=-10, max_value=-1),
+        output=st.text(min_size=1, max_size=200),
     )
     @settings(max_examples=30, deadline=None)
-    def test_layer_reordering_preservation(self, layer_indices):
-        """Test that layer reordering preserves all layers."""
-        mock_viewer = Mock()
-        initial_layers = [Mock(name=f"layer_{i}") for i in range(10)]
-        mock_viewer.layers = initial_layers.copy()
-
-        # Simulate reordering
-        assume(max(layer_indices) < len(mock_viewer.layers))
-
-        # Property: Reordering should preserve layer count
-        _ = len(mock_viewer.layers)  # Store original count for reference
-
-        # Perform mock reordering (simplified)
-        if len(set(layer_indices)) == len(layer_indices):  # Only if indices are unique
-            reordered = [
-                mock_viewer.layers[i]
-                for i in layer_indices
-                if i < len(mock_viewer.layers)
-            ]
-            assert len(set(reordered)) == len(
-                reordered
-            )  # No duplicates after reordering
+    def test_negative_limits_are_unlimited(self, line_limit, output):
+        """Test that any negative line_limit acts as unlimited."""
+        result, was_truncated = _truncate_output(output, line_limit)
+        assert result == output
+        assert was_truncated is False
 
 
 class TestPropertyBasedDataTransformations:
@@ -169,195 +114,30 @@ class TestPropertyBasedDataTransformations:
     )
     @settings(max_examples=30, deadline=None)
     def test_screenshot_encoding_roundtrip(self, array_data):
-        """Test that screenshot encoding/decoding is lossless for valid data."""
+        """Test that screenshot encoding/decoding preserves image dimensions."""
         import base64
         from io import BytesIO
 
         from PIL import Image
 
         # Normalize data to valid image range
-        normalized = (
-            (array_data - array_data.min())
-            / (array_data.max() - array_data.min() + 1e-10)
-            * 255
-        ).astype(np.uint8)
+        data_range = array_data.max() - array_data.min()
+        if data_range == 0:
+            normalized = np.zeros_like(array_data, dtype=np.uint8)
+        else:
+            normalized = (
+                (array_data - array_data.min()) / (data_range + 1e-10) * 255
+            ).astype(np.uint8)
 
-        # Convert to RGB
         rgb_data = np.stack([normalized] * 3, axis=-1)
 
-        # Property: Encoding and decoding should preserve image dimensions
         img = Image.fromarray(rgb_data)
         buffer = BytesIO()
         img.save(buffer, format="PNG")
         encoded = base64.b64encode(buffer.getvalue()).decode("utf-8")
 
-        # Decode
         decoded_bytes = base64.b64decode(encoded)
         decoded_img = Image.open(BytesIO(decoded_bytes))
         decoded_array = np.array(decoded_img)
 
         assert decoded_array.shape == rgb_data.shape
-
-    @given(
-        points=arrays(
-            dtype=np.float64,
-            shape=st.tuples(
-                st.integers(min_value=1, max_value=100),
-                st.integers(min_value=2, max_value=3),
-            ),
-        ),
-        point_size=st.floats(min_value=1, max_value=50, allow_nan=False),
-    )
-    @settings(max_examples=30, deadline=None)
-    def test_points_layer_data_integrity(self, points, point_size):
-        """Test that points layer data maintains integrity."""
-        mock_viewer = Mock()
-        mock_viewer.add_points = Mock(return_value=Mock())
-
-        # Property: Points data shape should be preserved
-        mock_viewer.add_points(points, size=point_size)
-
-        call_args = mock_viewer.add_points.call_args
-        assert call_args[0][0].shape == points.shape
-        assert call_args[1]["size"] == point_size
-
-    @given(
-        code_snippets=st.lists(
-            st.text(min_size=1, max_size=100), min_size=1, max_size=5
-        )
-    )
-    @settings(max_examples=20, deadline=None)
-    def test_code_execution_isolation(self, code_snippets):
-        """Test that code execution maintains isolated namespaces."""
-        _viewer = None
-        from napari_mcp.server import NapariMCPTools
-
-        _ = NapariMCPTools()  # Tools instance not used directly
-
-        # Property: Each execution should have isolated namespace
-        for i, code in enumerate(code_snippets):
-            # Only test valid Python variable assignments
-            var_name = f"test_var_{i}"
-            safe_code = f"{var_name} = {repr(code)}"
-
-            # Execute in isolated namespace
-            namespace = {}
-            try:
-                exec(safe_code, namespace)
-                assert var_name in namespace
-                assert namespace[var_name] == code
-            except Exception:
-                pass  # Skip invalid code
-
-    @given(
-        grid_enabled=st.booleans(),
-        ndisplay=st.integers(min_value=2, max_value=3),
-        axis_values=st.lists(
-            st.tuples(
-                st.integers(min_value=0, max_value=3),
-                st.integers(min_value=0, max_value=100),
-            ),
-            max_size=4,
-        ),
-    )
-    @settings(max_examples=30, deadline=None)
-    def test_viewer_state_consistency(self, grid_enabled, ndisplay, axis_values):
-        """Test that viewer state remains consistent after multiple operations."""
-        mock_viewer = Mock()
-        mock_viewer.grid = Mock(enabled=False)
-        mock_viewer.dims = Mock(ndisplay=2)
-        mock_viewer.dims.set_current_step = Mock()
-
-        # Apply state changes
-        mock_viewer.grid.enabled = grid_enabled
-        mock_viewer.dims.ndisplay = ndisplay
-
-        for axis, value in axis_values:
-            if axis < ndisplay:
-                mock_viewer.dims.set_current_step(axis, value)
-
-        # Properties to verify
-        assert mock_viewer.grid.enabled == grid_enabled
-        assert mock_viewer.dims.ndisplay == ndisplay
-        assert ndisplay in [2, 3]  # Valid display dimensions
-
-
-class TestPropertyBasedConcurrency:
-    """Property-based tests for concurrent operations."""
-
-    @given(
-        operation_count=st.integers(min_value=1, max_value=10),
-        operation_types=st.lists(
-            st.sampled_from(["add", "remove", "rename", "reorder"]),
-            min_size=1,
-            max_size=10,
-        ),
-    )
-    @settings(max_examples=20, deadline=None)
-    @pytest.mark.asyncio
-    async def test_concurrent_layer_operations(self, operation_count, operation_types):
-        """Test that concurrent layer operations maintain consistency."""
-        import asyncio
-
-        mock_viewer = Mock()
-        mock_viewer.layers = []
-
-        # Property: Concurrent operations should not corrupt layer state
-        async def perform_operation(op_type, index):
-            await asyncio.sleep(0.001)  # Simulate async operation
-            if op_type == "add" and len(mock_viewer.layers) < 20:
-                mock_viewer.layers.append(Mock(name=f"layer_{index}"))
-            elif op_type == "remove" and mock_viewer.layers:
-                mock_viewer.layers.pop(0)
-            # Other operations omitted for brevity
-
-        tasks = [
-            perform_operation(op_type, i)
-            for i, op_type in enumerate(operation_types[:operation_count])
-        ]
-
-        await asyncio.gather(*tasks)
-
-        # Verify consistency
-        layer_names = [
-            layer.name for layer in mock_viewer.layers if hasattr(layer, "name")
-        ]
-        assert len(layer_names) == len(set(layer_names))  # No duplicate names
-
-
-# Strategy definitions for complex data types
-image_strategy = arrays(
-    dtype=np.uint8,
-    shape=st.tuples(
-        st.integers(min_value=10, max_value=200),
-        st.integers(min_value=10, max_value=200),
-        st.just(3),  # RGB channels
-    ),
-)
-
-layer_property_strategy = st.fixed_dictionaries(
-    {
-        "visible": st.booleans(),
-        "opacity": st.floats(min_value=0.0, max_value=1.0),
-        "blending": st.sampled_from(["translucent", "additive", "opaque"]),
-        "colormap": st.sampled_from(["viridis", "magma", "gray", "turbo"]),
-    }
-)
-
-
-@given(image_data=image_strategy, properties=layer_property_strategy)
-@settings(max_examples=20, deadline=None)
-def test_complex_layer_creation(image_data, properties):
-    """Test complex layer creation with various properties."""
-    mock_viewer = Mock()
-    mock_viewer.add_image = Mock(return_value=Mock())
-
-    # Create layer with properties
-    _ = mock_viewer.add_image(image_data, **properties)  # Layer not used directly
-
-    # Verify call was made with correct arguments
-    mock_viewer.add_image.assert_called_once()
-    call_kwargs = mock_viewer.add_image.call_args[1]
-
-    for key, value in properties.items():
-        assert call_kwargs[key] == value
diff --git a/tests/test_qt_helpers.py b/tests/test_qt_helpers.py
new file mode 100644
index 0000000..d27af70
--- /dev/null
+++ b/tests/test_qt_helpers.py
@@ -0,0 +1,306 @@
+"""Tests for Qt helper functions: ensure_qt_app, process_events, signal handling."""
+
+import asyncio
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from napari_mcp import server as napari_mcp_server  # noqa: E402
+from napari_mcp.qt_helpers import (
+    connect_window_destroyed_signal,
+    ensure_qt_app,
+    process_events,
+    qt_event_pump,
+)
+
+
+def test_qt_app_creation(make_napari_viewer):
+    """Test Qt application creation and error handling."""
+    # Create a viewer to ensure Qt is initialized
+    viewer = make_napari_viewer()  # noqa: F841
+
+    # Test successful creation
+    app = ensure_qt_app(napari_mcp_server._state)
+    assert app is not None
+
+    # Test error handling in setQuitOnLastWindowClosed
+    with patch.dict(os.environ, {"TEST_QT_FAILURE": "1"}):
+        # Should not raise exception, just continue
+        app = ensure_qt_app(napari_mcp_server._state)
+        assert app is not None
+
+
+def test_process_events(make_napari_viewer):
+    """Test Qt event processing."""
+    # Create a viewer to ensure Qt is initialized
+    viewer = make_napari_viewer()  # noqa: F841
+
+    # Test with different cycle counts
+    process_events(napari_mcp_server._state, 1)
+    process_events(napari_mcp_server._state, 5)
+    process_events(napari_mcp_server._state, 0)  # Should default to 1
+
+
+def test_connect_window_destroyed_signal(make_napari_viewer):
+    """Test window destroyed signal connection."""
+    # Import the module-level variable
+    from napari_mcp import server as napari_mcp_server
+
+    # Reset the global flag first to ensure we test properly
+    original_flag = napari_mcp_server._state.window_close_connected
+    napari_mcp_server._state.window_close_connected = False
+
+    try:
+        # Create a real napari viewer
+        viewer = make_napari_viewer()  # noqa: F841
+
+        # Test connecting the signal (first time)
+        connect_window_destroyed_signal(napari_mcp_server._state, viewer)
+        assert napari_mcp_server._state.window_close_connected is True
+
+        # Test that it doesn't connect again
+        connect_window_destroyed_signal(napari_mcp_server._state, viewer)
+        assert napari_mcp_server._state.window_close_connected is True
+
+    finally:
+        # Restore original state
+        napari_mcp_server._state.window_close_connected = original_flag
+
+
+def test_window_close_connected_resets_on_destroy(make_napari_viewer):
+    """Test that _window_close_connected resets when the viewer is destroyed.
+
+    This guards against a regression where the flag stayed True after the
+    viewer window was destroyed, preventing signal reconnection on new viewers.
+    """
+    from napari_mcp import server as napari_mcp_server
+
+    original_flag = napari_mcp_server._state.window_close_connected
+    original_viewer = napari_mcp_server._state.viewer
+
+    try:
+        viewer = make_napari_viewer()
+        napari_mcp_server._state.window_close_connected = False
+        napari_mcp_server._state.viewer = viewer
+
+        # Connect the signal
+        connect_window_destroyed_signal(napari_mcp_server._state, viewer)
+        assert napari_mcp_server._state.window_close_connected is True
+
+        # Simulate closing the viewer (triggers destroyed signal indirectly)
+        # We can verify the callback logic by checking the code path:
+        # The _on_destroyed callback sets both _viewer=None and
+        # _window_close_connected=False. Verify this directly.
+        napari_mcp_server._state.viewer = None
+        napari_mcp_server._state.window_close_connected = False
+
+        # After destroy, reconnecting to a new viewer should work
+        viewer2 = make_napari_viewer()
+        napari_mcp_server._state.viewer = viewer2
+        connect_window_destroyed_signal(napari_mcp_server._state, viewer2)
+        # The key assertion: this should now succeed (was the bug)
+        assert napari_mcp_server._state.window_close_connected is True
+    finally:
+        napari_mcp_server._state.window_close_connected = original_flag
+        napari_mcp_server._state.viewer = original_viewer
+
+
+def test_on_destroyed_requests_shutdown(make_napari_viewer):
+    """Test that the _on_destroyed callback calls request_shutdown."""
+    from unittest.mock import patch as _patch
+
+    from napari_mcp import server as napari_mcp_server
+
+    viewer = make_napari_viewer()
+    napari_mcp_server._state.window_close_connected = False
+    napari_mcp_server._state.viewer = viewer
+    napari_mcp_server._state._shutdown_requested = False
+
+    connect_window_destroyed_signal(napari_mcp_server._state, viewer)
+
+    # Simulate the _on_destroyed callback by calling request_shutdown directly
+    # (actually triggering Qt destroyed signal requires closing the window,
+    # which is fragile in tests). Instead, verify the callback is wired by
+    # checking that viewer.close() triggers shutdown_requested.
+    with _patch.object(napari_mcp_server._state, "request_shutdown") as mock_shutdown:
+        # Close the viewer, which should trigger the destroyed signal
+        try:
+            viewer.close()
+        except Exception:
+            pass
+        # The destroyed signal may fire asynchronously; process events
+        try:
+            process_events(napari_mcp_server._state, 5)
+        except Exception:
+            pass
+        # If the Qt signal fired, request_shutdown was called
+        if mock_shutdown.called:
+            mock_shutdown.assert_called_once()
+
+
+@pytest.mark.asyncio
+async def test_close_viewer_requests_shutdown(make_napari_viewer):
+    """Test that close_viewer tool triggers request_shutdown."""
+    from napari_mcp import server as napari_mcp_server
+
+    viewer = make_napari_viewer()
+    napari_mcp_server._state.viewer = viewer
+
+    result = await napari_mcp_server.close_viewer()
+    assert result["status"] == "closed"
+    assert napari_mcp_server._state._shutdown_requested is True
+
+
+@pytest.mark.asyncio
+async def test_qt_event_pump(make_napari_viewer):
+    """Test Qt event pump behavior."""
+    # Create a viewer to ensure Qt is initialized
+    viewer = make_napari_viewer()  # noqa: F841
+
+    # Test that event pump can be created and runs
+    task = asyncio.create_task(qt_event_pump(napari_mcp_server._state))
+
+    # Let it run briefly then cancel
+    await asyncio.sleep(0.01)
+    task.cancel()
+
+    # Should handle cancellation gracefully
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass  # Expected
+
+
+@pytest.mark.asyncio
+async def test_gui_control_functions(make_napari_viewer):
+    """Test GUI lifecycle handled implicitly."""
+    # Create a viewer to ensure Qt is initialized
+    viewer = make_napari_viewer()
+    from napari_mcp import server as napari_mcp_server
+
+    napari_mcp_server._state.viewer = viewer
+
+    # init_viewer starts the GUI pump
+    result = await napari_mcp_server.init_viewer()
+    assert result["status"] == "ok"
+
+    # Close viewer stops the GUI pump
+    result = await napari_mcp_server.close_viewer()
+    assert result["status"] == "closed"
+
+
+@pytest.mark.asyncio
+@patch("asyncio.create_subprocess_exec")
+async def test_install_packages(mock_create_subprocess, make_napari_viewer):
+    """Test package installation function."""
+    from unittest.mock import AsyncMock
+
+    # Mock the subprocess properly
+    mock_process = AsyncMock()
+    mock_process.returncode = 0
+    mock_process.communicate.return_value = (
+        b"Successfully installed test-package",
+        b"",
+    )
+    mock_create_subprocess.return_value = mock_process
+
+    result = await napari_mcp_server.install_packages(packages=["test-package"])
+    assert result["status"] == "ok"
+    assert "test-package" in result["stdout"]
+
+    # Test failed installation
+    mock_process.returncode = 1
+    mock_process.communicate.return_value = (b"", b"Package not found")
+
+    result = await napari_mcp_server.install_packages(packages=["bad-package"])
+    assert result["status"] == "error"
+    assert "Package not found" in result["stderr"]
+
+
+@pytest.mark.asyncio
+async def test_error_recovery(make_napari_viewer):
+    """Test error recovery in various scenarios."""
+    from napari_mcp import server as napari_mcp_server
+
+    # Create viewer
+    viewer = make_napari_viewer()
+    napari_mcp_server._state.viewer = viewer
+
+    # Test with real viewer - should work normally
+    connect_window_destroyed_signal(napari_mcp_server._state, viewer)
+
+    # Test with mock viewer that has no window attribute - should not crash
+    mock_viewer = MagicMock(spec=[])  # No window attribute
+    connect_window_destroyed_signal(
+        napari_mcp_server._state, mock_viewer
+    )  # Should not crash
+
+
+def test_qt_app_singleton(make_napari_viewer):
+    """Test Qt application singleton behavior."""
+    from napari_mcp.qt_helpers import ensure_qt_app as _ensure_qt_app
+
+    app1 = _ensure_qt_app(napari_mcp_server._state)
+    app2 = _ensure_qt_app(napari_mcp_server._state)
+    assert app1 is app2
+
+
+@pytest.mark.asyncio
+@patch("asyncio.create_subprocess_exec")
+async def test_install_packages_with_flags(mock_create_subprocess, make_napari_viewer):
+    """Test install_packages passes optional pip flags to subprocess."""
+    from unittest.mock import AsyncMock
+
+    mock_process = AsyncMock()
+    mock_process.returncode = 0
+    mock_process.communicate.return_value = (b"Success", b"")
+    mock_create_subprocess.return_value = mock_process
+
+    result = await napari_mcp_server.install_packages(
+        packages=["some-package"],
+        upgrade=True,
+        no_deps=True,
+        pre=True,
+        index_url="https://example.com/simple",
+        extra_index_url="https://extra.example.com/simple",
+    )
+    assert result["status"] == "ok"
+
+    # Verify the subprocess was called with the right flags
+    call_args = mock_create_subprocess.call_args
+    cmd_args = call_args[0]  # positional args to create_subprocess_exec
+    cmd_str = " ".join(str(a) for a in cmd_args)
+    assert "--upgrade" in cmd_str
+    assert "--no-deps" in cmd_str
+    assert "--pre" in cmd_str
+    assert "https://example.com/simple" in cmd_str
+    assert "https://extra.example.com/simple" in cmd_str
+    assert "some-package" in cmd_str
+
+
+@pytest.mark.asyncio
+async def test_proxy_disabled_during_tests():
+    """Guard: external proxy must be disabled in tests to ensure isolation.
+
+    If this test fails, the conftest fixture that sets STANDALONE mode
+    is broken, and other tests may silently talk to a running bridge server.
+    """
+    from napari_mcp import server as napari_mcp_server
+    from napari_mcp.state import StartupMode
+
+    # Verify state is in STANDALONE mode
+    assert napari_mcp_server._state.mode == StartupMode.STANDALONE, (
+        "Server state should be STANDALONE during tests."
+    )
+
+    result = await napari_mcp_server._state.proxy_to_external("list_layers")
+    assert result is None, (
+        "proxy_to_external should return None during tests (STANDALONE mode). "
+        "If this fails, tests may be proxying to a live external viewer."
+    )
+
+    found, info = await napari_mcp_server._state.detect_external_viewer()
+    assert found is False and info is None, (
+        "detect_external_viewer should return (False, None) during tests."
+    )
diff --git a/tests/test_server_tools.py b/tests/test_server_tools.py
new file mode 100644
index 0000000..ef4a5ef
--- /dev/null
+++ b/tests/test_server_tools.py
@@ -0,0 +1,1087 @@
+"""Unit tests for all 16 MCP tools exposed by the server.
+
+Organised by tool name. Each class covers happy paths, edge cases,
+error handling, and input validation for one tool.
+"""
+
+import tempfile
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+import imageio.v3 as iio
+import numpy as np
+import pytest
+
+from napari_mcp import server as s
+from napari_mcp.state import StartupMode
+
+# Shortcut: every test that needs a viewer uses this pattern.
+pytestmark = pytest.mark.asyncio
+
+
+# ── helpers ────────────────────────────────────────────────────────────────
+
+
+def _viewer(make_napari_viewer):
+    """Create viewer and wire it into server state."""
+    v = make_napari_viewer()
+    s._state.viewer = v
+    return v
+
+
+# ── init_viewer ────────────────────────────────────────────────────────────
+
+
+class TestInitViewer:
+    async def test_basic(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.init_viewer(title="T", width=640, height=480)
+        assert res["status"] == "ok"
+        assert res["title"] == "T"
+        assert isinstance(res["layers"], list)
+
+    async def test_detect_only_with_viewer(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        res = await s.init_viewer(detect_only=True)
+        assert res["status"] == "ok"
+        assert res["viewers"]["local"]["available"] is True
+        assert res["viewers"]["local"]["title"] == v.title
+        assert res["viewers"]["external"]["available"] is False
+
+    async def test_detect_only_no_viewer(self):
+        s._state.viewer = None
+        res = await s.init_viewer(detect_only=True)
+        assert res["viewers"]["local"]["type"] == "not_initialized"
+
+    async def test_invalid_port_does_not_crash(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.init_viewer(port="not_a_number")
+        assert res["status"] == "ok"
+
+    async def test_auto_detect_fallback(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        s._state.mode = StartupMode.AUTO_DETECT
+        with patch.object(
+            s._state,
+            "external_session_information",
+            new_callable=AsyncMock,
+            side_effect=ConnectionError,
+        ):
+            res = await s.init_viewer()
+        assert res["status"] == "ok"
+        assert res["viewer_type"] == "local"
+
+
+# ── close_viewer ───────────────────────────────────────────────────────────
+
+
+class TestCloseViewer:
+    async def test_close_then_close_again(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.close_viewer())["status"] == "closed"
+        assert (await s.close_viewer())["status"] == "no_viewer"
+
+
+# ── session_information ────────────────────────────────────────────────────
+
+
+class TestSessionInformation:
+    async def test_with_layers(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        v.add_points(np.array([[1, 1]]), name="pts")
+        await s.set_layer_properties("pts", active=True)
+
+        res = await s.session_information()
+        assert res["status"] == "ok"
+        assert res["viewer"]["n_layers"] == 2
+        assert "pts" in res["viewer"]["selected_layers"]
+        assert "system" in res
+        assert len(res["layers"]) == 2
+
+    async def test_no_viewer(self):
+        s._state.viewer = None
+        res = await s.session_information()
+        assert res["status"] == "ok"
+        assert res["viewer"] is None
+
+    async def test_auto_detect_fallback(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        s._state.mode = StartupMode.AUTO_DETECT
+        with patch.object(
+            s._state,
+            "external_session_information",
+            new_callable=AsyncMock,
+            side_effect=ConnectionError,
+        ):
+            res = await s.session_information()
+        assert res["session_type"] == "napari_mcp_standalone_session"
+
+
+# ── list_layers ────────────────────────────────────────────────────────────
+
+
+class TestListLayers:
+    async def test_returns_properties(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        await s.set_layer_properties("img", opacity=0.3, visible=False)
+
+        layers = await s.list_layers()
+        lyr = next(entry for entry in layers if entry["name"] == "img")
+        assert lyr["opacity"] == pytest.approx(0.3)
+        assert lyr["visible"] is False
+        assert lyr["type"] == "Image"
+
+    async def test_empty(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert await s.list_layers() == []
+
+    async def test_proxy_list(self):
+        s._state.mode = StartupMode.AUTO_DETECT
+        mock = [{"name": "x"}]
+        with patch.object(
+            s._state, "proxy_to_external", new_callable=AsyncMock, return_value=mock
+        ):
+            assert await s.list_layers() == mock
+
+    async def test_proxy_dict_with_content(self):
+        s._state.mode = StartupMode.AUTO_DETECT
+        inner = [{"name": "x"}]
+        with patch.object(
+            s._state,
+            "proxy_to_external",
+            new_callable=AsyncMock,
+            return_value={"content": inner},
+        ):
+            assert await s.list_layers() == inner
+
+    async def test_proxy_bad_format(self):
+        s._state.mode = StartupMode.AUTO_DETECT
+        with patch.object(
+            s._state,
+            "proxy_to_external",
+            new_callable=AsyncMock,
+            return_value={"content": "bad"},
+        ):
+            assert await s.list_layers() == []
+        with patch.object(
+            s._state,
+            "proxy_to_external",
+            new_callable=AsyncMock,
+            return_value={"error": "x"},
+        ):
+            assert await s.list_layers() == []
+
+
+# ── get_layer ──────────────────────────────────────────────────────────────
+
+
+class TestGetLayer:
+    # -- metadata (include_data=False) --
+
+    async def test_image_metadata(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(
+            np.zeros((10, 20), dtype=np.uint8),
+            name="img",
+            scale=[2.0, 3.0],
+            translate=[10.0, 20.0],
+        )
+        res = await s.get_layer("img")
+        assert res["status"] == "ok"
+        assert res["type"] == "Image"
+        assert res["data_shape"] == [10, 20]
+        assert res["data_dtype"] == "uint8"
+        assert res["ndim"] == 2
+        assert res["scale"] == [2.0, 3.0]
+        assert res["translate"] == [10.0, 20.0]
+        assert "colormap" in res and "gamma" in res
+        assert "statistics" not in res  # not requested
+
+    async def test_labels_metadata(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_labels(np.array([[0, 1], [2, 0]], dtype=np.int32), name="seg")
+        res = await s.get_layer("seg")
+        assert res["type"] == "Labels"
+        assert res["n_labels"] == 2
+
+    async def test_points_metadata(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_points(np.array([[1.0, 2.0], [3.0, 4.0]]), name="pts")
+        res = await s.get_layer("pts")
+        assert res["n_points"] == 2
+        assert "point_size" in res
+        assert "coordinates" not in res  # not requested
+
+    async def test_not_found(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.get_layer("nope"))["status"] == "not_found"
+
+    # -- data (include_data=True / slicing) --
+
+    async def test_image_statistics(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.array([[10, 20], [30, 40]], dtype=np.float32), name="img")
+        res = await s.get_layer("img", include_data=True)
+        st = res["statistics"]
+        assert st["min"] == 10.0 and st["max"] == 40.0 and st["mean"] == 25.0
+
+    async def test_image_slicing(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.arange(60).reshape(3, 4, 5).astype(np.float32), name="vol")
+        res = await s.get_layer("vol", slicing="0, :2, :2")
+        assert res["slice_shape"] == [2, 2]
+        assert res["data"] == [[0, 1], [5, 6]]
+        assert "statistics" in res  # slicing implies include_data
+
+    async def test_invalid_slicing(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.get_layer("img", slicing="bad")
+        assert "slice_error" in res
+
+    async def test_points_data(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_points(np.array([[1.0, 2.0], [3.0, 4.0]]), name="pts")
+        res = await s.get_layer("pts", include_data=True)
+        assert res["coordinates"] == [[1.0, 2.0], [3.0, 4.0]]
+        assert "statistics" in res
+
+    async def test_large_data_stores_output(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((100, 100), dtype=np.uint8), name="big")
+        res = await s.get_layer("big", slicing=":50, :50", max_elements=10)
+        assert "output_id" in res
+        assert "message" in res
+
+    async def test_labels_statistics(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_labels(np.array([[0, 1], [2, 3]], dtype=np.int32), name="seg")
+        res = await s.get_layer("seg", include_data=True)
+        assert res["data_dtype"] == "int32"
+        assert "statistics" in res
+
+    async def test_max_elements_minus_one_means_unlimited(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_points(np.random.rand(50, 2), name="pts")
+        res = await s.get_layer("pts", include_data=True, max_elements=-1)
+        assert "coordinates" in res  # inline, not output_id
+        assert len(res["coordinates"]) == 50
+
+
+# ── add_layer ──────────────────────────────────────────────────────────────
+
+
+class TestAddLayer:
+    # -- per-type happy paths --
+
+    async def test_image_from_path(self, make_napari_viewer, tmp_path):
+        _viewer(make_napari_viewer)
+        p = tmp_path / "img.tif"
+        iio.imwrite(p, np.zeros((8, 8), dtype=np.uint8))
+        res = await s.add_layer("image", path=str(p), name="img", colormap="magma")
+        assert res["status"] == "ok"
+        assert res["name"] == "img"
+        assert res["shape"] == [8, 8]
+
+    async def test_image_from_data_var(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        await s.execute_code("arr = np.zeros((4, 4), dtype=np.uint8)")
+        res = await s.add_layer("image", data_var="arr")
+        assert res["status"] == "ok"
+        assert res["name"] == "arr"
+
+    async def test_labels_from_path(self, make_napari_viewer, tmp_path):
+        _viewer(make_napari_viewer)
+        p = tmp_path / "lbl.tif"
+        iio.imwrite(p, np.array([[0, 1], [2, 0]], dtype=np.uint8))
+        res = await s.add_layer("labels", path=str(p), name="lbl")
+        assert res["status"] == "ok" and res["shape"] == [2, 2]
+
+    async def test_labels_from_data_var(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        await s.execute_code("lbl = np.array([[0,1],[2,0]], dtype=np.int32)")
+        res = await s.add_layer("labels", data_var="lbl")
+        assert res["status"] == "ok"
+
+    async def test_points_inline(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.add_layer("points", data=[[1, 2], [3, 4]], name="pts", size=5)
+        assert res["status"] == "ok" and res["n_points"] == 2
+
+    async def test_shapes_inline(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        rect = [[0, 0], [0, 10], [10, 10], [10, 0]]
+        res = await s.add_layer("shapes", data=[rect], name="r", edge_color="red")
+        assert res["status"] == "ok" and res["nshapes"] == 1
+
+    async def test_vectors_inline(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.add_layer("vectors", data=[[[0, 0], [1, 1]]], name="v")
+        assert res["status"] == "ok" and res["n_vectors"] == 1
+
+    async def test_tracks_inline(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        data = [[0, 0, 10, 10], [0, 1, 11, 11], [1, 0, 20, 20], [1, 1, 21, 21]]
+        res = await s.add_layer("tracks", data=data, name="t")
+        assert res["status"] == "ok" and res["n_tracks"] == 2
+
+    async def test_surface_from_data_var(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        await s.execute_code(
+            "verts = np.array([[0,0,0],[1,0,0],[0,1,0]])\n"
+            "faces = np.array([[0,1,2]])\n"
+            "surf = (verts, faces)"
+        )
+        res = await s.add_layer("surface", data_var="surf", name="s")
+        assert res["status"] == "ok"
+        assert res["n_vertices"] == 3 and res["n_faces"] == 1
+
+    # -- type normalization --
+
+    async def test_singular_plural_case(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.add_layer("point", data=[[1, 2]]))["status"] == "ok"
+        assert (await s.add_layer("Points", data=[[3, 4]]))["status"] == "ok"
+        assert (await s.add_layer("IMAGE", data_var=None))["status"] == "error"
+
+    async def test_whitespace_in_type(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.add_layer(" image ", data_var=None))[
+            "status"
+        ] == "error"  # no data, but type accepted
+        # With data it works
+        await s.execute_code("ws_img = np.zeros((3,3), dtype=np.uint8)")
+        assert (await s.add_layer("  points  ", data=[[1, 2]]))["status"] == "ok"
+
+    # -- error paths --
+
+    async def test_unknown_type(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.add_layer("bogus", data=[[1]])
+        assert res["status"] == "error" and "Unknown" in res["message"]
+
+    async def test_no_data_source(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.add_layer("image"))["status"] == "error"
+        assert (await s.add_layer("points"))["status"] == "error"
+        assert (await s.add_layer("surface"))["status"] == "error"
+
+    async def test_data_var_not_found(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.add_layer("image", data_var="nope")
+        assert res["status"] == "error" and "not found" in res["message"]
+
+    async def test_bad_image_path(self, make_napari_viewer, tmp_path):
+        _viewer(make_napari_viewer)
+        bad = tmp_path / "bad.tif"
+        bad.write_text("not an image")
+        res = await s.add_layer("image", path=str(bad))
+        assert res["status"] == "error"
+
+    async def test_bad_labels_path(self, make_napari_viewer, tmp_path):
+        _viewer(make_napari_viewer)
+        bad = tmp_path / "bad.txt"
+        bad.write_text("not an image")
+        res = await s.add_layer("labels", path=str(bad))
+        assert res["status"] == "error" and "Failed to add" in res["message"]
+
+    async def test_path_unsupported_for_non_image_type(
+        self, make_napari_viewer, tmp_path
+    ):
+        _viewer(make_napari_viewer)
+        p = tmp_path / "x.tif"
+        iio.imwrite(p, np.zeros((5, 5), dtype=np.uint8))
+        res = await s.add_layer("points", path=str(p))
+        assert res["status"] == "error" and "only supported" in res["message"]
+
+
+# ── remove_layer ───────────────────────────────────────────────────────────
+
+
+class TestRemoveLayer:
+    async def test_remove_existing(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="x")
+        assert (await s.remove_layer("x"))["status"] == "removed"
+        assert len(v.layers) == 0
+
+    async def test_remove_not_found(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.remove_layer("nope"))["status"] == "not_found"
+
+
+# ── set_layer_properties ──────────────────────────────────────────────────
+
+
+class TestSetLayerProperties:
+    async def test_all_properties(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.set_layer_properties(
+            "img",
+            visible=False,
+            opacity=0.3,
+            colormap="magma",
+            blending="additive",
+            contrast_limits=[10, 200],
+            gamma=2.0,
+        )
+        assert res["status"] == "ok"
+        assert v.layers["img"].visible is False
+        assert v.layers["img"].opacity == pytest.approx(0.3)
+        assert v.layers["img"].gamma == pytest.approx(2.0)
+
+    async def test_rename(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="old")
+        res = await s.set_layer_properties("old", new_name="new")
+        assert res["name"] == "new"
+        assert "new" in v.layers
+
+    async def test_active(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="a")
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="b")
+        await s.set_layer_properties("b", active=True)
+        assert v.layers["b"] in v.layers.selection
+
+    async def test_not_found(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.set_layer_properties("nope", visible=False))[
+            "status"
+        ] == "not_found"
+
+    async def test_malformed_contrast_limits(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        # Too short — now returns error
+        assert (await s.set_layer_properties("img", contrast_limits=[1]))[
+            "status"
+        ] == "error"
+        # Non-numeric — returns error
+        assert (await s.set_layer_properties("img", contrast_limits=["a", "b"]))[
+            "status"
+        ] == "error"
+
+    async def test_opacity_out_of_range(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.set_layer_properties("img", opacity=-0.5)
+        assert res["status"] == "error" and "opacity" in res["message"]
+        res = await s.set_layer_properties("img", opacity=5.0)
+        assert res["status"] == "error" and "opacity" in res["message"]
+
+    async def test_gamma_zero(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.set_layer_properties("img", gamma=0)
+        assert res["status"] == "error" and "gamma" in res["message"]
+
+    async def test_invalid_colormap(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.set_layer_properties("img", colormap="nonexistent_xyz")
+        assert res["status"] == "error" and "colormap" in res["message"].lower()
+
+    async def test_invalid_blending(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.set_layer_properties("img", blending="invalid_blend")
+        assert res["status"] == "error" and "blending" in res["message"].lower()
+
+
+# ── reorder_layer ─────────────────────────────────────────────────────────
+
+
+class TestReorderLayer:
+    async def test_by_index(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        for n in ("a", "b", "c"):
+            v.add_points(np.array([[0, 0]]), name=n)
+        res = await s.reorder_layer("c", index=0)
+        assert res["status"] == "ok" and res["index"] == 0
+
+    async def test_before_after(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        for n in ("a", "b", "c"):
+            v.add_points(np.array([[0, 0]]), name=n)
+        assert (await s.reorder_layer("a", after="b"))["status"] == "ok"
+        assert (await s.reorder_layer("a", before="c"))["status"] == "ok"
+
+    async def test_not_found(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.reorder_layer("nope", index=0))["status"] == "not_found"
+
+    async def test_no_target(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_points(np.array([[0, 0]]), name="a")
+        res = await s.reorder_layer("a")
+        assert res["status"] == "error" and "exactly one" in res["message"]
+
+    async def test_multiple_targets(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_points(np.array([[0, 0]]), name="a")
+        v.add_points(np.array([[0, 0]]), name="b")
+        res = await s.reorder_layer("a", index=0, before="b")
+        assert res["status"] == "error"
+
+    async def test_before_not_found(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_points(np.array([[0, 0]]), name="a")
+        assert (await s.reorder_layer("a", before="nope"))["status"] == "not_found"
+
+
+# ── apply_to_layers ───────────────────────────────────────────────────────
+
+
+class TestApplyToLayers:
+    async def test_by_type(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img1")
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img2")
+        v.add_points(np.array([[1, 1]]), name="pts")
+        res = await s.apply_to_layers(
+            filter_type="Image", properties={"visible": False}
+        )
+        assert res["count"] == 2
+        assert v.layers["img1"].visible is False
+        assert v.layers["pts"].visible is True
+
+    async def test_by_pattern(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="seg_a")
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="raw")
+        res = await s.apply_to_layers(
+            filter_pattern="seg_*", properties={"opacity": 0.5}
+        )
+        assert res["count"] == 1
+        assert v.layers["seg_a"].opacity == pytest.approx(0.5)
+        assert v.layers["raw"].opacity == pytest.approx(1.0)
+
+    async def test_no_match(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.apply_to_layers(
+            filter_type="Labels", properties={"visible": False}
+        )
+        assert res["count"] == 0
+
+    async def test_no_properties(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.apply_to_layers(filter_type="Image"))["status"] == "error"
+
+    async def test_colormap_on_labels_no_crash(self, make_napari_viewer):
+        """Setting colormap='viridis' on Labels should not crash with raw KeyError."""
+        v = _viewer(make_napari_viewer)
+        v.add_labels(np.array([[0, 1], [2, 0]], dtype=np.int32), name="seg")
+        # This used to raise KeyError: 'colors'
+        res = await s.apply_to_layers(
+            filter_type="Labels", properties={"colormap": "viridis"}
+        )
+        # Should either succeed or report count (error is swallowed per-layer)
+        assert res["status"] == "ok"
+
+    async def test_invalid_opacity_no_crash(self, make_napari_viewer):
+        """Out-of-range opacity on batch op should not crash."""
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.apply_to_layers(filter_type="Image", properties={"opacity": -5.0})
+        assert res["status"] == "ok"  # -5 skipped silently, layer matched
+
+
+# ── configure_viewer ──────────────────────────────────────────────────────
+
+
+class TestConfigureViewer:
+    async def test_camera(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.configure_viewer(
+            center=[10, 10], zoom=2.0, angles=[45.0, 0.0, 0.0]
+        )
+        assert res["status"] == "ok"
+        assert res["zoom"] == pytest.approx(2.0)
+        assert isinstance(res["angles"], list)
+
+    async def test_reset_view(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.configure_viewer(reset_view=True)
+        assert res["status"] == "ok"
+
+    async def test_ndisplay(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.configure_viewer(ndisplay=3)
+        assert res["ndisplay"] == 3
+
+    async def test_dims(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10, 10)))
+        res = await s.configure_viewer(dims_axis=0, dims_value=5)
+        assert res["value"] == 5
+
+    async def test_dims_clamped(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10, 10)))
+        res = await s.configure_viewer(dims_axis=0, dims_value=99999)
+        assert res["value"] == 9 and "warning" in res
+
+    async def test_dims_negative_clamps_to_zero(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10, 10)))
+        res = await s.configure_viewer(dims_axis=0, dims_value=-5)
+        assert res["value"] == 0 and "warning" in res
+
+    async def test_grid(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.configure_viewer(grid=True))["grid"] is True
+        assert (await s.configure_viewer(grid=False))["grid"] is False
+
+    async def test_combined(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.configure_viewer(zoom=1.5, ndisplay=2, grid=True)
+        assert res["zoom"] == pytest.approx(1.5)
+        assert res["ndisplay"] == 2
+        assert res["grid"] is True
+
+    # -- validation --
+
+    async def test_zoom_zero(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.configure_viewer(zoom=0)
+        assert res["status"] == "error" and "zoom" in res["message"]
+
+    async def test_zoom_negative(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.configure_viewer(zoom=-1))["status"] == "error"
+
+    async def test_zoom_string_zero(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.configure_viewer(zoom="0"))["status"] == "error"
+
+    async def test_zoom_validation_no_mutation(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        await s.configure_viewer(center=[0, 0], zoom=1.0)
+        original = list(s._state.viewer.camera.center)
+        await s.configure_viewer(center=[999, 999], zoom=0)
+        assert list(s._state.viewer.camera.center) == original
+
+    async def test_ndisplay_invalid(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        assert (await s.configure_viewer(ndisplay=5))["status"] == "error"
+        assert (await s.configure_viewer(ndisplay=0))["status"] == "error"
+
+    async def test_dims_axis_out_of_range(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10, 10)))
+        assert (await s.configure_viewer(dims_axis=99, dims_value=0))[
+            "status"
+        ] == "error"
+
+    async def test_dims_axis_negative(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10, 10)))
+        assert (await s.configure_viewer(dims_axis=-1, dims_value=0))[
+            "status"
+        ] == "error"
+
+    async def test_dims_axis_without_value(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10, 10)))
+        res = await s.configure_viewer(dims_axis=0)
+        assert res["status"] == "error" and "together" in res["message"]
+
+    async def test_dims_value_without_axis(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10, 10)))
+        res = await s.configure_viewer(dims_value=5)
+        assert res["status"] == "error" and "together" in res["message"]
+
+
+# ── save_layer_data ───────────────────────────────────────────────────────
+
+
+class TestSaveLayerData:
+    async def test_npy(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.ones((5, 5), dtype=np.uint8) * 42, name="img")
+        out = tmp_path / "img.npy"
+        res = await s.save_layer_data("img", str(out))
+        assert res["status"] == "ok" and res["format"] == "npy"
+        assert np.load(str(out))[0, 0] == 42
+
+    async def test_tiff(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10), dtype=np.uint8), name="img")
+        res = await s.save_layer_data("img", str(tmp_path / "img.tiff"))
+        assert res["status"] == "ok" and Path(res["path"]).exists()
+
+    async def test_csv_points(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_points(np.array([[1.0, 2.0], [3.0, 4.0]]), name="pts")
+        out = tmp_path / "pts.csv"
+        res = await s.save_layer_data("pts", str(out))
+        assert res["status"] == "ok"
+        # Verify header row
+        lines = out.read_text().strip().splitlines()
+        assert lines[0] == "axis-0,axis-1"
+        # Data still loads correctly (skiprows=1 for header)
+        loaded = np.loadtxt(str(out), delimiter=",", skiprows=1)
+        assert loaded.shape == (2, 2)
+
+    async def test_format_override(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        out = tmp_path / "img.dat"  # unusual extension
+        res = await s.save_layer_data("img", str(out), format="npy")
+        assert res["status"] == "ok"
+
+    async def test_not_found(self, make_napari_viewer, tmp_path):
+        _viewer(make_napari_viewer)
+        assert (await s.save_layer_data("nope", str(tmp_path / "x.npy")))[
+            "status"
+        ] == "not_found"
+
+
+# ── screenshot ─────────────────────────────────────────────────────────────
+
+
+class TestScreenshot:
+    async def test_returns_image_content(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10), dtype=np.uint8))
+        res = await s.screenshot()
+        assert hasattr(res, "mimeType")  # ImageContent
+        assert str(res.mimeType).lower() in ("png", "image/png")
+
+    async def test_save_to_file(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10), dtype=np.uint8))
+        out = tmp_path / "shot.png"
+        res = await s.screenshot(save_path=str(out))
+        assert res["status"] == "ok"
+        assert Path(res["path"]).exists()
+        assert res["size"][0] > 0
+
+    async def test_timelapse_requires_both(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.screenshot(axis=0)
+        assert res["status"] == "error" and "slice_range" in res["message"]
+        res = await s.screenshot(slice_range=":")
+        assert res["status"] == "error" and "axis" in res["message"]
+
+    async def test_proxy(self):
+        s._state.mode = StartupMode.AUTO_DETECT
+        sentinel = {"type": "image", "data": "x"}
+        with patch.object(
+            s._state, "proxy_to_external", new_callable=AsyncMock, return_value=sentinel
+        ):
+            assert (await s.screenshot()) is sentinel
+
+    async def test_inline_auto_downscale(self, make_napari_viewer):
+        """Inline screenshots are auto-downscaled to stay under ~200KB base64."""
+        import base64
+
+        v = _viewer(make_napari_viewer)
+        # Large image that would produce a big screenshot
+        v.add_image(np.random.randint(0, 255, (512, 512, 3), dtype=np.uint8))
+        res = await s.screenshot()
+        assert hasattr(res, "data")
+        raw = base64.b64decode(res.data)
+        # Should be under 200KB after auto-downscale
+        assert len(raw) <= 200_000
+
+    async def test_different_dtypes(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+            img = (np.random.rand(20, 20, 3) * 255).astype(np.uint8)
+            iio.imwrite(f.name, img)
+            await s.add_layer("image", path=f.name, name="test_float")
+        res = await s.screenshot()
+        assert hasattr(res, "data")
+
+
+# ── execute_code ──────────────────────────────────────────────────────────
+
+
+class TestExecuteCode:
+    async def test_expression(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code("1 + 2")
+        assert res["status"] == "ok" and res["result_repr"] == "3"
+
+    async def test_namespace_persistence(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        await s.execute_code("x = 42")
+        res = await s.execute_code("x * 2")
+        assert res["result_repr"] == "84"
+
+    async def test_viewer_available(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code(
+            "viewer.add_image(np.ones((5,5)), name='gen')\nlen(viewer.layers)"
+        )
+        assert res["status"] == "ok" and res["result_repr"] == "1"
+
+    async def test_syntax_error(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code("invalid syntax !!!")
+        assert res["status"] == "error" and res["stderr"]
+
+    async def test_runtime_error(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code("raise ValueError('boom')")
+        assert res["status"] == "error" and "boom" in res["stderr"]
+
+    async def test_stdout_stderr(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code(
+            "import sys; print('out'); print('err', file=sys.stderr)"
+        )
+        assert "out" in res["stdout"] and "err" in res["stderr"]
+
+    async def test_truncation(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code("for i in range(100): print(i)", line_limit=5)
+        assert res.get("truncated") is True
+        assert "output_id" in res
+
+    async def test_unlimited_output(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code("print('hello')", line_limit=-1)
+        assert "warning" in res and "large number of tokens" in res["warning"]
+
+    async def test_exception_handling_in_code(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code(
+            "try:\n x=1/0\nexcept ZeroDivisionError:\n result='caught'\nresult"
+        )
+        assert res["status"] == "ok" and "caught" in res["result_repr"]
+
+
+# ── Bug fix regression tests ──────────────────────────────────────────────
+
+
+class TestBugFixRegressions:
+    """Tests guarding specific bug fixes identified in test rounds."""
+
+    # Bug 5: contrast_limits invalid shapes
+    async def test_contrast_limits_empty_list(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.set_layer_properties("img", contrast_limits=[])
+        assert res["status"] == "error"
+        assert "contrast_limits" in res["message"]
+
+    async def test_contrast_limits_single_value(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.set_layer_properties("img", contrast_limits=[100])
+        assert res["status"] == "error"
+
+    async def test_contrast_limits_three_values(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.set_layer_properties("img", contrast_limits=[10, 50, 200])
+        assert res["status"] == "error"
+
+    async def test_contrast_limits_valid(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.set_layer_properties("img", contrast_limits=[0, 100])
+        assert res["status"] == "ok"
+
+    # Bug 8: data + data_var conflict
+    async def test_data_and_data_var_conflict(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.add_layer("image", data=[[1, 2], [3, 4]], data_var="x")
+        assert res["status"] == "error"
+        assert (
+            "only ONE" in res["message"].upper() or "only one" in res["message"].lower()
+        )
+
+    async def test_path_and_data_conflict(self, make_napari_viewer, tmp_path):
+        _viewer(make_napari_viewer)
+        res = await s.add_layer("image", path=str(tmp_path / "img.tif"), data=[[1, 2]])
+        assert res["status"] == "error"
+
+    # Bug 10: unknown extension
+    async def test_save_unknown_extension(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.save_layer_data("img", str(tmp_path / "out.xyz"))
+        assert res["status"] == "error"
+        assert "Unsupported" in res["message"]
+
+    # Bug 11: format/type mismatch
+    async def test_save_points_as_tiff(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_points(np.array([[0.0, 0.0], [1.0, 1.0]]), name="pts")
+        res = await s.save_layer_data("pts", str(tmp_path / "pts.tiff"))
+        assert res["status"] == "error"
+        assert "Image/Labels" in res["message"]
+
+    async def test_save_image_as_csv(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.save_layer_data("img", str(tmp_path / "img.csv"))
+        assert res["status"] == "error"
+        assert "Points/Tracks/Vectors" in res["message"]
+
+    # Bug 12: unknown property keys
+    async def test_apply_unknown_properties(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.apply_to_layers(
+            properties={"visible": True, "nonexistent_key": 42}
+        )
+        assert res["status"] == "ok"
+        assert "unknown_properties" in res
+        assert "nonexistent_key" in res["unknown_properties"]
+
+    # Bug 14: nonexistent file path
+    async def test_add_layer_nonexistent_path(self, make_napari_viewer, tmp_path):
+        _viewer(make_napari_viewer)
+        res = await s.add_layer("image", path=str(tmp_path / "does_not_exist.tif"))
+        assert res["status"] == "error"
+        assert "not found" in res["message"].lower()
+
+
+# ── _parse_numpy_slicing (indirect via get_layer) ────────────────────────
+
+
+class TestParseNumpySlicing:
+    """Test _parse_numpy_slicing indirectly through get_layer with slicing."""
+
+    async def test_single_index(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        data = np.arange(60).reshape(3, 4, 5).astype(np.float32)
+        v.add_image(data, name="vol")
+        res = await s.get_layer("vol", slicing="1")
+        assert res["status"] == "ok"
+        assert res["slice_shape"] == [4, 5]
+
+    async def test_slice_with_step(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        data = np.arange(20).reshape(4, 5).astype(np.float32)
+        v.add_image(data, name="img")
+        res = await s.get_layer("img", slicing="0:4:2, :")
+        assert res["status"] == "ok"
+        assert res["slice_shape"] == [2, 5]
+
+    async def test_empty_slicing_returns_error(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.get_layer("img", slicing="")
+        assert "slice_error" in res
+
+    async def test_too_many_colons_returns_error(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.get_layer("img", slicing="1:2:3:4")
+        assert "slice_error" in res
+
+    async def test_non_numeric_returns_error(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((5, 5), dtype=np.uint8), name="img")
+        res = await s.get_layer("img", slicing="abc")
+        assert "slice_error" in res
+
+    async def test_open_ended_slice(self, make_napari_viewer):
+        v = _viewer(make_napari_viewer)
+        data = np.arange(20).reshape(4, 5).astype(np.float32)
+        v.add_image(data, name="img")
+        res = await s.get_layer("img", slicing=":, 3")
+        assert res["status"] == "ok"
+        assert res["slice_shape"] == [4]
+
+
+# ── get_layer max_elements cap ────────────────────────────────────────────
+
+
+class TestGetLayerMaxElementsCap:
+    """Test that max_elements is capped at 1,000,000."""
+
+    async def test_negative_capped(self, make_napari_viewer):
+        """max_elements=-1 should be capped to 1,000,000."""
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10), dtype=np.uint8), name="img")
+        # Should not raise — -1 is capped internally
+        res = await s.get_layer("img", include_data=True, max_elements=-1)
+        assert res["status"] == "ok"
+
+    async def test_large_value_capped(self, make_napari_viewer):
+        """max_elements=2000000 should be capped to 1,000,000."""
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10), dtype=np.uint8), name="img")
+        res = await s.get_layer("img", include_data=True, max_elements=2_000_000)
+        assert res["status"] == "ok"
+
+
+# ── execute_code line_limit normalization ─────────────────────────────────
+
+
+class TestExecuteCodeLineLimitNormalization:
+    """Test that line_limit is properly normalized from string to int."""
+
+    async def test_string_int(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code("print('hello')", line_limit="30")
+        assert res["status"] == "ok"
+        assert "hello" in res["stdout"]
+
+    async def test_string_minus_one(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code("print('hello')", line_limit="-1")
+        assert "warning" in res
+
+    async def test_invalid_string_falls_back(self, make_napari_viewer):
+        _viewer(make_napari_viewer)
+        res = await s.execute_code("print('hello')", line_limit="invalid")
+        assert res["status"] == "ok"
+        # Should not crash — falls back to default 30
+
+
+# ── save_layer_data format coverage ───────────────────────────────────────
+
+
+class TestSaveLayerDataFormats:
+    """Additional format coverage for save_layer_data."""
+
+    async def test_png(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.zeros((10, 10), dtype=np.uint8), name="img")
+        out = tmp_path / "img.png"
+        res = await s.save_layer_data("img", str(out))
+        assert res["status"] == "ok"
+        assert Path(res["path"]).exists()
+        assert res["format"] == "png"
+
+    async def test_jpg(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_image(np.random.randint(0, 255, (10, 10), dtype=np.uint8), name="img")
+        out = tmp_path / "img.jpg"
+        res = await s.save_layer_data("img", str(out))
+        assert res["status"] == "ok"
+        assert Path(res["path"]).exists()
+
+    async def test_csv_tracks(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        # Tracks need 4D: track_id, t, y, x
+        data = np.array(
+            [[0, 0, 0, 0], [0, 1, 1, 1], [1, 0, 2, 2], [1, 1, 3, 3]], dtype=float
+        )
+        v.add_tracks(data, name="trk")
+        out = tmp_path / "trk.csv"
+        res = await s.save_layer_data("trk", str(out))
+        assert res["status"] == "ok"
+        lines = out.read_text().strip().splitlines()
+        assert "track_id" in lines[0]
+
+    async def test_labels_tiff(self, make_napari_viewer, tmp_path):
+        v = _viewer(make_napari_viewer)
+        v.add_labels(np.array([[0, 1], [2, 0]], dtype=np.int32), name="seg")
+        out = tmp_path / "seg.tiff"
+        res = await s.save_layer_data("seg", str(out))
+        assert res["status"] == "ok"
+        assert Path(res["path"]).exists()
diff --git a/tests/test_state.py b/tests/test_state.py
new file mode 100644
index 0000000..df43bca
--- /dev/null
+++ b/tests/test_state.py
@@ -0,0 +1,216 @@
+"""Tests for napari_mcp.state.ServerState and napari_mcp.viewer_protocol."""
+
+from unittest.mock import patch
+
+import pytest
+
+from napari_mcp.state import ServerState, StartupMode
+
+
+class TestServerState:
+    """Test ServerState initialization and methods."""
+
+    def test_default_standalone_mode(self):
+        state = ServerState()
+        assert state.mode == StartupMode.STANDALONE
+        assert state.viewer is None
+        assert state.exec_globals == {}
+        assert state.output_storage == {}
+        assert state.next_output_id == 1
+        assert state.window_close_connected is False
+        assert state.gui_executor is None
+
+    def test_auto_detect_mode(self):
+        state = ServerState(mode=StartupMode.AUTO_DETECT, bridge_port=1234)
+        assert state.mode == StartupMode.AUTO_DETECT
+        assert state.bridge_port == 1234
+
+    def test_default_bridge_port_from_env(self):
+        with patch.dict("os.environ", {"NAPARI_MCP_BRIDGE_PORT": "5555"}):
+            state = ServerState()
+            assert state.bridge_port == 5555
+
+    def test_gui_execute_without_executor(self):
+        state = ServerState()
+        result = state.gui_execute(lambda: 42)
+        assert result == 42
+
+    def test_gui_execute_with_executor(self):
+        state = ServerState()
+        calls = []
+        state.gui_executor = lambda op: calls.append("called") or op()
+        state.gui_execute(lambda: 42)
+        assert calls == ["called"]
+
+    @pytest.mark.asyncio
+    async def test_store_output(self):
+        state = ServerState()
+        oid = await state.store_output("test_tool", stdout="hello", stderr="")
+        assert oid == "1"
+        assert "1" in state.output_storage
+        assert state.output_storage["1"]["stdout"] == "hello"
+        assert state.output_storage["1"]["tool_name"] == "test_tool"
+        assert state.next_output_id == 2
+
+    @pytest.mark.asyncio
+    async def test_store_output_eviction(self):
+        state = ServerState()
+        state.max_output_items = 2
+        await state.store_output("t", stdout="a")
+        await state.store_output("t", stdout="b")
+        await state.store_output("t", stdout="c")
+        assert len(state.output_storage) == 2
+        assert "1" not in state.output_storage
+        assert "2" in state.output_storage
+        assert "3" in state.output_storage
+
+    @pytest.mark.asyncio
+    async def test_proxy_standalone_returns_none(self):
+        state = ServerState(mode=StartupMode.STANDALONE)
+        result = await state.proxy_to_external("some_tool")
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_detect_external_standalone_returns_false(self):
+        state = ServerState(mode=StartupMode.STANDALONE)
+        found, info = await state.detect_external_viewer()
+        assert found is False
+        assert info is None
+
+
+class TestRequestShutdown:
+    """Test ServerState.request_shutdown lifecycle."""
+
+    def test_initial_shutdown_state(self):
+        state = ServerState()
+        assert state._shutdown_requested is False
+        assert state._event_loop is None
+
+    def test_shutdown_without_event_loop(self):
+        """request_shutdown should not raise when no event loop is set."""
+        state = ServerState()
+        state.request_shutdown()
+        assert state._shutdown_requested is True
+
+    def test_shutdown_is_idempotent(self):
+        """Calling request_shutdown twice should only act once."""
+        state = ServerState()
+        state.request_shutdown()
+        assert state._shutdown_requested is True
+        # Second call should be a no-op (no error)
+        state.request_shutdown()
+        assert state._shutdown_requested is True
+
+    def test_shutdown_with_closed_loop(self):
+        """request_shutdown should not raise when the loop is already closed."""
+        import asyncio
+
+        loop = asyncio.new_event_loop()
+        loop.close()
+        state = ServerState()
+        state._event_loop = loop
+        # Should not raise
+        state.request_shutdown()
+        assert state._shutdown_requested is True
+
+    def test_shutdown_schedules_delayed_stop(self):
+        """request_shutdown should schedule a delayed loop.stop via call_later."""
+        import asyncio
+        from unittest.mock import MagicMock
+
+        loop = MagicMock(spec=asyncio.AbstractEventLoop)
+        loop.is_closed.return_value = False
+
+        state = ServerState()
+        state._event_loop = loop
+
+        state.request_shutdown()
+
+        loop.call_soon_threadsafe.assert_called_once()
+        # The argument should be a lambda that calls call_later
+        scheduled_fn = loop.call_soon_threadsafe.call_args[0][0]
+        scheduled_fn()
+        loop.call_later.assert_called_once()
+        delay_arg, stop_fn = loop.call_later.call_args[0]
+        assert delay_arg == 1.0
+        assert stop_fn is loop.stop
+
+
+class TestServerModuleInit:
+    """Test that server module initializes correctly at import time."""
+
+    def test_tools_available_at_import(self):
+        from napari_mcp import server as srv
+
+        assert hasattr(srv, "list_layers")
+        assert hasattr(srv, "execute_code")
+        assert hasattr(srv, "screenshot")
+        assert callable(srv.list_layers)
+
+    def test_state_exists_at_import(self):
+        from napari_mcp import server as srv
+
+        assert srv._state is not None
+
+    def test_server_instance_exists_at_import(self):
+        from napari_mcp import server as srv
+
+        assert hasattr(srv, "server")
+
+
+class TestServerStateEnvFallbacks:
+    """Test environment variable parsing edge cases."""
+
+    def test_malformed_max_output_items_env(self, monkeypatch):
+        monkeypatch.setenv("NAPARI_MCP_MAX_OUTPUT_ITEMS", "abc")
+        state = ServerState()
+        assert state.max_output_items == 1000  # fallback
+
+    @pytest.mark.asyncio
+    async def test_external_session_information_not_bridge(self, monkeypatch):
+        """external_session_information returns error when response is not a bridge session."""
+        from unittest.mock import AsyncMock, MagicMock
+
+        state = ServerState(mode=StartupMode.AUTO_DETECT)
+
+        mock_content_item = MagicMock()
+        mock_content_item.type = "text"
+        mock_content_item.text = '{"session_type": "something_else"}'
+
+        mock_result = MagicMock()
+        mock_result.content = [mock_content_item]
+
+        mock_client_instance = AsyncMock()
+        mock_client_instance.call_tool = AsyncMock(return_value=mock_result)
+        mock_client_instance.__aenter__ = AsyncMock(return_value=mock_client_instance)
+        mock_client_instance.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("fastmcp.Client", return_value=mock_client_instance):
+            result = await state.external_session_information()
+
+        assert result["status"] == "error"
+        assert "Failed to get session information" in result["message"]
+
+
+class TestViewerProtocol:
+    """Test ViewerProtocol structural typing."""
+
+    def test_protocol_is_importable(self):
+        from napari_mcp.viewer_protocol import ViewerProtocol
+
+        assert ViewerProtocol is not None
+
+    def test_protocol_defines_expected_methods(self):
+        from napari_mcp.viewer_protocol import ViewerProtocol
+
+        for method_name in (
+            "add_image",
+            "add_labels",
+            "add_points",
+            "screenshot",
+            "reset_view",
+            "close",
+        ):
+            assert hasattr(ViewerProtocol, method_name), (
+                f"Missing method: {method_name}"
+            )
diff --git a/tests/test_timelapse.py b/tests/test_timelapse.py
index f5bf5d1..eeb259b 100644
--- a/tests/test_timelapse.py
+++ b/tests/test_timelapse.py
@@ -11,7 +11,7 @@ async def test_timelapse_screenshot_basic(make_napari_viewer, monkeypatch):
     viewer = make_napari_viewer()
     from napari_mcp import server as napari_mcp_server
 
-    napari_mcp_server._viewer = viewer
+    napari_mcp_server._state.viewer = viewer
 
     # Add a simple T, Y, X image so axis 0 is temporal
     img = np.linspace(0, 255, 5 * 32 * 32, dtype=np.uint8).reshape(5, 32, 32)
@@ -19,9 +19,11 @@ async def test_timelapse_screenshot_basic(make_napari_viewer, monkeypatch):
     assert layer is not None
 
     # Invoke via the tool interface to ensure ctx is injected automatically
-    tool = await napari_mcp_server.server.get_tool("timelapse_screenshot")
+    tool = await napari_mcp_server.server.get_tool("screenshot")
     # Sweep all frames
-    result = await tool.fn(0, ":", True, False)
+    result = await tool.fn(
+        axis=0, slice_range=":", canvas_only=True, interpolate_to_fit=False
+    )
 
     assert isinstance(result, list)
     assert len(result) == 5
@@ -53,7 +55,7 @@ async def test_timelapse_screenshot_interpolate_to_fit_enforces_cap(
     viewer = make_napari_viewer()
     from napari_mcp import server as napari_mcp_server
 
-    napari_mcp_server._viewer = viewer
+    napari_mcp_server._state.viewer = viewer
 
     # Create many frames so uncompressed total would exceed the cap
     t = 20
@@ -79,14 +81,18 @@ def fake_save(self, fp, *args, **kwargs):  # noqa: D401
     monkeypatch.setattr(PIL.Image.Image, "save", fake_save)
 
     try:
-        tool = await napari_mcp_server.server.get_tool("timelapse_screenshot")
+        tool = await napari_mcp_server.server.get_tool("screenshot")
 
         # Without interpolation: should return all frames (may exceed cap)
-        res_no = await tool.fn(0, ":", True, False)
+        res_no = await tool.fn(
+            axis=0, slice_range=":", canvas_only=True, interpolate_to_fit=False
+        )
         assert len(res_no) == t
 
         # With interpolation: should fit within cap and also return all frames
-        res_yes = await tool.fn(0, ":", True, True)
+        res_yes = await tool.fn(
+            axis=0, slice_range=":", canvas_only=True, interpolate_to_fit=True
+        )
         assert len(res_yes) == t
 
         total_b64 = _b64_len_list(res_yes)
@@ -108,3 +114,77 @@ def fake_save(self, fp, *args, **kwargs):  # noqa: D401
     finally:
         # Restore original save
         monkeypatch.setattr(PIL.Image.Image, "save", orig_save)
+
+
+@pytest.mark.asyncio
+async def test_timelapse_screenshot_invalid_slice_range(make_napari_viewer):
+    """Test timelapse_screenshot with invalid slice range."""
+    viewer = make_napari_viewer()
+    from napari_mcp import server as napari_mcp_server
+
+    napari_mcp_server._state.viewer = viewer
+
+    img = np.zeros((5, 32, 32), dtype=np.uint8)
+    viewer.add_image(img, name="timelapse")
+
+    tool = await napari_mcp_server.server.get_tool("screenshot")
+
+    result = await tool.fn(axis=0, slice_range="1:2:3:4", canvas_only=True)
+    assert result["status"] == "error"
+    assert "Invalid slice range" in result["message"]
+
+
+@pytest.mark.asyncio
+async def test_timelapse_screenshot_step_zero(make_napari_viewer):
+    """Test timelapse_screenshot with step=0 raises ValueError."""
+    viewer = make_napari_viewer()
+    from napari_mcp import server as napari_mcp_server
+
+    napari_mcp_server._state.viewer = viewer
+
+    img = np.zeros((5, 32, 32), dtype=np.uint8)
+    viewer.add_image(img, name="timelapse")
+
+    tool = await napari_mcp_server.server.get_tool("screenshot")
+
+    result = await tool.fn(axis=0, slice_range="::0", canvas_only=True)
+    assert result["status"] == "error"
+    assert "step cannot be 0" in result["message"]
+
+
+@pytest.mark.asyncio
+async def test_timelapse_screenshot_negative_index(make_napari_viewer):
+    """Test timelapse_screenshot with negative index (last frame)."""
+    viewer = make_napari_viewer()
+    from napari_mcp import server as napari_mcp_server
+
+    napari_mcp_server._state.viewer = viewer
+
+    img = np.linspace(0, 255, 5 * 32 * 32, dtype=np.uint8).reshape(5, 32, 32)
+    viewer.add_image(img, name="timelapse")
+
+    tool = await napari_mcp_server.server.get_tool("screenshot")
+
+    # "-1" should select only the last frame
+    result = await tool.fn(axis=0, slice_range="-1", canvas_only=True)
+    assert isinstance(result, list)
+    assert len(result) == 1
+
+
+@pytest.mark.asyncio
+async def test_timelapse_screenshot_2d_image(make_napari_viewer):
+    """Test timelapse_screenshot with 2D (non-temporal) data."""
+    viewer = make_napari_viewer()
+    from napari_mcp import server as napari_mcp_server
+
+    napari_mcp_server._state.viewer = viewer
+
+    img = np.zeros((32, 32), dtype=np.uint8)
+    viewer.add_image(img, name="flat")
+
+    tool = await napari_mcp_server.server.get_tool("screenshot")
+
+    # Single index "0" on axis 0 of a 2D image
+    result = await tool.fn(axis=0, slice_range="0", canvas_only=True)
+    assert isinstance(result, list)
+    assert len(result) == 1
diff --git a/tests/test_tools.py b/tests/test_tools.py
index ff8b5cb..a4f6e0e 100644
--- a/tests/test_tools.py
+++ b/tests/test_tools.py
@@ -1,27 +1,38 @@
+"""Integration and structural tests for the MCP tool registry.
+
+- E2E workflow exercising all 16 tools in sequence
+- MCP dispatch verification (tools callable via server.get_tool)
+- Server factory (create_server returns FastMCP, sets state, registers tools)
+- README completeness (every tool name appears in README)
+"""
+
 from pathlib import Path
 
 import numpy as np
 import pytest
 
-from napari_mcp.server import (
-    add_image,
-    add_labels,
-    add_points,
-    close_viewer,
-    execute_code,
-    init_viewer,
-    list_layers,
-    remove_layer,
-    reorder_layer,
-    reset_view,
-    screenshot,
-    set_active_layer,
-    set_camera,
-    set_dims_current_step,
-    set_grid,
-    set_layer_properties,
-    set_ndisplay,
-)
+from napari_mcp import server as napari_mcp_server
+
+# Authoritative set of all registered MCP tool names.
+# Update this when adding/removing tools in server.py.
+EXPECTED_TOOLS = {
+    "add_layer",
+    "apply_to_layers",
+    "close_viewer",
+    "configure_viewer",
+    "execute_code",
+    "get_layer",
+    "init_viewer",
+    "install_packages",
+    "list_layers",
+    "read_output",
+    "remove_layer",
+    "reorder_layer",
+    "save_layer_data",
+    "screenshot",
+    "session_information",
+    "set_layer_properties",
+}
 
 
 def test_version_import() -> None:
@@ -34,148 +45,189 @@ def test_version_import() -> None:
 
 @pytest.mark.asyncio
 async def test_all_tools_end_to_end(make_napari_viewer, tmp_path: Path) -> None:
-    # Create a napari viewer using the built-in fixture
+    """Smoke test: exercise every tool in a realistic workflow."""
     viewer = make_napari_viewer()
+    napari_mcp_server._state.viewer = viewer
 
-    # Set the viewer in the server module
-    from napari_mcp import server as napari_mcp_server
-
-    napari_mcp_server._viewer = viewer
+    import imageio.v3 as iio
 
-    # init viewer
-    res = await init_viewer(title="Test Viewer")
+    # init_viewer
+    res = await napari_mcp_server.init_viewer(title="E2E")
     assert res["status"] == "ok"
-    assert isinstance(res["layers"], list)
 
-    # create sample image (T, Y, X) to exercise dims slider
+    # add_layer (image from file)
     img = np.linspace(0, 255, 5 * 32 * 32, dtype=np.uint8).reshape(5, 32, 32)
-    img_path = tmp_path / "img.tif"
-    import imageio.v3 as iio
-
-    iio.imwrite(img_path, img)
-
-    # add image
-    res = await add_image(str(img_path), name="img")
+    iio.imwrite(tmp_path / "img.tif", img)
+    res = await napari_mcp_server.add_layer(
+        "image", path=str(tmp_path / "img.tif"), name="img"
+    )
     assert res["status"] == "ok"
-    assert res["name"] == "img"
 
-    # add labels
-    labels = np.random.randint(0, 4, size=(32, 32), dtype=np.uint8)
-    labels_path = tmp_path / "labels.tif"
-    iio.imwrite(labels_path, labels)
-    res = await add_labels(str(labels_path), name="labels")
+    # add_layer (labels from file)
+    iio.imwrite(tmp_path / "lbl.tif", np.random.randint(0, 4, (32, 32), dtype=np.uint8))
+    assert (
+        await napari_mcp_server.add_layer(
+            "labels", path=str(tmp_path / "lbl.tif"), name="lbl"
+        )
+    )["status"] == "ok"
+
+    # add_layer (points inline)
+    res = await napari_mcp_server.add_layer(
+        "points", data=[[5, 5], [10, 10]], name="pts", size=5
+    )
+    assert res["n_points"] == 2
+
+    # list_layers
+    names = {entry["name"] for entry in await napari_mcp_server.list_layers()}
+    assert {"img", "lbl", "pts"} <= names
+
+    # get_layer (metadata)
+    info = await napari_mcp_server.get_layer("img")
+    assert info["type"] == "Image" and info["data_shape"] == [5, 32, 32]
+
+    # get_layer (data + slicing)
+    data = await napari_mcp_server.get_layer("img", slicing="0, :2, :2")
+    assert "data" in data and "statistics" in data
+
+    # set_layer_properties (visibility, opacity, active, rename)
+    await napari_mcp_server.set_layer_properties(
+        "img", visible=False, opacity=0.5, active=True
+    )
+    assert viewer.layers["img"].visible is False
+
+    # reorder_layer
+    assert (await napari_mcp_server.reorder_layer("lbl", before="img"))[
+        "status"
+    ] == "ok"
+
+    # apply_to_layers
+    res = await napari_mcp_server.apply_to_layers(
+        filter_type="Image", properties={"opacity": 0.8}
+    )
+    assert res["count"] == 1
+
+    # configure_viewer
+    assert (
+        await napari_mcp_server.configure_viewer(reset_view=True, ndisplay=2, grid=True)
+    )["status"] == "ok"
+    assert (
+        await napari_mcp_server.configure_viewer(zoom=1.5, dims_axis=0, dims_value=2)
+    )["status"] == "ok"
+
+    # screenshot (single)
+    shot = await napari_mcp_server.screenshot(canvas_only=True)
+    assert str(shot.mimeType).lower() in ("png", "image/png")
+
+    # save_layer_data
+    res = await napari_mcp_server.save_layer_data("pts", str(tmp_path / "pts.csv"))
     assert res["status"] == "ok"
 
-    # add points
-    res = await add_points([[5, 5], [10, 10]], name="pts", size=5)
-    assert res["status"] == "ok" and res["n_points"] == 2
-
-    # list layers
-    layers = await list_layers()
-    layer_names = {lyr["name"] for lyr in layers}
-    assert {"img", "labels", "pts"}.issubset(layer_names)
-
-    # reorder layers: move labels before img
-    res = await reorder_layer("labels", before="img")
+    # execute_code
+    res = await napari_mcp_server.execute_code("len(viewer.layers)")
     assert res["status"] == "ok"
 
-    # set active layer and properties
-    res = await set_active_layer("img")
-    assert res["status"] == "ok" and res["active"] == "img"
-    res = await set_layer_properties("img", visible=False, opacity=0.5)
-    assert res["status"] == "ok"
+    # session_information
+    si = await napari_mcp_server.session_information()
+    assert si["viewer"]["n_layers"] == len(viewer.layers)
 
-    # view controls
-    assert (await reset_view())["status"] == "ok"
-    assert (await set_camera(zoom=1.5))["status"] == "ok"
-    cam = await set_camera(center=[10, 10], zoom=2.0, angle=0.0)
-    assert cam["status"] == "ok"
+    # remove + rename + close
+    await napari_mcp_server.set_layer_properties("img", new_name="image1")
+    assert (await napari_mcp_server.remove_layer("lbl"))["status"] == "removed"
+    assert (await napari_mcp_server.close_viewer())["status"] in {"closed", "no_viewer"}
 
-    # dims/grid controls
-    # Keep ndisplay at 2 to avoid 3D requirements
-    assert (await set_ndisplay(2))["status"] == "ok"
-    assert (await set_dims_current_step(0, 2))["status"] == "ok"
-    assert (await set_grid(True))["status"] == "ok"
 
-    # screenshot returns a valid PNG (FastMCP Image)
-    shot = await screenshot(canvas_only=True)
-    fmt = shot.mimeType
-    assert str(fmt).lower() in ("png", "image/png")
+@pytest.mark.asyncio
+async def test_add_layer_error_handling(make_napari_viewer, tmp_path: Path) -> None:
+    """Error paths: bad file, bad data, nonexistent path."""
+    viewer = make_napari_viewer()
+    napari_mcp_server._state.viewer = viewer
 
-    import base64
+    assert (await napari_mcp_server.add_layer("image", path="/nonexistent.tif"))[
+        "status"
+    ] == "error"
+    assert (await napari_mcp_server.add_layer("points", data="bad"))[
+        "status"
+    ] == "error"
 
-    data = base64.b64decode(shot.data)
-    assert data.startswith(b"\x89PNG\r\n\x1a\n")
 
-    # rename and remove layers
-    assert (await set_layer_properties("img", new_name="image1"))["status"] == "ok"
-    assert (await remove_layer("labels"))["status"] == "removed"
+@pytest.mark.asyncio
+async def test_mcp_tool_dispatch(make_napari_viewer) -> None:
+    """All tools are registered and callable via MCP dispatch."""
+    viewer = make_napari_viewer()
+    napari_mcp_server._state.viewer = viewer
+    server = napari_mcp_server.server
 
-    # close viewer
-    assert (await close_viewer())["status"] in {"closed", "no_viewer"}
+    for tool_name in EXPECTED_TOOLS:
+        tool = await server.get_tool(tool_name)
+        assert tool is not None, f"Tool '{tool_name}' not registered"
+        assert callable(tool.fn), f"Tool '{tool_name}' fn is not callable"
 
+    # Dispatch through MCP interface (not direct function call)
+    tool = await server.get_tool("add_layer")
+    result = await tool.fn("points", data=[[5, 5]], name="dispatch_pts")
+    assert result["status"] == "ok"
 
-@pytest.mark.asyncio
-async def test_execute_code_namespace_and_result(make_napari_viewer) -> None:
-    # Create a napari viewer using the built-in fixture
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
+    tool = await server.get_tool("remove_layer")
+    assert (await tool.fn("dispatch_pts"))["status"] == "removed"
 
-    napari_mcp_server._viewer = viewer
 
-    # Simple expression
-    res = await execute_code("1 + 2")
-    assert res["status"] == "ok"
-    assert res.get("result_repr") == "3"
+class TestCreateServer:
+    def test_returns_fastmcp(self):
+        from fastmcp import FastMCP
 
-    # Set a variable and verify it's accessible
-    res = await execute_code("x = 42")
-    assert res["status"] == "ok"
+        from napari_mcp.server import create_server
+        from napari_mcp.state import ServerState
 
-    res = await execute_code("x * 2")
-    assert res["status"] == "ok"
-    assert res.get("result_repr") == "84"
+        assert isinstance(create_server(ServerState()), FastMCP)
 
-    # Import a module in the namespace
-    res = await execute_code("import math")
-    assert res["status"] == "ok"
+    def test_sets_module_state(self):
+        from napari_mcp.server import create_server
+        from napari_mcp.state import ServerState
 
-    res = await execute_code("math.pi")
-    assert res["status"] == "ok"
-    assert res.get("result_repr", "").startswith("3.14")
+        state = ServerState()
+        create_server(state)
+        assert napari_mcp_server._state is state
 
-    # Clean up
-    await close_viewer()
+    def test_registers_all_tools(self):
+        from napari_mcp.server import create_server
+        from napari_mcp.state import ServerState
 
+        create_server(ServerState())
+        for name in EXPECTED_TOOLS:
+            fn = getattr(napari_mcp_server, name, None)
+            assert fn is not None and callable(fn), f"Tool {name} missing"
 
-@pytest.mark.asyncio
-async def test_screenshot_no_viewer() -> None:
-    pytest.skip(reason="This test is not working")
 
-    # Test screenshot when no viewer exists
-    from napari_mcp import server as napari_mcp_server
+class TestToolListCompleteness:
+    def test_readme_lists_all_tools(self):
+        content = (Path(__file__).parent.parent / "README.md").read_text(
+            encoding="utf-8"
+        )
+        missing = {t for t in EXPECTED_TOOLS if f"`{t}`" not in content}
+        assert not missing, f"README.md missing tools: {missing}"
 
-    # Ensure no viewer is set
-    napari_mcp_server._viewer = None
+    @pytest.mark.asyncio
+    async def test_expected_tools_matches_server(self):
+        """EXPECTED_TOOLS stays in sync with actually registered tools."""
+        from napari_mcp.server import create_server
+        from napari_mcp.state import ServerState
 
-    # screenshot with no viewer should return either error or a valid image
-    res = await screenshot()
-    assert res.mimeType.lower() in ("png", "image/png")
-    assert res.data is not None
+        state = ServerState()
+        srv = create_server(state)
 
+        registered = set((await srv.get_tools()).keys())
+        assert registered == EXPECTED_TOOLS, (
+            f"Mismatch — registered: {registered - EXPECTED_TOOLS}, "
+            f"expected but missing: {EXPECTED_TOOLS - registered}"
+        )
 
-@pytest.mark.asyncio
-async def test_add_layers_error_handling(make_napari_viewer, tmp_path: Path) -> None:
-    # Create a napari viewer using the built-in fixture
-    viewer = make_napari_viewer()
-    from napari_mcp import server as napari_mcp_server
 
-    napari_mcp_server._viewer = viewer
+class TestDeprecatedInstallCommand:
+    def test_exits_with_error(self):
+        from typer.testing import CliRunner
 
-    # Test adding image with bad path - should raise FileNotFoundError
-    with pytest.raises(FileNotFoundError):
-        await add_image("/nonexistent/file.tif", name="bad")
+        from napari_mcp.server import app
 
-    # Test adding points with bad data - should raise ValueError
-    with pytest.raises(ValueError):
-        await add_points("not_an_array", name="bad_points")
+        result = CliRunner().invoke(app, ["install"])
+        assert result.exit_code == 1
+        assert "napari-mcp-install" in result.stdout
diff --git a/tests/test_widget.py b/tests/test_widget.py
index 299bf21..31cae10 100644
--- a/tests/test_widget.py
+++ b/tests/test_widget.py
@@ -3,7 +3,10 @@
 Tests the Qt widget interface for the MCP server using real Qt.
 """
 
+from unittest.mock import patch
+
 import numpy as np
+import pytest
 
 
 class TestWidgetWithRealQt:
@@ -135,3 +138,66 @@ def test_widget_cleanup(self, make_napari_viewer, qtbot):
         # Server should be stopped
         if server:
             assert not server.is_running
+
+    def test_widget_initialization_without_viewer(self, make_napari_viewer, qtbot):
+        """Test widget uses current_viewer when no viewer provided."""
+        viewer = make_napari_viewer()
+        viewer.title = "Current Viewer"
+
+        import napari
+
+        with patch.object(napari, "current_viewer", return_value=viewer):
+            from napari_mcp.widget import MCPControlWidget
+
+            widget = MCPControlWidget()
+            qtbot.addWidget(widget)
+            assert widget.viewer == viewer
+
+    def test_widget_initialization_no_viewer_error(self, qtbot):
+        """Test widget raises error when no viewer available."""
+        import napari
+
+        with patch.object(napari, "current_viewer", return_value=None):
+            from napari_mcp.widget import MCPControlWidget
+
+            with pytest.raises(RuntimeError, match="No napari viewer found"):
+                MCPControlWidget()
+
+    def test_port_change_replaces_text(self, make_napari_viewer, qtbot):
+        """Port change should replace info text, not append to it."""
+        from napari_mcp.widget import MCPControlWidget
+
+        viewer = make_napari_viewer()
+        widget = MCPControlWidget(viewer, port=9999)
+        qtbot.addWidget(widget)
+
+        # Change port multiple times
+        widget._on_port_changed(8888)
+        widget._on_port_changed(7777)
+        widget._on_port_changed(6666)
+
+        text = widget.info_text.toPlainText()
+        # Should only contain ONE port message (the last one), not three
+        assert text.count("Port set to") == 1
+        assert "6666" in text
+
+    def test_start_server_failure_updates_ui(self, make_napari_viewer, qtbot):
+        """If server.start() fails, UI should show error and remain startable."""
+        from napari_mcp.widget import MCPControlWidget
+
+        viewer = make_napari_viewer()
+        widget = MCPControlWidget(viewer, port=9999)
+        qtbot.addWidget(widget)
+
+        # Mock NapariBridgeServer to make start() return False
+        with patch("napari_mcp.widget.NapariBridgeServer") as MockServer:
+            mock_server = MockServer.return_value
+            mock_server.start.return_value = False
+            mock_server.is_running = False
+
+            widget._start_server()
+
+            # UI should show error state
+            assert widget.start_button.isEnabled() is True
+            assert widget.stop_button.isEnabled() is False
+            assert "Failed" in widget.info_text.toPlainText()
diff --git a/tox.ini b/tox.ini
deleted file mode 100644
index e15eece..0000000
--- a/tox.ini
+++ /dev/null
@@ -1,33 +0,0 @@
-# For more information about tox, see https://tox.readthedocs.io/en/latest/
-[tox]
-envlist = py{310,311,312,313}-{linux,macos,windows}
-isolated_build=true
-
-[gh-actions]
-python =
-    3.10: py310
-    3.11: py311
-    3.12: py312
-    3.13: py313
-
-[gh-actions:env]
-PLATFORM =
-    ubuntu-latest: linux
-    macos-latest: macos
-    windows-latest: windows
-
-[testenv]
-platform =
-    macos: darwin
-    linux: linux
-    windows: win32
-passenv =
-    CI
-    GITHUB_ACTIONS
-    DISPLAY
-    XAUTHORITY
-    NUMPY_EXPERIMENTAL_ARRAY_FUNCTION
-    PYVISTA_OFF_SCREEN
-    QT_QPA_PLATFORM
-extras = test
-commands = pytest -v --color=yes --cov=napari_mcp --cov-report=xml
diff --git a/uv.lock b/uv.lock
index 276b58a..6708a40 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 2
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version >= '3.13' and sys_platform == 'darwin'",
@@ -148,40 +148,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/48/ca/ba5f909b40ea12ec542d5d7bdd13ee31c4d65f3beed20211ef81c18fa1f3/bandit-1.8.6-py3-none-any.whl", hash = "sha256:3348e934d736fcdb68b6aa4030487097e23a501adf3e7827b63658df464dddd0", size = 133808, upload-time = "2025-07-06T03:10:49.134Z" },
 ]
 
-[[package]]
-name = "black"
-version = "25.1.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "click" },
-    { name = "mypy-extensions" },
-    { name = "packaging" },
-    { name = "pathspec" },
-    { name = "platformdirs" },
-    { name = "tomli", marker = "python_full_version < '3.11'" },
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/94/49/26a7b0f3f35da4b5a65f081943b7bcd22d7002f5f0fb8098ec1ff21cb6ef/black-25.1.0.tar.gz", hash = "sha256:33496d5cd1222ad73391352b4ae8da15253c5de89b93a80b3e2c8d9a19ec2666", size = 649449, upload-time = "2025-01-29T04:15:40.373Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/4d/3b/4ba3f93ac8d90410423fdd31d7541ada9bcee1df32fb90d26de41ed40e1d/black-25.1.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:759e7ec1e050a15f89b770cefbf91ebee8917aac5c20483bc2d80a6c3a04df32", size = 1629419, upload-time = "2025-01-29T05:37:06.642Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/02/0bde0485146a8a5e694daed47561785e8b77a0466ccc1f3e485d5ef2925e/black-25.1.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:0e519ecf93120f34243e6b0054db49c00a35f84f195d5bce7e9f5cfc578fc2da", size = 1461080, upload-time = "2025-01-29T05:37:09.321Z" },
-    { url = "https://files.pythonhosted.org/packages/52/0e/abdf75183c830eaca7589144ff96d49bce73d7ec6ad12ef62185cc0f79a2/black-25.1.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:055e59b198df7ac0b7efca5ad7ff2516bca343276c466be72eb04a3bcc1f82d7", size = 1766886, upload-time = "2025-01-29T04:18:24.432Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/a6/97d8bb65b1d8a41f8a6736222ba0a334db7b7b77b8023ab4568288f23973/black-25.1.0-cp310-cp310-win_amd64.whl", hash = "sha256:db8ea9917d6f8fc62abd90d944920d95e73c83a5ee3383493e35d271aca872e9", size = 1419404, upload-time = "2025-01-29T04:19:04.296Z" },
-    { url = "https://files.pythonhosted.org/packages/7e/4f/87f596aca05c3ce5b94b8663dbfe242a12843caaa82dd3f85f1ffdc3f177/black-25.1.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:a39337598244de4bae26475f77dda852ea00a93bd4c728e09eacd827ec929df0", size = 1614372, upload-time = "2025-01-29T05:37:11.71Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/d0/2c34c36190b741c59c901e56ab7f6e54dad8df05a6272a9747ecef7c6036/black-25.1.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:96c1c7cd856bba8e20094e36e0f948718dc688dba4a9d78c3adde52b9e6c2299", size = 1442865, upload-time = "2025-01-29T05:37:14.309Z" },
-    { url = "https://files.pythonhosted.org/packages/21/d4/7518c72262468430ead45cf22bd86c883a6448b9eb43672765d69a8f1248/black-25.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bce2e264d59c91e52d8000d507eb20a9aca4a778731a08cfff7e5ac4a4bb7096", size = 1749699, upload-time = "2025-01-29T04:18:17.688Z" },
-    { url = "https://files.pythonhosted.org/packages/58/db/4f5beb989b547f79096e035c4981ceb36ac2b552d0ac5f2620e941501c99/black-25.1.0-cp311-cp311-win_amd64.whl", hash = "sha256:172b1dbff09f86ce6f4eb8edf9dede08b1fce58ba194c87d7a4f1a5aa2f5b3c2", size = 1428028, upload-time = "2025-01-29T04:18:51.711Z" },
-    { url = "https://files.pythonhosted.org/packages/83/71/3fe4741df7adf015ad8dfa082dd36c94ca86bb21f25608eb247b4afb15b2/black-25.1.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:4b60580e829091e6f9238c848ea6750efed72140b91b048770b64e74fe04908b", size = 1650988, upload-time = "2025-01-29T05:37:16.707Z" },
-    { url = "https://files.pythonhosted.org/packages/13/f3/89aac8a83d73937ccd39bbe8fc6ac8860c11cfa0af5b1c96d081facac844/black-25.1.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:1e2978f6df243b155ef5fa7e558a43037c3079093ed5d10fd84c43900f2d8ecc", size = 1453985, upload-time = "2025-01-29T05:37:18.273Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/22/b99efca33f1f3a1d2552c714b1e1b5ae92efac6c43e790ad539a163d1754/black-25.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:3b48735872ec535027d979e8dcb20bf4f70b5ac75a8ea99f127c106a7d7aba9f", size = 1783816, upload-time = "2025-01-29T04:18:33.823Z" },
-    { url = "https://files.pythonhosted.org/packages/18/7e/a27c3ad3822b6f2e0e00d63d58ff6299a99a5b3aee69fa77cd4b0076b261/black-25.1.0-cp312-cp312-win_amd64.whl", hash = "sha256:ea0213189960bda9cf99be5b8c8ce66bb054af5e9e861249cd23471bd7b0b3ba", size = 1440860, upload-time = "2025-01-29T04:19:12.944Z" },
-    { url = "https://files.pythonhosted.org/packages/98/87/0edf98916640efa5d0696e1abb0a8357b52e69e82322628f25bf14d263d1/black-25.1.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8f0b18a02996a836cc9c9c78e5babec10930862827b1b724ddfe98ccf2f2fe4f", size = 1650673, upload-time = "2025-01-29T05:37:20.574Z" },
-    { url = "https://files.pythonhosted.org/packages/52/e5/f7bf17207cf87fa6e9b676576749c6b6ed0d70f179a3d812c997870291c3/black-25.1.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:afebb7098bfbc70037a053b91ae8437c3857482d3a690fefc03e9ff7aa9a5fd3", size = 1453190, upload-time = "2025-01-29T05:37:22.106Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/ee/adda3d46d4a9120772fae6de454c8495603c37c4c3b9c60f25b1ab6401fe/black-25.1.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:030b9759066a4ee5e5aca28c3c77f9c64789cdd4de8ac1df642c40b708be6171", size = 1782926, upload-time = "2025-01-29T04:18:58.564Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/64/94eb5f45dcb997d2082f097a3944cfc7fe87e071907f677e80788a2d7b7a/black-25.1.0-cp313-cp313-win_amd64.whl", hash = "sha256:a22f402b410566e2d1c950708c77ebf5ebd5d0d88a6a2e87c86d9fb48afa0d18", size = 1442613, upload-time = "2025-01-29T04:19:27.63Z" },
-    { url = "https://files.pythonhosted.org/packages/09/71/54e999902aed72baf26bca0d50781b01838251a462612966e9fc4891eadd/black-25.1.0-py3-none-any.whl", hash = "sha256:95e8176dae143ba9097f351d174fdaf0ccd29efb414b362ae3fd72bf0f710717", size = 207646, upload-time = "2025-01-29T04:15:38.082Z" },
-]
-
 [[package]]
 name = "build"
 version = "1.3.0"
@@ -198,15 +164,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/8c/2b30c12155ad8de0cf641d76a8b396a16d2c36bc6d50b621a62b7c4567c1/build-1.3.0-py3-none-any.whl", hash = "sha256:7145f0b5061ba90a1500d60bd1b13ca0a8a4cebdd0cc16ed8adf1c0e739f43b4", size = 23382, upload-time = "2025-08-01T21:27:07.844Z" },
 ]
 
-[[package]]
-name = "cachetools"
-version = "6.2.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/9d/61/e4fad8155db4a04bfb4734c7c8ff0882f078f24294d42798b3568eb63bff/cachetools-6.2.0.tar.gz", hash = "sha256:38b328c0889450f05f5e120f56ab68c8abaf424e1275522b138ffc93253f7e32", size = 30988, upload-time = "2025-08-25T18:57:30.924Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/6c/56/3124f61d37a7a4e7cc96afc5492c78ba0cb551151e530b54669ddd1436ef/cachetools-6.2.0-py3-none-any.whl", hash = "sha256:1c76a8960c0041fcc21097e357f882197c79da0dbff766e7317890a65d7d8ba6", size = 11276, upload-time = "2025-08-25T18:57:29.684Z" },
-]
-
 [[package]]
 name = "cachey"
 version = "0.2.1"
@@ -294,15 +251,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c5/55/51844dd50c4fc7a33b653bfaba4c2456f06955289ca770a5dbd5fd267374/cfgv-3.4.0-py2.py3-none-any.whl", hash = "sha256:b7265b1f29fd3316bfcd2b330d63d024f2bfd8bcb8b0272f8e19a504856c48f9", size = 7249, upload-time = "2023-08-12T20:38:16.269Z" },
 ]
 
-[[package]]
-name = "chardet"
-version = "5.2.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/f3/0d/f7b6ab21ec75897ed80c17d79b15951a719226b9fababf1e40ea74d69079/chardet-5.2.0.tar.gz", hash = "sha256:1b3b6ff479a8c414bc3fa2c0852995695c4a026dcd6d0633b2dd092ca39c1cf7", size = 2069618, upload-time = "2023-08-01T19:23:02.662Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/38/6f/f5fbc992a329ee4e0f288c1fe0e2ad9485ed064cac731ed2fe47dcc38cbf/chardet-5.2.0-py3-none-any.whl", hash = "sha256:e1cf59446890a00105fe7b7912492ea04b6e6f06d4b742b2c788469e34c82970", size = 199385, upload-time = "2023-08-01T19:23:00.661Z" },
-]
-
 [[package]]
 name = "charset-normalizer"
 version = "3.4.2"
@@ -2341,64 +2289,33 @@ dependencies = [
     { name = "napari" },
     { name = "numpy" },
     { name = "pillow" },
-    { name = "pyqt6" },
     { name = "qtpy" },
     { name = "rich" },
     { name = "toml" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
     { name = "typer" },
 ]
 
 [package.optional-dependencies]
 all = [
     { name = "bandit" },
-    { name = "black" },
-    { name = "hypothesis" },
     { name = "mypy" },
-    { name = "napari", extra = ["pyqt6", "testing"] },
     { name = "pre-commit" },
-    { name = "pytest" },
-    { name = "pytest-asyncio" },
-    { name = "pytest-benchmark" },
-    { name = "pytest-cov" },
-    { name = "pytest-forked" },
-    { name = "pytest-mock" },
-    { name = "pytest-qt" },
-    { name = "pytest-random-order" },
-    { name = "pytest-timeout" },
-    { name = "pytest-xdist" },
     { name = "ruff" },
-    { name = "tox" },
     { name = "types-pillow" },
     { name = "types-toml" },
 ]
 dev = [
     { name = "bandit" },
-    { name = "black" },
     { name = "mypy" },
     { name = "pre-commit" },
     { name = "ruff" },
     { name = "types-pillow" },
     { name = "types-toml" },
 ]
-test = [
-    { name = "hypothesis" },
-    { name = "napari", extra = ["pyqt6", "testing"] },
-    { name = "pytest" },
-    { name = "pytest-asyncio" },
-    { name = "pytest-benchmark" },
-    { name = "pytest-cov" },
-    { name = "pytest-forked" },
-    { name = "pytest-mock" },
-    { name = "pytest-qt" },
-    { name = "pytest-random-order" },
-    { name = "pytest-timeout" },
-    { name = "pytest-xdist" },
-    { name = "tox" },
-]
 
 [package.dev-dependencies]
 dev = [
-    { name = "black" },
     { name = "ruff" },
     { name = "types-toml" },
 ]
@@ -2407,53 +2324,40 @@ testing = [
     { name = "napari", extra = ["pyqt6", "testing"] },
     { name = "pytest" },
     { name = "pytest-asyncio" },
+    { name = "pytest-benchmark" },
     { name = "pytest-cov" },
     { name = "pytest-forked" },
     { name = "pytest-mock" },
     { name = "pytest-qt" },
     { name = "pytest-random-order" },
-    { name = "tox" },
+    { name = "pytest-timeout" },
+    { name = "pytest-xdist" },
 ]
 
 [package.metadata]
 requires-dist = [
     { name = "bandit", marker = "extra == 'dev'", specifier = ">=1.8.6" },
-    { name = "black", marker = "extra == 'dev'", specifier = ">=24.0.0" },
     { name = "fastmcp", specifier = ">=2.10.3" },
-    { name = "hypothesis", marker = "extra == 'test'", specifier = ">=6.100.0" },
     { name = "imageio", specifier = ">=2.34.0" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.17.0" },
     { name = "napari", specifier = ">=0.5.5" },
-    { name = "napari", extras = ["pyqt6", "testing"], marker = "extra == 'test'" },
-    { name = "napari-mcp", extras = ["dev", "test"], marker = "extra == 'all'" },
+    { name = "napari-mcp", extras = ["dev"], marker = "extra == 'all'" },
     { name = "numpy", specifier = ">=1.26.0" },
     { name = "pillow", specifier = ">=10.3.0" },
     { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=4.3.0" },
-    { name = "pyqt6", specifier = ">=6.5.0" },
-    { name = "pytest", marker = "extra == 'test'", specifier = ">=8.4.0" },
-    { name = "pytest-asyncio", marker = "extra == 'test'", specifier = ">=0.23.0" },
-    { name = "pytest-benchmark", marker = "extra == 'test'", specifier = ">=4.0.0" },
-    { name = "pytest-cov", marker = "extra == 'test'", specifier = ">=4.0.0" },
-    { name = "pytest-forked", marker = "extra == 'test'", specifier = ">=1.6.0" },
-    { name = "pytest-mock", marker = "extra == 'test'", specifier = ">=3.12.0" },
-    { name = "pytest-qt", marker = "extra == 'test'", specifier = ">=4.0.0" },
-    { name = "pytest-random-order", marker = "extra == 'test'", specifier = ">=1.1.0" },
-    { name = "pytest-timeout", marker = "extra == 'test'", specifier = ">=2.2.0" },
-    { name = "pytest-xdist", marker = "extra == 'test'", specifier = ">=3.5.0" },
     { name = "qtpy", specifier = ">=2.4.1" },
     { name = "rich", specifier = ">=13.0.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.12.10" },
     { name = "toml", specifier = ">=0.10.2" },
-    { name = "tox", marker = "extra == 'test'" },
+    { name = "tomli", marker = "python_full_version < '3.11'", specifier = ">=2.0" },
     { name = "typer", specifier = ">=0.9.0" },
     { name = "types-pillow", marker = "extra == 'dev'", specifier = ">=10.0.0" },
     { name = "types-toml", marker = "extra == 'dev'", specifier = ">=0.10.8.20240310" },
 ]
-provides-extras = ["test", "dev", "all"]
+provides-extras = ["dev", "all"]
 
 [package.metadata.requires-dev]
 dev = [
-    { name = "black", specifier = ">=24.0.0" },
     { name = "ruff", specifier = ">=0.12.10" },
     { name = "types-toml", specifier = ">=0.10.8.20240310" },
 ]
@@ -2462,12 +2366,14 @@ testing = [
     { name = "napari", extras = ["testing", "pyqt6"] },
     { name = "pytest", specifier = ">=8.4.0" },
     { name = "pytest-asyncio", specifier = ">=0.23.0" },
+    { name = "pytest-benchmark", specifier = ">=4.0.0" },
     { name = "pytest-cov", specifier = ">=4.0.0" },
     { name = "pytest-forked", specifier = ">=1.6.0" },
     { name = "pytest-mock", specifier = ">=3.12.0" },
     { name = "pytest-qt", specifier = ">=4.0.0" },
     { name = "pytest-random-order", specifier = ">=1.1.0" },
-    { name = "tox" },
+    { name = "pytest-timeout", specifier = ">=2.2.0" },
+    { name = "pytest-xdist", specifier = ">=3.5.0" },
 ]
 
 [[package]]
@@ -3519,19 +3425,6 @@ version = "1.9.0"
 source = { registry = "https://pypi.org/simple" }
 sdist = { url = "https://files.pythonhosted.org/packages/30/23/2f0a3efc4d6a32f3b63cdff36cd398d9701d26cda58e3ab97ac79fb5e60d/pyperclip-1.9.0.tar.gz", hash = "sha256:b7de0142ddc81bfc5c7507eea19da920b92252b548b96186caf94a5e2527d310", size = 20961, upload-time = "2024-06-18T20:38:48.401Z" }
 
-[[package]]
-name = "pyproject-api"
-version = "1.9.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "packaging" },
-    { name = "tomli", marker = "python_full_version < '3.11'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/19/fd/437901c891f58a7b9096511750247535e891d2d5a5a6eefbc9386a2b41d5/pyproject_api-1.9.1.tar.gz", hash = "sha256:43c9918f49daab37e302038fc1aed54a8c7a91a9fa935d00b9a485f37e0f5335", size = 22710, upload-time = "2025-05-12T14:41:58.025Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/ef/e6/c293c06695d4a3ab0260ef124a74ebadba5f4c511ce3a4259e976902c00b/pyproject_api-1.9.1-py3-none-any.whl", hash = "sha256:7d6238d92f8962773dd75b5f0c4a6a27cce092a14b623b811dba656f3b628948", size = 13158, upload-time = "2025-05-12T14:41:56.217Z" },
-]
-
 [[package]]
 name = "pyproject-hooks"
 version = "1.2.0"
@@ -3596,6 +3489,11 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b0/1e/c6a28a142f14e735088534cc92951c3f48cccd77cdd4f3b10d7996be420f/pyqt6_sip-13.10.2-cp313-cp313-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:3dde8024d055f496eba7d44061c5a1ba4eb72fc95e5a9d7a0dbc908317e0888b", size = 303833, upload-time = "2025-05-23T12:26:41.075Z" },
     { url = "https://files.pythonhosted.org/packages/89/63/e5adf350c1c3123d4865c013f164c5265512fa79f09ad464fb2fdf9f9e61/pyqt6_sip-13.10.2-cp313-cp313-win_amd64.whl", hash = "sha256:0b097eb58b4df936c4a2a88a2f367c8bb5c20ff049a45a7917ad75d698e3b277", size = 53527, upload-time = "2025-05-23T12:26:42.625Z" },
     { url = "https://files.pythonhosted.org/packages/58/74/2df4195306d050fbf4963fb5636108a66e5afa6dc05fd9e81e51ec96c384/pyqt6_sip-13.10.2-cp313-cp313-win_arm64.whl", hash = "sha256:cc6a1dfdf324efaac6e7b890a608385205e652845c62130de919fd73a6326244", size = 45373, upload-time = "2025-05-23T12:26:43.536Z" },
+    { url = "https://files.pythonhosted.org/packages/23/57/74b4eb7a51b9133958daa8409b55de95e44feb694d4e2e3eba81a070ca20/pyqt6_sip-13.10.2-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:8a76a06a8e5c5b1f17a3f6f3c834ca324877e07b960b18b8b9bbfd9c536ec658", size = 112354, upload-time = "2025-10-08T08:44:00.22Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/cb/fdef02e0d6ee8443a9683a43650d61c6474b634b6ae6e1c6f097da6310bf/pyqt6_sip-13.10.2-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9128d770a611200529468397d710bc972f1dcfe12bfcbb09a3ccddcd4d54fa5b", size = 323488, upload-time = "2025-10-08T08:44:01.965Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/5b/8ede8d6234c3ea884cbd097d7d47ff9910fb114efe041af62b4453acd23b/pyqt6_sip-13.10.2-cp314-cp314-manylinux_2_5_x86_64.manylinux1_x86_64.whl", hash = "sha256:d820a0fae7315932c08f27dc0a7e33e0f50fe351001601a8eb9cf6f22b04562e", size = 303881, upload-time = "2025-10-08T08:44:04.086Z" },
+    { url = "https://files.pythonhosted.org/packages/be/44/b5e78b072d1594643b0f1ff348f2bf54d4adb5a3f9b9f0989c54e33238d6/pyqt6_sip-13.10.2-cp314-cp314-win_amd64.whl", hash = "sha256:3213bb6e102d3842a3bb7e59d5f6e55f176c80880ff0b39d0dac0cfe58313fb3", size = 55098, upload-time = "2025-10-08T08:44:08.943Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/91/357e9fcef5d830c3d50503d35e0357818aca3540f78748cc214dfa015d00/pyqt6_sip-13.10.2-cp314-cp314-win_arm64.whl", hash = "sha256:ce33ff1f94960ad4b08035e39fa0c3c9a67070bec39ffe3e435c792721504726", size = 46088, upload-time = "2025-10-08T08:44:10.014Z" },
 ]
 
 [[package]]
@@ -4869,28 +4767,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/55/a7/535c44c7bea4578e48281d83c615219f3ab19e6abc67625ef637c73987be/tornado-6.5.1-cp39-abi3-win_arm64.whl", hash = "sha256:02420a0eb7bf617257b9935e2b754d1b63897525d8a289c9d65690d580b4dcf7", size = 443596, upload-time = "2025-05-22T18:15:37.433Z" },
 ]
 
-[[package]]
-name = "tox"
-version = "4.27.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "cachetools" },
-    { name = "chardet" },
-    { name = "colorama" },
-    { name = "filelock" },
-    { name = "packaging" },
-    { name = "platformdirs" },
-    { name = "pluggy" },
-    { name = "pyproject-api" },
-    { name = "tomli", marker = "python_full_version < '3.11'" },
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
-    { name = "virtualenv" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/a5/b7/19c01717747076f63c54d871ada081cd711a7c9a7572f2225675c3858b94/tox-4.27.0.tar.gz", hash = "sha256:b97d5ecc0c0d5755bcc5348387fef793e1bfa68eb33746412f4c60881d7f5f57", size = 198351, upload-time = "2025-06-17T15:17:50.585Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/c1/3a/30889167f41ecaffb957ec4409e1cbc1d5d558a5bbbdfb734a5b9911930f/tox-4.27.0-py3-none-any.whl", hash = "sha256:2b8a7fb986b82aa2c830c0615082a490d134e0626dbc9189986da46a313c4f20", size = 173441, upload-time = "2025-06-17T15:17:48.689Z" },
-]
-
 [[package]]
 name = "tqdm"
 version = "4.67.1"