feat(plugin): make the live Blender session an opt-in second plugin

Since 4be2cea every install of the core plugin launched the Blender Lab MCP
server at session start: an error on every session without uv, a duplicate
blender server for anyone who had registered it themselves, and nothing at
all on 4.5 LTS, where the add-on cannot run.

The server now lives in live-session/, a second plugin in the same
marketplace, blender-live-session (Claude Code installs it from plugin-dist
through a git-subdir source; Cursor from ./live-session). The core manifests
declare no mcpServers, and check_manifest_meta and the dist build fail if one
comes back.

The pin now covers the dependencies too: uvx gets --exclude-newer set to the
day after the reviewed commit, because uvx ignores the upstream uv.lock and
would otherwise resolve mcp, pyyaml and docutils fresh on each install.
mcp-server.yml runs tests/check_mcp_server.py (install + initialize +
tools/list over stdio, no Blender needed) weekly and on every change to
live-session/, and opens an issue when a scheduled run fails. Verified
locally: 26 tools at the pin; a zeroed SHA exits 1.

The plugin also ships the live-blender-session skill, which carries the
CLAUDE.md live-vs-headless policy to plugin users: read with the summary and
screenshot tools first, save before mutating, return a result dict, and
prove anything worth keeping with blender --background. README, landing,
llms.txt, ROADMAP, AGENTS and CONTRIBUTING describe the new layout.

Closes #483
Closes #484
Closes #485
Refs #491

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

Author: TMHSDigital

.claude-plugin/marketplace.json

@@ -14,6 +14,17 @@
         "ref": "plugin-dist"
       },
       "version": "0.153.0"
+    },
+    {
+      "name": "blender-live-session",
+      "description": "Opt-in companion to blender-developer-tools: registers the official Blender Lab MCP server so the agent can inspect and drive a running Blender 5.1+ (needs uv and the MCP add-on), plus a skill for reading the scene before mutating it and proving changes headless",
+      "source": {
+        "source": "git-subdir",
+        "url": "TMHSDigital/Blender-Developer-Tools",
+        "path": "live-session",
+        "ref": "plugin-dist"
+      },
+      "version": "0.153.0"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -9,7 +9,6 @@
   "homepage": "https://tmhsdigital.github.io/Blender-Developer-Tools/",
   "repository": "https://github.com/TMHSDigital/Blender-Developer-Tools",
   "license": "CC-BY-NC-ND-4.0 AND MIT",
-  "mcpServers": "./mcp.json",
   "skills": [
     "./claude/skills/"
   ],

.cursor-plugin/marketplace.json

@@ -11,6 +11,11 @@
       "name": "blender-developer-tools",
       "source": "./",
       "description": "Blender Python skills and rules for AI agents: correct bpy for Blender 5.2 LTS and 4.5 LTS (Slotted Actions, temp_override, Extensions, bmesh, Geometry Nodes, glTF/FBX export), backed by smoke-tested examples"
+    },
+    {
+      "name": "blender-live-session",
+      "source": "./live-session",
+      "description": "Opt-in companion to blender-developer-tools: registers the official Blender Lab MCP server so the agent can inspect and drive a running Blender 5.1+ (needs uv and the MCP add-on), plus a skill for reading the scene before mutating it and proving changes headless"
     }
   ]
 }

.cursor-plugin/plugin.json

@@ -19,7 +19,6 @@
     "blender-addon",
     "blender-python"
   ],
-  "mcpServers": "./mcp.json",
   "skills": [
     "skills/addon-scaffolding/SKILL.md",
     "skills/ai-mesh-cleanup/SKILL.md",

.github/scripts/plugin-content-changed.sh

@@ -5,9 +5,9 @@
 #
 # Plugin content is every path scripts/build_plugin_dist.py ships (its
 # --list-paths: skills/, claude/, rules/, snippets/, templates/, the manifests,
-# mcp.json, LICENSE), so the list has one owner (#494). release.yml cuts a
+# live-session/, LICENSE), so the list has one owner (#494). release.yml cuts a
 # patch release when this says yes even if no commit subject is feat:/fix:, so
-# a `docs:` correction to a skill or a pin bump in mcp.json still reaches
+# a `docs:` correction to a skill or an MCP pin bump in live-session/ reaches
 # plugin users (#350). Exit 2 if the path list cannot be read. PYTHON
 # overrides the interpreter (default python3).
 set -euo pipefail

.github/scripts/release_notes.py

@@ -8,7 +8,7 @@
 
 - **For agents and users**: commits that touched what the plugin ships
   (scripts/build_plugin_dist.py DIRS + FILES: skills/, rules/, snippets/,
-  templates/, claude/, the manifests, mcp.json, LICENSE), grouped Features, Fixes,
+  templates/, claude/, live-session/, the manifests, LICENSE), grouped Features, Fixes,
   Other. This is what a plugin user gets from the update, so it leads.
 - **Maintenance**: everything else (CI, tests, the site and gallery,
   showcase pieces, examples, docs), in a collapsed <details> block.
