npm - davinci-resolve-mcp - Versions diffs - 2.35.1 → 2.36.0 - Mend

davinci-resolve-mcp 2.35.1 → 2.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/CHANGELOG.md +29 -0
package/README.md +1 -1
package/docs/SKILL.md +2 -0
package/install.py +1 -1
package/package.json +1 -1
package/src/analysis_dashboard.py +128 -1
package/src/granular/common.py +1 -1
package/src/server.py +34 -7
package/src/utils/mcp_transport.py +128 -0
package/src/utils/readback.py +21 -0

package/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,35 @@
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
+## What's New in v2.36.0
+Optional networked transport — run the MCP server over the network, safely, with
+control-panel management. Local stdio remains the default and is unchanged.
+- **Added** `--transport stdio|sse|streamable-http` (default `stdio`). The networked
+  modes bind to **loopback (127.0.0.1) by default** and **require a bearer token** on
+  every request (from `$DAVINCI_MCP_TOKEN`, or generated + logged at startup). A
+  non-loopback bind logs a loud security warning. stdio is untouched; you can run a
+  local stdio instance and a networked instance against the same Resolve at once.
+- **Added** control-panel management (Setup → MCP): a Transport card showing the live
+  mode / URL / token / loopback status, with Start/Stop buttons (loopback-only). Backed
+  by `/api/mcp/transport/{start,stop}` and a transport field on `/api/mcp/status`.
+- The page-switch lock (v2.34.1) already serializes concurrent page switches across the
+  local and networked instances.
+## What's New in v2.35.2
+Verification observability and a validator consolidation.
+- **Added** `resolve_control(action="verification_stats")` returns a
+  process-level tally of readback-verification outcomes
+  (verified / contradicted / unverified) since server start. A rising
+  `contradicted` count means the Resolve API reported success but a readback
+  disagreed. No connection required.
+- **Changed** `open_page` now validates its `page` argument through the declarative
+  contract layer (`contracts.validate`) instead of a hand-written enum check —
+  behavior unchanged; part of folding scattered validation into one place.
 ## What's New in v2.35.1
 - **Added** `media_pool_item(action="extract_frames", clip_id, timestamps, output_dir?)`

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
-[![Version](https://img.shields.io/badge/version-2.35.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.36.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-32%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md CHANGED Viewed

@@ -320,6 +320,8 @@ Key actions:
 - `get_version` — returns `{product, version, version_string}`
 - `api_truth(query?)` — look up behaviorally-verified facts about quirky/unreliable
   Resolve API behavior (no connection needed); filter by substring
+- `verification_stats` — readback-verification tally (verified/contradicted/
+  unverified) since server start (no connection needed)
 - `get_page` / `open_page(page)` — read or switch the active page
 - `get_keyframe_mode` / `set_keyframe_mode(mode)`
 - `get_fairlight_presets` — Resolve 20.2.2+; returns available Fairlight

package/install.py CHANGED Viewed

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 # ─── Version ──────────────────────────────────────────────────────────────────
-VERSION = "2.35.1"
+VERSION = "2.36.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.35.1",
+  "version": "2.36.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py CHANGED Viewed

@@ -5495,7 +5495,36 @@ HTML = r"""<!doctype html>
             <span>${apiOk && libOk ? 'Auto-detected from standard install paths' : 'Install via install.py if paths cannot be detected'}</span>
           </div>
         </div>`;
-      setHtml('diagnosticsMcpServer', serverCard + resolveCard);
+      const tr = data.transport || { networked: false, mode: 'stdio (local)' };
+      const trPill = tr.networked
+        ? (tr.loopback ? statusPill('pill-ok', 'Networked · loopback')
+                       : statusPill('pill-warn', 'Networked · EXPOSED'))
+        : statusPill('pill-ok', 'Local (stdio)');
+      const transportCard = `
+        <div class="diag-card">
+          <div class="diag-card-header">
+            <div class="diag-card-title">${DIAG_ICONS.connection}Transport</div>
+            ${trPill}
+          </div>
+          <div class="diag-card-rows">
+            ${diagRow('Mode', tr.mode || 'stdio (local)')}
+            ${tr.networked ? diagRow('URL', tr.url || '—') : ''}
+            ${tr.networked ? diagRow('Auth', tr.has_token ? 'Bearer token required' : 'NONE') : ''}
+            ${tr.networked && tr.token ? diagRow('Token', tr.token) : ''}
+          </div>
+          <div class="diag-card-footer">
+            <span>${tr.networked
+              ? (tr.loopback ? 'Reachable on this machine only; every request needs the bearer token.'
+                             : 'WARNING: bound to a non-loopback host — exposed on the network.')
+              : 'Default. Networked access is opt-in (launch with --transport sse|streamable-http).'}</span>
+            <button class="secondary transport-toggle-btn" data-transport-action="${tr.networked ? 'stop' : 'start'}">
+              ${tr.networked ? 'Stop networked' : 'Start networked'}</button>
+          </div>
+        </div>`;
+      setHtml('diagnosticsMcpServer', serverCard + resolveCard + transportCard);
+      serverEl.querySelectorAll('.transport-toggle-btn').forEach(btn => {
+        btn.addEventListener('click', () => toggleTransport(btn.dataset.transportAction, btn).catch(alertError));
+      });
       const clients = data.clients || [];
       if (!clients.length) {
@@ -5592,6 +5621,28 @@ HTML = r"""<!doctype html>
       }
     }
