@hybridlabor-api/aos 4.4.1 → 4.4.2-beta.0

package/mcps/davinci-mcp-professional/USING.md

@@ -1,301 +0,0 @@
-# Developer Guide — DaVinci MCP Professional
-
-This document covers everything needed to work on the project from source,
-including setup, running, building, testing, and contributing.
-
-For end-user installation, see [README.md](README.md).
-For full API documentation, see `docs/html/index.html` or regenerate with
-`doxygen Doxyfile`.
-
----
-
-## Prerequisites
-
-- Python 3.10 or later, **installed system-wide** (the installer from
-  [python.org](https://www.python.org/downloads/) with "Add to PATH" and
-  "Install for all users" selected)
-- [uv](https://docs.astral.sh/uv/getting-started/installation/)
-- DaVinci Resolve Studio, installed and running when using the server
-  (the free edition does not support external scripting)
-- Git, configured with GPG signing (required for commits — see CONTRIBUTING.md)
-
----
-
-## Development Setup
-
-```bash
-git clone https://github.com/Positronikal/davinci-mcp-professional.git
-cd davinci-mcp-professional
-uv venv --python <system-python>
-uv sync
-```
-
-**Windows — important:** The `--python` flag must point to the
-system-installed Python executable.  DaVinci Resolve's `fusionscript.dll`
-discovers Python through the Windows registry
-(`HKLM\SOFTWARE\Python\PythonCore`) and loads `python3.dll` by full path
-from that installation.  If the virtual environment uses a *different*
-Python (e.g. one downloaded by `uv` automatically), two Python runtimes
-end up in the same process and the server crashes.
-
-To find your system Python, run:
-
-```powershell
-py -0p          # Windows Python Launcher — lists installed versions and paths
-```
-
-Then create the venv:
-
-```bash
-uv venv --python "C:\Program Files\Python314\python.exe"   # adjust to your version
-uv sync
-```
-
-On **macOS / Linux**, `uv venv` with no `--python` flag works if the
-default `python3` is a system-wide installation.
-
-`uv sync` installs all runtime and dev dependencies from `uv.lock` into `.venv`.
-
----
-
-## Running from Source
-
-The project has two entry points that serve different purposes:
-
-**`mcp_server.py` — MCP server (for AI clients)**
-
-```bash
-uv run python mcp_server.py
-```
-
-This is the entry point that MCP clients (Claude Desktop, Gemini CLI, etc.)
-launch as a subprocess. It speaks the MCP stdio protocol with no console
-output. Point your `claude_desktop_config.json` at this file.
-
-**`main.py` — Interactive CLI (for humans)**
-
-```bash
-uv run python main.py
-uv run python main.py --debug
-```
-
-This wraps the same MCP server with a human-friendly terminal interface:
-a colored startup banner, prerequisite checks (is Resolve running? is
-PYTHONPATH set?), and `--debug` / `--skip-checks` flags. Use this when
-running the server manually to verify connectivity or troubleshoot issues.
-
----
-
-## MCP Client Configuration for Development
-
-Point your MCP client at the venv interpreter and `mcp_server.py`. Example
-for Claude Desktop (`claude_desktop_config.json`):
-
-**Windows:**
-```json
-{
-  "mcpServers": {
-    "davinci-resolve": {
-      "name": "DaVinci MCP Professional",
-      "command": "C:\\path\\to\\davinci-mcp-professional\\.venv\\Scripts\\python.exe",
-      "args": ["C:\\path\\to\\davinci-mcp-professional\\mcp_server.py"]
-    }
-  }
-}
-```
-
-**macOS:**
-```json
-{
-  "mcpServers": {
-    "davinci-resolve": {
-      "name": "DaVinci MCP Professional",
-      "command": "/path/to/davinci-mcp-professional/.venv/bin/python",
-      "args": ["/path/to/davinci-mcp-professional/mcp_server.py"]
-    }
-  }
-}
-```
-
-A ready-to-edit template is at `claude_desktop_config_template.json`.
-
----
-
-## PyInstaller Builds
-
-Build standalone executables (single-directory bundles):
-
-```bash
-uv sync --extra build      # install PyInstaller into the venv
-uv run python build.py     # build both targets
-```
-
-Output:
-
-```
-dist/davinci-mcp-server/davinci-mcp-server.exe   # MCP server (for AI clients)
-dist/davinci-mcp/davinci-mcp.exe                 # Interactive CLI (for humans)
-```
-
-These mirror the two entry points described in **Running from Source** above:
-
-- **`davinci-mcp-server.exe`** — the MCP stdio server. Use this in MCP client
-  configurations when distributing to end users who do not have Python
-  installed.
-- **`davinci-mcp.exe`** — the interactive CLI with prerequisite checks and
-  colored output. Useful for manual testing and troubleshooting.
-
----
-
-## Project Structure
-
-```
-davinci-mcp-professional/
-├── mcp_server.py              # Pure MCP stdio server entry point
-├── main.py                    # Interactive CLI entry point
-├── build.py                   # PyInstaller build script
-├── src/davinci_mcp/
-│   ├── __init__.py            # Package init; imports __version__ from hatch-vcs
-│   ├── cli.py                 # click CLI, prerequisite checks, banner
-│   ├── server.py              # MCP server: registers tool/resource handlers
-│   ├── resolve_client.py      # DaVinci Resolve API wrapper
-│   ├── types.py               # runtime_checkable Protocol types for Resolve objects
-│   ├── tools/__init__.py      # All 13 MCP tool definitions (name, schema)
-│   ├── resources/__init__.py  # All 7 MCP resource definitions (URI, schema)
-│   └── utils/
-│       ├── __init__.py
-│       └── platform.py        # Platform detection, PYTHONPATH setup, process check
-├── tests/
-│   ├── conftest.py
-│   └── test_security.py
-├── docs/                      # Doxygen-generated HTML (tracked in git)
-├── pyproject.toml
-├── uv.lock
-└── Doxyfile
-```
-
----
-
-## Available Tools
-
-| Tool | Description |
-|---|---|
-| `get_version` | DaVinci Resolve version string |
-| `get_current_page` | Currently active page (Edit, Color, etc.) |
-| `switch_page` | Navigate to a page (media/cut/edit/fusion/color/fairlight/deliver) |
-| `list_projects` | All projects in the current database |
-| `get_current_project` | Name of the open project |
-| `open_project` | Open a project by name |
-| `create_project` | Create a new project |
-| `list_timelines` | All timelines in the current project |
-| `get_current_timeline` | Name of the active timeline |
-| `create_timeline` | Create a new empty timeline |
-| `switch_timeline` | Switch to a timeline by name |
-| `list_media_clips` | All clips in the media pool root folder |
-| `import_media` | Import a media file into the media pool |
-
-## Available Resources
-
-| URI | MIME type | Content |
-|---|---|---|
-| `resolve://version` | text/plain | Resolve version string |
-| `resolve://current-page` | text/plain | Active page name |
-| `resolve://projects` | application/json | Project list |
-| `resolve://current-project` | text/plain | Open project name |
-| `resolve://timelines` | application/json | Timeline list |
-| `resolve://current-timeline` | text/plain | Active timeline name |
-| `resolve://media-clips` | application/json | Media pool clip list |
-
----
-
-## Extending the Server
-
-### Adding a new tool
-
-1. Add its definition to `src/davinci_mcp/tools/__init__.py` (name, description,
-   inputSchema).
-2. Add a dispatch branch in `server.py` → `_call_tool()`.
-3. Implement the method in `resolve_client.py`.
-
-### Adding a new resource
-
-1. Add its definition to `src/davinci_mcp/resources/__init__.py` (URI, mimeType).
-2. Add a dispatch branch in `server.py` → `_read_resource()`.
-3. Implement the method in `resolve_client.py`.
-
----
-
-## Testing, Linting, and Type Checking
-
-```bash
-# Run all tests
-uv run pytest
-
-# Run a single test file
-uv run pytest tests/test_security.py -v
-
-# Skip integration tests (requires Resolve running)
-uv run pytest -m "not integration"
-
-# Coverage
-uv run pytest --cov=src/davinci_mcp --cov-report=html
-
-# Lint and format
-uv run ruff check src/ tests/
-uv run ruff format src/ tests/
-
-# Type checking
-uv run pyright
-uv run mypy src/
-
-# Security
-uv run bandit -r src/
-uv run safety check
-```
-
----
-
-## API Documentation
-
-Full Doxygen-generated API documentation is in `docs/html/`:
-
-```bash
-# View locally
-open docs/html/index.html          # macOS
-start docs/html/index.html         # Windows
-
-# Serve with search support
-cd docs/html
-uv run python -m http.server 8000
-# then open http://localhost:8000
-
-# Regenerate after code changes
-doxygen Doxyfile
-```
-
----
-
-## Troubleshooting
-
-**DaVinci Resolve not found**
-- Confirm Resolve is installed in the default location for your OS.
-- On Windows: `C:\Program Files\Blackmagic Design\DaVinci Resolve\`
-- On macOS: `/Applications/DaVinci Resolve/`
-
-**DaVinci Resolve not running**
-- The server requires Resolve to be fully loaded before connecting.
-- Start Resolve first, wait for the UI to appear, then start the server.
-
-**Import errors after setup**
-- Run `uv sync` to ensure all dependencies are installed.
-- Confirm you are running via `uv run python ...` or have activated `.venv`.
-
-**Debug mode**
-```bash
-uv run python main.py --debug
-```
-
-**Dependency conflicts**
-```bash
-uv sync --reinstall
-```

package/mcps/davinci-mcp-professional/VERSION.md

@@ -1,13 +0,0 @@
-# Version
-Refer to the applied git tags for versioning using one of the following commands as appropriate:
-
-- Linux or Macintosh:
-```
-    $ git tag
-```
-...or...
-
-- Windows:
-```
-    > git tag
-```

package/mcps/davinci-mcp-professional/build.py

@@ -1,169 +0,0 @@
-#!/usr/bin/env python3
-"""
-PyInstaller build script for DaVinci MCP Professional.
-
-Produces standalone single-directory bundles in dist/:
-  - davinci-mcp-server/  (pure MCP stdio server, no console noise)
-  - davinci-mcp/         (interactive CLI with prerequisite checks)
-
-Usage:
-  uv run --extra build python build.py
-
-The build extra installs PyInstaller. Alternatively install it manually:
-  uv add --optional build pyinstaller
-"""
-
-import sys
-import os
-from pathlib import Path
-
-try:
-    import PyInstaller.__main__
-except ImportError:
-    print("[ERROR] PyInstaller not found.")
-    print("        Install with: uv run --extra build python build.py")
-    print("        Or manually:  uv add --optional build pyinstaller")
-    sys.exit(1)
-
-ROOT = Path(__file__).parent
-SRC = ROOT / "src"
-
-# ---------------------------------------------------------------------------
-# Hidden imports
-#
-# PyInstaller's static analysis misses modules that are imported at runtime
-# via importlib, __import__(), or behind try/except blocks.
-# ---------------------------------------------------------------------------
-HIDDEN_IMPORTS: list[str] = [
-    # anyio: backends are selected at runtime by the event-loop policy
-    "anyio._backends._asyncio",
-    "anyio._backends._trio",
-    # MCP internals used at connection time
-    "mcp.server.stdio",
-    "mcp.server.models",
-    "mcp.server.lowlevel",
-    "mcp.server.lowlevel.server",
-    "mcp.types",
-    # pydantic v2: validators and core are loaded dynamically
-    "pydantic.deprecated.class_validators",
-    "pydantic_core",
-    # click / colorama: usually auto-detected, listed for safety
-    "click",
-    "colorama",
-    "colorama.initialise",
-    # importlib.metadata: used by __init__.py version fallback
-    "importlib.metadata",
-]
-
-# On Windows, mcp pulls in pywin32 for named-pipe transport
-if sys.platform == "win32":
-    HIDDEN_IMPORTS += ["win32api", "win32con", "win32process", "pywintypes"]
-
-# ---------------------------------------------------------------------------
-# Packages to collect in full (Python files + data files + submodules).
-# Needed for packages that rely heavily on runtime discovery.
-# ---------------------------------------------------------------------------
-COLLECT_ALL: list[str] = [
-    "mcp",
-    "pydantic",
-    "pydantic_core",
-    "anyio",
-    "httpx",
-    "httpx_sse",
-    "starlette",
-    "sse_starlette",
-]
-
-
-def _args(name: str, script: Path) -> list[str]:
-    """Assemble the PyInstaller argument list for one target."""
-    args = [
-        str(script),
-        "--name", name,
-        "--onedir",               # directory bundle — avoids AV false positives
-        "--noconfirm",            # overwrite previous dist without prompting
-        "--distpath", str(ROOT / "dist"),
-        "--workpath", str(ROOT / "build"),
-        "--specpath", str(ROOT / "build"),
-        "--paths", str(SRC),      # ensure src/ is on the analysis path
-    ]
-
-    for imp in HIDDEN_IMPORTS:
-        args += ["--hidden-import", imp]
-
-    for pkg in COLLECT_ALL:
-        args += ["--collect-all", pkg]
-
-    return args
-
-
-def build_target(name: str, script_name: str) -> bool:
-    """
-    Build one executable bundle. Returns True on success.
-
-    The MCP server communicates over stdio (JSON-RPC), so we deliberately
-    do NOT pass --noconsole / --windowed. Hiding the console on Windows
-    would break the stdio transport that Claude Desktop uses.
-    """
-    script = ROOT / script_name
-    if not script.exists():
-        print(f"[ERROR] Entry point not found: {script}")
-        return False
-
-    print(f"\n{'=' * 60}")
-    print(f"  Building: {name}  ({script_name})")
-    print(f"{'=' * 60}\n")
-
-    args = _args(name, script)
-
-    try:
-        PyInstaller.__main__.run(args)
-    except SystemExit as exc:
-        if exc.code != 0:
-            print(f"\n[ERROR] PyInstaller exited with code {exc.code}")
-            return False
-    except Exception as exc:  # noqa: BLE001
-        print(f"\n[ERROR] Build failed: {exc}")
-        return False
-
-    output_dir = ROOT / "dist" / name
-    if output_dir.exists():
-        print(f"\n[OK] Output directory: {output_dir}")
-        return True
-
-    print(f"\n[ERROR] Expected output not found: {output_dir}")
-    return False
-
-
-def main() -> int:
-    targets = [
-        ("davinci-mcp-server", "mcp_server.py"),
-        ("davinci-mcp",        "main.py"),
-    ]
-
-    results: list[tuple[str, bool]] = []
-    for name, script in targets:
-        results.append((name, build_target(name, script)))
-
-    print(f"\n{'=' * 60}")
-    print("  Build Summary")
-    print(f"{'=' * 60}")
-    for name, ok in results:
-        tag = "[OK]    " if ok else "[FAILED]"
-        print(f"  {tag}  dist/{name}/")
-
-    if all(ok for _, ok in results):
-        print(f"\nExecutables are inside their respective dist/ subdirectories.")
-        if sys.platform == "win32":
-            print("  dist/davinci-mcp-server/davinci-mcp-server.exe")
-            print("  dist/davinci-mcp/davinci-mcp.exe")
-        else:
-            print("  dist/davinci-mcp-server/davinci-mcp-server")
-            print("  dist/davinci-mcp/davinci-mcp")
-        return 0
-
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/mcps/davinci-mcp-professional/claude_desktop_config_template.json

@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "davinci-resolve": {
-      "name": "DaVinci MCP Professional",
-      "command": "/path/to/repo/.venv/bin/python",
-      "args": ["/path/to/repo/mcp_server.py"],
-      "_comment_windows": "On Windows use .venv\\Scripts\\python.exe",
-      "_comment_uv": "Run 'uv venv && uv sync' in the repo to create .venv"
-    }
-  }
-}

package/mcps/davinci-mcp-professional/hooks/ci-check.sh

@@ -1,29 +0,0 @@
-#!/usr/bin/env bash
-# Single source of truth for CI/code-quality checks.
-# Invoked locally by hooks/pre-push (blocking) and by .github/workflows/ci.yml
-# (confirmation only) — both run this exact script so local and CI cannot drift.
-set -e
-
-uv sync
-
-echo "Running tests..."
-uv run pytest
-
-echo "Running pyright..."
-uv run pyright
-
-echo "Linting with Ruff..."
-uv run ruff check src/
-uv run ruff format src/ --check
-
-echo "Security vulnerability scan (safety)..."
-uv run safety check --json || echo "Safety check completed with warnings"
-
-echo "SAST with Bandit..."
-uv run bandit -r src/ -f json -o bandit-report.json || echo "Bandit scan completed"
-
-echo "License compliance check..."
-uv run pip-licenses --format=json --output-file=licenses.json
-echo "License compliance check completed"
-
-echo "ci-check passed."

package/mcps/davinci-mcp-professional/hooks/pre-push

@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-# pre-push: local CI/CD gate + informational security review
-#
-# 1. hooks/ci-check.sh — same checks as .github/workflows/ci.yml.
-#    BLOCKING: push aborts on failure. Local pass should reliably predict
-#    the CI verdict for the same commit; GitHub Actions runs are
-#    confirmation, not discovery.
-# 2. Claude Code security review — semantic, informational only.
-#    Findings are advisory; review them but they do not block the push.
-
-set -e
-
-echo "Running local CI checks (hooks/ci-check.sh)..."
-bash hooks/ci-check.sh
-
-echo ""
-echo "Local CI checks passed."
-echo ""
-
-if ! command -v claude >/dev/null 2>&1; then
-    echo "Claude Code not installed. Skipping security review."
-    echo "  Install from: https://claude.ai/download"
-    exit 0
-fi
-
-if [ ! -f ".claude/commands/security-review.md" ]; then
-    echo ".claude/commands/security-review.md not found. Skipping security review."
-    exit 0
-fi
-
-DIFF=$(git diff --merge-base origin/HEAD 2>/dev/null || git diff HEAD~1 2>/dev/null)
-
-if [ -z "$DIFF" ]; then
-    echo "No changes to review."
-    exit 0
-fi
-
-echo "Running security review..."
-PROMPT="$(cat .claude/commands/security-review.md)
-
-DIFF:"
-printf '%s\n%s\n' "$PROMPT" "$DIFF" | claude -p 2>&1 || echo "Security review failed to run (non-blocking)."
-
-echo ""
-echo "Security review complete. Address any findings above before pushing."
-exit 0

package/mcps/davinci-mcp-professional/main.py

@@ -1,40 +0,0 @@
-#!/usr/bin/env python3
-"""
-Main entry point for DaVinci Resolve MCP Server.
-"""
-
-import os
-import sys
-import subprocess
-from pathlib import Path
-
-# Get the current directory and virtual environment
-current_dir = Path(__file__).parent
-venv_dir = current_dir / ".venv"
-
-# Check if we're in the virtual environment (skip when running as a frozen executable)
-if not getattr(sys, 'frozen', False) and not hasattr(sys, 'real_prefix') and not (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
-    # Not in virtual environment, run with the venv python
-    if os.name == "nt":  # Windows
-        venv_python = venv_dir / "Scripts" / "python.exe"
-    else:  # macOS/Linux
-        venv_python = venv_dir / "bin" / "python"
-    
-    if venv_python.exists():
-        print(f"Starting with virtual environment: {venv_python}")
-        # Re-run this script with the virtual environment Python
-        result = subprocess.run([str(venv_python), __file__] + sys.argv[1:], check=False)
-        sys.exit(result.returncode)
-    else:
-        print(f"Virtual environment not found at {venv_dir}")
-        print("Please run 'python setup.py' first")
-        sys.exit(1)
-
-# Add the src directory to Python path
-src_dir = current_dir / "src"
-sys.path.insert(0, str(src_dir))
-
-from davinci_mcp.cli import main
-
-if __name__ == "__main__":
-    main()

package/mcps/davinci-mcp-professional/mcp_server.py

@@ -1,30 +0,0 @@
-#!/usr/bin/env python3
-"""
-Pure MCP server entry point for DaVinci Resolve.
-This version outputs no console messages - only JSON-RPC.
-"""
-
-import asyncio
-import sys
-import os
-from pathlib import Path
-
-# Add the src directory to Python path  
-current_dir = Path(__file__).parent
-src_dir = current_dir / "src"
-sys.path.insert(0, str(src_dir))
-
-from davinci_mcp.server import DaVinciMCPServer
-
-async def main():
-    """Run the MCP server with no console output."""
-    server = DaVinciMCPServer()
-    await server.run()
-
-if __name__ == "__main__":
-    # Suppress all output except JSON-RPC
-    try:
-        asyncio.run(main())
-    except Exception:
-        # Exit silently on any error to avoid polluting JSON-RPC
-        sys.exit(1)