@@ -38,7 +38,7 @@
 SKIP = re.compile(r"^chore: bump version to ", re.I)
 # What the plugin ships (scripts/build_plugin_dist.py DIRS + FILES, #494): a
 # change here is a change a plugin user receives, including the manifests and
-# mcp.json.
+# the opt-in live-session plugin.
 USER_DIRS = tuple(d + "/" for d in DIRS)
 USER_FILES = frozenset(FILES)
 NO_USER_CHANGES = ("No changes to the plugin content (skills, rules, snippets, templates, "

.github/workflows/mcp-server.yml

@@ -0,0 +1,74 @@
+name: Pinned MCP server check
+
+# The opt-in blender-live-session plugin launches the Blender Lab MCP server
+# from live-session/mcp.json: uvx, a full commit pin, and --exclude-newer so
+# its dependencies resolve to what was reviewed with that pin (#484). This
+# runs that exact command and speaks MCP over stdio (initialize, tools/list).
+# No Blender is needed: listing tools does not call them. It goes red when the
+# pin stops resolving (upstream history rewrite, repo move) or the server stops
+# starting, before plugin users find out.
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 8 * * 2"   # weekly, Tuesday 08:00 UTC
+  push:
+    branches: [main]
+    paths:
+      - "live-session/**"
+      - "tests/check_mcp_server.py"
+      - ".github/workflows/mcp-server.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "live-session/**"
+      - "tests/check_mcp_server.py"
+      - ".github/workflows/mcp-server.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  handshake:
+    name: Install the pinned server and list its tools
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: python -m pip install "uv==0.8.5"
+
+      - name: Handshake with the server from live-session/mcp.json
+        run: python tests/check_mcp_server.py --timeout 300
+
+  report-scheduled-failure:
+    name: Report a failed weekly check
+    needs: handshake
+    if: always() && github.event_name == 'schedule' && needs.handshake.result != 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      issues: write
+    steps:
+      - name: Open or update the tracking issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          title="Pinned MCP server no longer installs or starts"
+          body="Scheduled run: $RUN_URL
+
+          live-session/mcp.json no longer answers tools/list. Check the upstream repo at the pinned SHA and the dependency resolution under --exclude-newer, then bump or fix the pin (CLAUDE.md, Live MCP vs Headless Harness)."
+          num=$(gh issue list --state open --search "\"$title\" in:title" --json number --jq '.[0].number // empty')
+          if [ -n "$num" ]; then
+            gh issue comment "$num" --body "$body"
+          else
+            gh issue create --title "$title" --body "$body" --label "bug,ci,priority: high"
+          fi

.github/workflows/release.yml

@@ -187,7 +187,10 @@ jobs:
 
           # Claude Code manifests: same version, rewritten via JSON.
           import json
-          for path in ('.claude-plugin/plugin.json', '.claude-plugin/marketplace.json'):
+          # live-session/ is the opt-in blender-live-session plugin (#483).
+          for path in ('.claude-plugin/plugin.json', '.claude-plugin/marketplace.json',
+                       'live-session/.claude-plugin/plugin.json',
+                       'live-session/.cursor-plugin/plugin.json'):
               data = json.load(open(path, encoding='utf-8'))
               if 'version' in data:
                   data['version'] = os.environ['NEW_VERSION']
@@ -217,7 +220,8 @@ jobs:
 
           # Explicit paths only: the files this workflow owns, never `git add -A`.
           git add -- VERSION CHANGELOG.md CLAUDE.md ROADMAP.md \
-            .cursor-plugin/plugin.json .claude-plugin/plugin.json .claude-plugin/marketplace.json
+            .cursor-plugin/plugin.json .claude-plugin/plugin.json .claude-plugin/marketplace.json \
+            live-session/.claude-plugin/plugin.json live-session/.cursor-plugin/plugin.json
           if [ -n "$(git status --porcelain)" ]; then
             echo "::warning::files changed that the release commit does not own:"
             git status --porcelain

.github/workflows/validate.yml

@@ -214,11 +214,24 @@ jobs:
           for key in sorted(set(market) - {'name', 'owner', 'metadata', 'plugins'}):
               errors.append(f'marketplace.json: {key!r} is not in the Cursor marketplace schema')
           entries = market.get('plugins') or []
-          if [e.get('name') for e in entries] != [manifest.get('name')]:
-              errors.append('marketplace.json: must list exactly this plugin by name')
+          live = json.load(open('live-session/.cursor-plugin/plugin.json'))
+          if [e.get('name') for e in entries] != [manifest.get('name'), live.get('name')]:
+              errors.append('marketplace.json: must list this plugin, then the opt-in live-session plugin')
           for e in entries:
               for key in sorted(set(e) - {'name', 'source', 'description', 'minClientVersions'}):
                   errors.append(f'marketplace.json plugin entry: {key!r} not allowed')
+          if len(entries) > 1 and entries[1].get('source') != './live-session':
+              errors.append('marketplace.json: the live-session entry source must be ./live-session')
+
+          # The opt-in live-session plugin (#483): same schema, same VERSION.
+          for key in sorted(set(live) - allowed):
+              errors.append(f'live-session plugin.json: {key!r} is not in the Cursor plugin schema')
+          if live.get('version') != version:
+              errors.append(f"live-session plugin.json version {live.get('version')!r} != VERSION {version!r}")
+          live_skills = sorted(p.replace('\\', '/').removeprefix('live-session/')
+                               for p in glob.glob('live-session/skills/*/SKILL.md'))
+          if sorted(live.get('skills', [])) != live_skills:
+              errors.append(f"live-session plugin.json skills {live.get('skills')} != on disk {live_skills}")
 
           # Every showcase piece names a category the gallery build knows.
           sys.path.insert(0, 'scripts')
@@ -265,14 +278,23 @@ jobs:
               errors.append(f"claude plugin.json version {plugin.get('version')!r} != VERSION {version!r}")
           if plugin.get('name') != 'blender-developer-tools':
               errors.append('claude plugin.json name must be blender-developer-tools')
+          live = json.load(open('live-session/.claude-plugin/plugin.json', encoding='utf-8'))
           entries = market.get('plugins', [])
-          if len(entries) != 1 or entries[0].get('name') != plugin.get('name'):
-              errors.append('marketplace.json must list exactly the one plugin from plugin.json')
-          elif entries[0].get('version') != version:
-              errors.append(f"marketplace.json plugin version {entries[0].get('version')!r} != VERSION {version!r}")
-          elif entries[0].get('source') != {'source': 'github', 'repo': 'TMHSDigital/Blender-Developer-Tools', 'ref': 'plugin-dist'}:
-              errors.append('marketplace.json plugin source must be the plugin-dist branch '
-                            '(github TMHSDigital/Blender-Developer-Tools, ref plugin-dist)')
+          if [e.get('name') for e in entries] != [plugin.get('name'), live.get('name')]:
+              errors.append('marketplace.json must list the core plugin, then blender-live-session')
+          else:
+              want_sources = (
+                  {'source': 'github', 'repo': 'TMHSDigital/Blender-Developer-Tools', 'ref': 'plugin-dist'},
+                  {'source': 'git-subdir', 'url': 'TMHSDigital/Blender-Developer-Tools',
+                   'path': 'live-session', 'ref': 'plugin-dist'},
+              )
+              for entry, want in zip(entries, want_sources):
+                  if entry.get('version') != version:
+                      errors.append(f"marketplace.json {entry['name']} version {entry.get('version')!r} != VERSION {version!r}")
+                  if entry.get('source') != want:
+                      errors.append(f"marketplace.json {entry['name']} source must be {want} (the plugin-dist branch)")
+          if live.get('version') != version:
+              errors.append(f"live-session claude plugin.json version {live.get('version')!r} != VERSION {version!r}")
 
           # Claude Code discovers skills/<name>/SKILL.md plus every extra
           # directory in plugin.json "skills" (the generated blender-rules

AGENTS.md

@@ -15,7 +15,7 @@ repeats the other.
 
 Skills, rules, snippets, starter templates, and runnable smoke-gated examples
 for Blender Python development. The repo targets **Blender 5.2 LTS** (current
-stable) with a **Blender 4.5 LTS** fallback. **Blender 5.1** is prior stable. The repo ships no MCP server of its own; the plugin's `mcp.json` registers the upstream Blender Lab server (pinned commit, launched with `uvx`) for optional live sessions. It ships
+stable) with a **Blender 4.5 LTS** fallback. **Blender 5.1** is prior stable. The repo ships no MCP server of its own; the opt-in `blender-live-session` plugin (`live-session/`) registers the upstream Blender Lab server (pinned commit and `--exclude-newer`, launched with `uvx`) for live sessions. It ships
 a `.cursor-plugin/plugin.json` manifest so the ecosystem drift checker
 classifies it as a `cursor-plugin`. This is content the AI loads when the user
 asks Blender questions or works on Blender add-ons in Cursor or Claude Code.