+    async function toggleTransport(action, btn) {
+      if (action === 'start') {
+        const proceed = await brandedConfirm({
+          kicker: 'MCP Transport',
+          title: 'Start networked transport?',
+          body: 'Starts a second MCP server instance over streamable-http, bound to loopback (127.0.0.1) and protected by a bearer token. Local stdio is unaffected. The connection URL + token will appear here.',
+          confirmLabel: 'Start',
+          cancelLabel: 'Cancel',
+        });
+        if (!proceed) return;
+      }
+      const original = btn?.textContent;
+      if (btn) { btn.disabled = true; btn.textContent = action === 'start' ? 'Starting…' : 'Stopping…'; }
+      try {
+        const ep = action === 'start' ? '/api/mcp/transport/start' : '/api/mcp/transport/stop';
+        await api(ep, { method: 'POST', body: '{}' });
+      } finally {
+        if (btn) { btn.disabled = false; btn.textContent = original; }
+        await refreshMcpStatus();
+      }
+    }
     function renderControlPanels() {
       renderOverview();
       renderDiagnostics();
@@ -13483,9 +13534,73 @@ def _mcp_status_payload() -> Dict[str, Any]:
             "resolve_lib_detected": bool(paths.get("lib_path")),
         },
         "clients": clients_out,
+        "transport": _transport_status(),
     }
+def _transport_status() -> Dict[str, Any]:
+    """Live networked-transport status (or local-only) for the MCP diagnostics card."""
+    try:
+        from src.utils.mcp_transport import read_transport_state
+    except Exception:
+        return {"networked": False, "mode": "stdio (local)"}
+    state = read_transport_state()
+    if not state:
+        return {"networked": False, "mode": "stdio (local)"}
+    return {
+        "networked": True,
+        "mode": state.get("transport"),
+        "url": state.get("url"),
+        "loopback": state.get("loopback", True),
+        "has_token": bool(state.get("token")),
+        "token": state.get("token"),
+        "pid": state.get("pid"),
+    }
+def _transport_start() -> Dict[str, Any]:
+    """Spawn a networked MCP instance (streamable-http, loopback + token)."""
+    import subprocess as _sp
+    from src.utils.mcp_transport import read_transport_state
+    if read_transport_state():
+        return {"success": False, "error": "A networked transport instance is already running."}
+    paths = _resolve_mcp_paths()
+    py, script = paths.get("python_path"), paths.get("server_path")
+    if not py or not script:
+        return {"success": False, "error": "Could not resolve the Python interpreter or server script path."}
+    try:
+        _sp.Popen(
+            [py, script, "--transport", "streamable-http"],
+            stdin=_sp.DEVNULL, stdout=_sp.DEVNULL, stderr=_sp.DEVNULL,
+            start_new_session=True,
+        )
+    except OSError as exc:
+        return {"success": False, "error": f"Failed to launch: {exc}"}
+    import time as _t
+    for _ in range(15):
+        _t.sleep(0.2)
+        if read_transport_state():
+            return {"success": True, "transport": _transport_status()}
+    return {"success": True, "note": "Launch initiated; status will appear shortly."}
+def _transport_stop() -> Dict[str, Any]:
+    """Stop the running networked MCP instance via its state-file PID."""
+    import signal as _sig
+    from src.utils.mcp_transport import read_transport_state, clear_transport_state
+    state = read_transport_state()
+    if not state:
+        return {"success": True, "note": "No networked transport running."}
+    pid = state.get("pid")
+    if isinstance(pid, int):
+        try:
+            os.kill(pid, _sig.SIGTERM)
+        except (OSError, ProcessLookupError):
+            pass
+    clear_transport_state()
+    return {"success": True}
 def _mcp_install_payload(client_id: str) -> Dict[str, Any]:
     """Write the MCP entry for one client by delegating to install.write_client_config."""
     installer, error = _load_installer_module()
@@ -14304,6 +14419,18 @@ class Handler(BaseHTTPRequestHandler):
                 return
             self._json(_mcp_uninstall_payload(client_id))
             return
+        if path == "/api/mcp/transport/start":
+            if not _request_is_loopback(self):
+                self._json({"success": False, "error": "Transport management is loopback-only."}, HTTPStatus.FORBIDDEN)
+                return
+            self._json(_transport_start())
+            return
+        if path == "/api/mcp/transport/stop":
+            if not _request_is_loopback(self):
+                self._json({"success": False, "error": "Transport management is loopback-only."}, HTTPStatus.FORBIDDEN)
+                return
+            self._json(_transport_stop())
+            return
         if path == "/api/jobs":
             paths = body.get("paths") or []
             if isinstance(paths, str):

package/src/granular/common.py CHANGED Viewed

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
-VERSION = "2.35.1"
+VERSION = "2.36.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py CHANGED Viewed

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
-VERSION = "2.35.1"
+VERSION = "2.36.0"
 import base64
 import os
@@ -48,7 +48,7 @@ from src.utils.contracts import validate as _validate_params
 from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.page_lock import open_page_serialized as _open_page_serialized
 from src.utils.proc import safe_run
-from src.utils.readback import verify_by_readback
+from src.utils.readback import verify_by_readback, verification_stats as _verification_stats
 from src.utils.update_check import (
     check_for_updates,
     clear_update_prompt_preferences,
@@ -10632,6 +10632,8 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       clear_mcp_update_preferences() -> {success, version, update, decision}
       api_truth(query?) -> {verified_on, count, facts}  — look up behaviorally-verified
         facts about quirky/unreliable Resolve API behavior (no connection needed).
+      verification_stats() -> {stats}  — readback-verification tally
+        (verified/contradicted/unverified) since server start (no connection needed).
       get_page() -> {page}
       open_page(page) -> {success}  — page: edit, cut, color, fusion, fairlight, deliver
       get_keyframe_mode() -> {mode}
@@ -10656,6 +10658,11 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     if action == "api_truth":
         facts = lookup_api_truth(p.get("query"))
         return {"verified_on": _API_TRUTH_VERIFIED_ON, "count": len(facts), "facts": facts}
+    if action == "verification_stats":
+        # Process-level readback-verification tally — no connection needed.
+        stats = _verification_stats()
+        return {"stats": stats, "note": "Counts since server start. A rising "
+                "'contradicted' count means the API reported success but a readback disagreed."}
     # Control-panel actions don't require Resolve to be running.
     if action == "open_control_panel":
@@ -10720,12 +10727,15 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_page":
         return {"page": r.GetCurrentPage()}
     elif action == "open_page":
-        valid_pages = ["media", "cut", "edit", "color", "fusion", "fairlight", "deliver"]
-        if p["page"] not in valid_pages:
-            return _err(f"Invalid page '{p['page']}'. Valid pages: {', '.join(valid_pages)}")
+        err, clean = _validate_params(p, {
+            "page": {"enum": ["media", "cut", "edit", "color", "fusion", "fairlight", "deliver"],
+                     "required": True},
+        })
+        if err:
+            return _err(err)
         # Serialize page switches so concurrent agents can't flip the single
         # globally-active page underneath each other.
-        return {"success": bool(_open_page_serialized(r, p["page"]))}
+        return {"success": bool(_open_page_serialized(r, clean["page"]))}
     elif action == "get_keyframe_mode":
         return {"mode": r.GetKeyframeMode()}
     elif action == "set_keyframe_mode":
@@ -10746,7 +10756,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
             return missing
         r.DisableBackgroundTasksForCurrentResolveSession()
         return _ok()
-    return _unknown(action, ["launch","get_version","api_truth","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","get_version","api_truth","verification_stats","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────
@@ -21031,5 +21041,22 @@ if __name__ == "__main__":
         run_fastmcp_stdio(granular_mcp)
         sys.exit(0)
+    # --transport stdio (default) | sse | streamable-http. Networked modes bind
+    # loopback by default and require a bearer token (see src/utils/mcp_transport).
+    transport = "stdio"
+    if "--transport" in sys.argv:
+        _i = sys.argv.index("--transport")
+        if _i + 1 < len(sys.argv):
+            transport = sys.argv[_i + 1]
+            del sys.argv[_i:_i + 2]
+    if transport in ("sse", "streamable-http"):
+        from src.utils.mcp_transport import run_networked
+        logger.info(f"Starting DaVinci Resolve MCP Server ({transport} transport)")
+        run_networked(mcp, transport)
+        sys.exit(0)
+    if transport != "stdio":
+        logger.error(f"Unknown --transport {transport!r}; use stdio|sse|streamable-http")
+        sys.exit(2)
     logger.info(f"Starting DaVinci Resolve MCP Server (32 compound tools)")
     run_fastmcp_stdio(mcp)

package/src/utils/mcp_transport.py ADDED Viewed

@@ -0,0 +1,128 @@
+"""Networked transport for the MCP server (opt-in via --transport).
+stdio remains the default. The `sse` and `streamable-http` modes bind to
+loopback (127.0.0.1) by default and REQUIRE a bearer token on every request, so
+turning networking on never silently exposes Resolve. The token comes from
+``$DAVINCI_MCP_TOKEN`` or is generated and logged at startup. A small state file
+lets the control panel show the live connection URL + token.
+Security posture:
+- Default host is loopback; a non-loopback bind logs a loud warning.
+- Every HTTP request must carry ``Authorization: Bearer <token>`` (constant-time
+  compared); otherwise 401.
+- stdio (the default transport) is unaffected by anything here.
+"""
+import json
+import logging
+import os
+import secrets
+import tempfile
+import time
+logger = logging.getLogger("davinci-resolve-mcp")
+TRANSPORT_STATE_PATH = os.path.join(
+    tempfile.gettempdir(), "davinci_resolve_mcp_transport.json"
+)
+LOOPBACK_HOSTS = {"127.0.0.1", "localhost", "::1"}
+def resolve_token():
+    """Return (token, was_generated). Honors $DAVINCI_MCP_TOKEN."""
+    tok = os.environ.get("DAVINCI_MCP_TOKEN")
+    if tok:
+        return tok, False
+    return secrets.token_urlsafe(24), True
+def _auth_middleware_cls(token):
+    from starlette.middleware.base import BaseHTTPMiddleware
+    from starlette.responses import JSONResponse
+    expected = f"Bearer {token}"
+    class BearerAuth(BaseHTTPMiddleware):
+        async def dispatch(self, request, call_next):
+            provided = request.headers.get("authorization", "")
+            if not secrets.compare_digest(provided, expected):
+                return JSONResponse(
+                    {"error": "unauthorized: Authorization: Bearer <token> required"},
+                    status_code=401,
+                )
+            return await call_next(request)
+    return BearerAuth
+def write_transport_state(transport, host, port, token):
+    try:
+        with open(TRANSPORT_STATE_PATH, "w", encoding="utf-8") as fh:
+            json.dump({
+                "transport": transport,
+                "host": host,
+                "port": port,
+                "url": f"http://{host}:{port}",
+                "token": token,
+                "loopback": host in LOOPBACK_HOSTS,
+                "pid": os.getpid(),
+                "started_at": time.time(),
+            }, fh)
+    except OSError as exc:
+        logger.warning("could not write transport state: %s", exc)
+def clear_transport_state():
+    try:
+        os.remove(TRANSPORT_STATE_PATH)
+    except OSError:
+        pass
+def read_transport_state():
+    """Return the live transport state dict, or None if no networked instance.
+    Treats a state file whose pid is no longer alive as stale (returns None).
+    """
+    try:
+        with open(TRANSPORT_STATE_PATH, encoding="utf-8") as fh:
+            state = json.load(fh)
+    except (OSError, ValueError):
+        return None
+    pid = state.get("pid")
+    if isinstance(pid, int):
+        try:
+            os.kill(pid, 0)
+        except (OSError, ProcessLookupError):
+            return None
+    return state
+def run_networked(mcp, transport):
+    """Serve `mcp` over an authenticated HTTP transport ('sse'|'streamable-http')."""
+    import uvicorn
+    host = os.environ.get("DAVINCI_MCP_HOST") or mcp.settings.host or "127.0.0.1"
+    port = int(os.environ.get("DAVINCI_MCP_PORT") or mcp.settings.port or 8000)
+    mcp.settings.host = host
+    mcp.settings.port = port
+    token, generated = resolve_token()
+    app = mcp.sse_app() if transport == "sse" else mcp.streamable_http_app()
+    app.add_middleware(_auth_middleware_cls(token))
+    if host not in LOOPBACK_HOSTS:
+        logger.warning(
+            "SECURITY: MCP %s transport bound to NON-loopback host %r — Resolve "
+            "control is exposed on the network. Ensure this is intended.",
+            transport, host,
+        )
+    logger.info("MCP %s transport: http://%s:%s (bearer token required)",
+                transport, host, port)
+    if generated:
+        logger.info("Generated bearer token (set $DAVINCI_MCP_TOKEN to pin it): %s", token)
+    write_transport_state(transport, host, port, token)
+    try:
+        uvicorn.run(app, host=host, port=port, log_level="warning")
+    finally:
+        clear_transport_state()

package/src/utils/readback.py CHANGED Viewed

@@ -16,6 +16,21 @@ from typing import Any, Callable, Dict, Optional
 logger = logging.getLogger("davinci-resolve-mcp")
+# Process-level tally of verification outcomes — lightweight observability into
+# how often the Resolve API's self-reported success matches reality. A rising
+# `contradicted` count is the signal worth watching.
+_STATS = {"total": 0, "verified": 0, "contradicted": 0, "unverified": 0}
+def verification_stats():
+    """Return a copy of the process-level verification tally."""
+    return dict(_STATS)
+def reset_verification_stats():
+    for k in _STATS:
+        _STATS[k] = 0
 def verify_by_readback(
     mutate: Callable[[], Any],
@@ -56,6 +71,7 @@ def verify_by_readback(
     # A contradiction — reported success but the readback disagrees — is the
     # signal worth surfacing loudly.
+    _STATS["total"] += 1
     if result.get("success_raw") and not result.get("verified"):
         logger.warning(
             "readback contradiction%s: API reported success but post-state "
@@ -64,7 +80,12 @@ def verify_by_readback(
             f" (intent={intent})" if intent else "",
         )
         result["contradiction"] = True
+        _STATS["contradicted"] += 1
     else:
         result["contradiction"] = False
+        if result.get("verified"):
+            _STATS["verified"] += 1
+        else:
+            _STATS["unverified"] += 1
     return result