clipwright 0.1.1__tar.gz

clipwright-0.1.1/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.3
+Name: clipwright
+Version: 0.1.1
+Summary: MCP server group wrapping FFmpeg/OTIO. Provides primitives to manipulate video editing workflows from AI agents.
+Author: satoh-y-0323
+Author-email: satoh-y-0323 <shoma.papa.0323@gmail.com>
+License: MIT
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: opentimelineio>=0.18
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Clipwright
+
+> For Japanese, see [README.ja.md](README.ja.md).
+
+MCP server group wrapping FFmpeg/OTIO. Provides primitives to manipulate video editing workflows from AI agents.
+
+## Prerequisite: FFmpeg
+
+Clipwright requires ffprobe (runtime) and ffmpeg (test fixture generation) on PATH. Binaries are not included.
+
+### Installation (Windows / WinGet)
+
+```bash
+winget install Gyan.FFmpeg
+```
+
+**PATH takes effect after shell restart.** When using with Claude Code, restart the app for PATH to become active.
+
+If you cannot wait for a restart, specify environment variables directly:
+
+```bash
+# runtime: ffprobe only
+export CLIPWRIGHT_FFPROBE="C:/Users/<user>/AppData/Local/Microsoft/WinGet/Packages/Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe/ffmpeg-8.1.1-full_build/bin/ffprobe.exe"
+
+# test: both ffmpeg + ffprobe (for test fixture generation)
+export CLIPWRIGHT_FFMPEG="C:/Users/<user>/AppData/Local/Microsoft/WinGet/Packages/Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe/ffmpeg-8.1.1-full_build/bin/ffmpeg.exe"
+```
+
+### Environment Variable Usage
+
+| Variable | Purpose |
+|----------|---------|
+| `CLIPWRIGHT_FFPROBE` | **Runtime only**. Used by the `clipwright_inspect_media` tool |
+| `CLIPWRIGHT_FFMPEG` | **Test only**. Used by the `sample_media` fixture in `conftest.py` |
+
+> Runtime depends only on ffprobe. ffmpeg is used only for test fixture generation (design: [DC-AM-008]).
+
+---
+
+## Development Environment Setup
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run tests (with coverage)
+uv run pytest --cov=clipwright --cov-report=term-missing
+
+# lint / format
+uv run ruff check src tests
+uv run ruff format src tests
+
+# Type checking
+uv run mypy src
+```
+
+### Integration Test Prerequisites
+
+To run integration tests (tests that actually invoke ffprobe/ffmpeg), ffmpeg / ffprobe must exist on PATH or the following environment variables must be set:
+
+```bash
+# Specify path to ffprobe (used by runtime and integration tests)
+export CLIPWRIGHT_FFPROBE="/path/to/ffprobe"
+
+# Specify path to ffmpeg (used for test fixture generation)
+export CLIPWRIGHT_FFMPEG="/path/to/ffmpeg"
+```
+
+If ffmpeg / ffprobe are already registered in PATH, setting environment variables is not required. If neither is found, integration tests are automatically skipped.
+
+---
+
+## Development Notes: MCP Package
+
+### Adopted Package
+
+**Official MCP Python SDK** (`mcp[cli]`) is adopted (ADR-5 confirmed).
+
+```
+mcp[cli]>=1.27.2
+```
+
+Importable via `from mcp.server.fastmcp import FastMCP`. Verified to work on Python 3.11 / Windows.
+
+### Annotation Syntax (Adopted Version)
+
+```python
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+mcp = FastMCP("clipwright")
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_inspect_media(path: str) -> dict:
+    """Probe a media file and return its information."""
+    ...
+```
+
+`ToolAnnotations` fields: `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`
+
+### outputSchema / structured_output
+
+When `mcp.tool(structured_output=True)` is specified, Pydantic model return values are reflected in outputSchema as JSON Schema.
+
+```python
+from pydantic import BaseModel
+
+class MediaResult(BaseModel):
+    ok: bool
+    summary: str
+
+@mcp.tool(structured_output=True)
+def clipwright_inspect_media(path: str) -> MediaResult:
+    ...
+```
+
+---
+
+## MCP Inspector Communication Procedure
+
+How to manually verify the server using MCP Inspector (`@modelcontextprotocol/inspector`).
+
+### Setup (Node.js Required)
+
+```bash
+# Verify Node.js is installed
+node --version
+npx --version
+```
+
+### Starting the Server and Connecting
+
+```bash
+# Start MCP Inspector and connect the server via stdio
+npx @modelcontextprotocol/inspector uv run python -m clipwright.server
+```
+
+Browser opens automatically at `http://localhost:5173` (or access manually).
+
+The tool list (`clipwright_init_project` / `clipwright_inspect_media` / `clipwright_read_timeline` / `clipwright_write_timeline`) appears in Inspector, and you can manually execute each tool.
+
+### Expected Behavior
+
+- 4 tools appear in the tool list
+- Passing a non-existent path to `clipwright_inspect_media` returns an error envelope with `ok=false`
+- If ffprobe is not set in PATH / environment variables, a `DEPENDENCY_MISSING` error is returned
+
+---
+
+## Architecture Overview
+
+```
+src/clipwright/
+  __init__.py       # Version definition
+  schemas.py        # Shared Pydantic types (contract surface)
+  envelope.py       # Return value envelope + error formatting
+  errors.py         # Error codes + ClipwrightError exception
+  process.py        # Subprocess runner (shell=False / timeout required)
+  media.py          # ffprobe wrapper
+  otio_utils.py     # OTIO helpers
+  operations.py     # Declarative edit operation types + application logic
+  project.py        # Project directory management
+  server.py         # FastMCP server (4 tools exposed)
+```
+
+Dependency direction: `schemas / envelope / errors` (contract surface) → `process / media / otio_utils / project` → `operations` → `server`
+
+For details, see [docs/clipwright-spec.md](docs/clipwright-spec.md).
+
+---
+
+## License
+
+MIT — See [LICENSE](LICENSE) for details.

clipwright-0.1.1/README.md

@@ -0,0 +1,181 @@
+# Clipwright
+
+> For Japanese, see [README.ja.md](README.ja.md).
+
+MCP server group wrapping FFmpeg/OTIO. Provides primitives to manipulate video editing workflows from AI agents.
+
+## Prerequisite: FFmpeg
+
+Clipwright requires ffprobe (runtime) and ffmpeg (test fixture generation) on PATH. Binaries are not included.
+
+### Installation (Windows / WinGet)
+
+```bash
+winget install Gyan.FFmpeg
+```
+
+**PATH takes effect after shell restart.** When using with Claude Code, restart the app for PATH to become active.
+
+If you cannot wait for a restart, specify environment variables directly:
+
+```bash
+# runtime: ffprobe only
+export CLIPWRIGHT_FFPROBE="C:/Users/<user>/AppData/Local/Microsoft/WinGet/Packages/Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe/ffmpeg-8.1.1-full_build/bin/ffprobe.exe"
+
+# test: both ffmpeg + ffprobe (for test fixture generation)
+export CLIPWRIGHT_FFMPEG="C:/Users/<user>/AppData/Local/Microsoft/WinGet/Packages/Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe/ffmpeg-8.1.1-full_build/bin/ffmpeg.exe"
+```
+
+### Environment Variable Usage
+
+| Variable | Purpose |
+|----------|---------|
+| `CLIPWRIGHT_FFPROBE` | **Runtime only**. Used by the `clipwright_inspect_media` tool |
+| `CLIPWRIGHT_FFMPEG` | **Test only**. Used by the `sample_media` fixture in `conftest.py` |
+
+> Runtime depends only on ffprobe. ffmpeg is used only for test fixture generation (design: [DC-AM-008]).
+
+---
+
+## Development Environment Setup
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run tests (with coverage)
+uv run pytest --cov=clipwright --cov-report=term-missing
+
+# lint / format
+uv run ruff check src tests
+uv run ruff format src tests
+
+# Type checking
+uv run mypy src
+```
+
+### Integration Test Prerequisites
+
+To run integration tests (tests that actually invoke ffprobe/ffmpeg), ffmpeg / ffprobe must exist on PATH or the following environment variables must be set:
+
+```bash
+# Specify path to ffprobe (used by runtime and integration tests)
+export CLIPWRIGHT_FFPROBE="/path/to/ffprobe"
+
+# Specify path to ffmpeg (used for test fixture generation)
+export CLIPWRIGHT_FFMPEG="/path/to/ffmpeg"
+```
+
+If ffmpeg / ffprobe are already registered in PATH, setting environment variables is not required. If neither is found, integration tests are automatically skipped.
+
+---
+
+## Development Notes: MCP Package
+
+### Adopted Package
+
+**Official MCP Python SDK** (`mcp[cli]`) is adopted (ADR-5 confirmed).
+
+```
+mcp[cli]>=1.27.2
+```
+
+Importable via `from mcp.server.fastmcp import FastMCP`. Verified to work on Python 3.11 / Windows.
+
+### Annotation Syntax (Adopted Version)
+
+```python
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+mcp = FastMCP("clipwright")
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_inspect_media(path: str) -> dict:
+    """Probe a media file and return its information."""
+    ...
+```
+
+`ToolAnnotations` fields: `title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`
+
+### outputSchema / structured_output
+
+When `mcp.tool(structured_output=True)` is specified, Pydantic model return values are reflected in outputSchema as JSON Schema.
+
+```python
+from pydantic import BaseModel
+
+class MediaResult(BaseModel):
+    ok: bool
+    summary: str
+
+@mcp.tool(structured_output=True)
+def clipwright_inspect_media(path: str) -> MediaResult:
+    ...
+```
+
+---
+
+## MCP Inspector Communication Procedure
+
+How to manually verify the server using MCP Inspector (`@modelcontextprotocol/inspector`).
+
+### Setup (Node.js Required)
+
+```bash
+# Verify Node.js is installed
+node --version
+npx --version
+```
+
+### Starting the Server and Connecting
+
+```bash
+# Start MCP Inspector and connect the server via stdio
+npx @modelcontextprotocol/inspector uv run python -m clipwright.server
+```
+
+Browser opens automatically at `http://localhost:5173` (or access manually).
+
+The tool list (`clipwright_init_project` / `clipwright_inspect_media` / `clipwright_read_timeline` / `clipwright_write_timeline`) appears in Inspector, and you can manually execute each tool.
+
+### Expected Behavior
+
+- 4 tools appear in the tool list
+- Passing a non-existent path to `clipwright_inspect_media` returns an error envelope with `ok=false`
+- If ffprobe is not set in PATH / environment variables, a `DEPENDENCY_MISSING` error is returned
+
+---
+
+## Architecture Overview
+
+```
+src/clipwright/
+  __init__.py       # Version definition
+  schemas.py        # Shared Pydantic types (contract surface)
+  envelope.py       # Return value envelope + error formatting
+  errors.py         # Error codes + ClipwrightError exception
+  process.py        # Subprocess runner (shell=False / timeout required)
+  media.py          # ffprobe wrapper
+  otio_utils.py     # OTIO helpers
+  operations.py     # Declarative edit operation types + application logic
+  project.py        # Project directory management
+  server.py         # FastMCP server (4 tools exposed)
+```
+
+Dependency direction: `schemas / envelope / errors` (contract surface) → `process / media / otio_utils / project` → `operations` → `server`
+
+For details, see [docs/clipwright-spec.md](docs/clipwright-spec.md).
+
+---
+
+## License
+
+MIT — See [LICENSE](LICENSE) for details.

clipwright-0.1.1/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "clipwright"
+version = "0.1.1"
+description = "MCP server group wrapping FFmpeg/OTIO. Provides primitives to manipulate video editing workflows from AI agents."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "satoh-y-0323", email = "shoma.papa.0323@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "mcp[cli]>=1.27.2",
+    "opentimelineio>=0.18",
+    "pydantic>=2",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.15.16",
+]
+
+# --- Ruff ---
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+# templates/ is a template containing placeholders (__TOOL__ etc). Excluded from lint/format.
+extend-exclude = ["templates"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM"]
+ignore = []
+
+[tool.ruff.format]
+# Default ruff formatter is OK
+
+# --- mypy ---
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_any_generics = true
+# templates/ is a template containing placeholders. Excluded from type checking.
+exclude = ["^templates/"]
+
+# opentimelineio has no stubs, ignored with mypy strict
+[[tool.mypy.overrides]]
+module = "opentimelineio.*"
+ignore_missing_imports = true
+
+# --- pytest ---
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers -q"
+markers = [
+    "integration: integration test requiring actual ffmpeg/ffprobe binaries",
+    "slow: test with long execution time",
+]
+
+# --- coverage ---
+[tool.coverage.run]
+source = ["clipwright"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+
+# --- uv workspace ---
+[tool.uv.workspace]
+members = ["clipwright-bgm", "clipwright-loudness", "clipwright-noise", "clipwright-render", "clipwright-silence", "clipwright-transcribe", "clipwright-wrap"]

clipwright-0.1.1/src/clipwright/__init__.py

@@ -0,0 +1,3 @@
+"""clipwright: Core library for the FFmpeg/OTIO MCP server suite."""
+
+__version__ = "0.1.1"

clipwright-0.1.1/src/clipwright/cli_io.py

@@ -0,0 +1,25 @@
+"""cli_io.py — Shared UTF-8 I/O helper for separate-process CLIs.
+
+DRY home for the per-CLI UTF-8 pinning helper (CR L-2 / SR I-1). wrap_cli and
+vad_cli import force_utf8_io() from here instead of carrying a local copy, so the
+behaviour is defined once for every separate-process CLI that depends on core.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def force_utf8_io() -> None:
+    """Pin stdin/stdout to UTF-8 so this CLI is correct regardless of host
+    locale or inherited PYTHONIOENCODING (cp932 on JP Windows otherwise).
+
+    MUST be called before the first read from stdin: TextIOWrapper.reconfigure
+    raises once buffered reading has begun. Calling it at the very top of main()
+    (before sys.stdin.read()) satisfies this. Safe to call even on a CLI that
+    never reads stdin (reconfigure before any read is a no-op there).
+    """
+    for stream in (sys.stdin, sys.stdout):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8")

clipwright-0.1.1/src/clipwright/envelope.py

@@ -0,0 +1,64 @@
+"""envelope.py — Return value envelope construction helpers.
+
+Thin helpers that normalise all tool return values to the standard format (§6.3 / §6.4).
+Returns dict representations of ToolResult / ToolErrorResult, which are directly
+compatible with FastMCP JSON serialisation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def ok_result(
+    summary: str,
+    *,
+    data: dict[str, Any] | None = None,
+    artifacts: list[Any] | None = None,
+    warnings: list[str] | None = None,
+) -> dict[str, Any]:
+    """Build a success envelope dict (§6.3 ToolResult form).
+
+    summary must include key points an AI needs to decide the next action
+    (counts, durations, maxima, etc.). Do not make it minimal.
+
+    Args:
+        summary: Key points of the result (required).
+        data: Supplementary information (optional).
+        artifacts: List of references to output files (optional).
+        warnings: List of warning messages (optional).
+
+    Returns:
+        A dict of the form { ok: True, summary, data, artifacts, warnings }.
+    """
+    return {
+        "ok": True,
+        "summary": summary,
+        "data": data if data is not None else {},
+        "artifacts": artifacts if artifacts is not None else [],
+        "warnings": warnings if warnings is not None else [],
+    }
+
+
+def error_result(code: str, message: str, hint: str) -> dict[str, Any]:
+    """Build a failure envelope dict (§6.4 ToolErrorResult form).
+
+    message describes what happened; hint describes the concrete next step.
+    An empty hint violates the error contract (§6).
+
+    Args:
+        code: String representation of an ErrorCode value.
+        message: What happened.
+        hint: Concrete, actionable next step.
+
+    Returns:
+        A dict of the form { ok: False, error: { code, message, hint } }.
+    """
+    return {
+        "ok": False,
+        "error": {
+            "code": code,
+            "message": message,
+            "hint": hint,
+        },
+    }

clipwright-0.1.1/src/clipwright/errors.py

@@ -0,0 +1,62 @@
+"""errors.py — Error code taxonomy and ClipwrightError exception.
+
+The library layer raises ClipwrightError on failure;
+server.py converts it to error_result at the MCP boundary.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ErrorCode(StrEnum):
+    """Error codes shared across all Clipwright tools (§4 + §13.1 DC-AM-002/DC-AS-003).
+
+    Inherits str so values are JSON-serializable at API boundaries.
+    Each value equals its name string.
+    """
+
+    DEPENDENCY_MISSING = "DEPENDENCY_MISSING"
+    """External tool (ffmpeg/ffprobe, etc.) not found."""
+    INVALID_INPUT = "INVALID_INPUT"
+    """Argument validation failed."""
+    FILE_NOT_FOUND = "FILE_NOT_FOUND"
+    """No file exists at the given input path."""
+    PATH_NOT_ALLOWED = "PATH_NOT_ALLOWED"
+    """Path validation failed (e.g., path traversal attempt)."""
+    SUBPROCESS_FAILED = "SUBPROCESS_FAILED"
+    """External process exited with a non-zero return code."""
+    SUBPROCESS_TIMEOUT = "SUBPROCESS_TIMEOUT"
+    """External process timed out."""
+    PROBE_FAILED = "PROBE_FAILED"
+    """Failed to parse ffprobe output."""
+    OTIO_ERROR = "OTIO_ERROR"
+    """Failed to read, write, or parse an OTIO file."""
+    PROJECT_NOT_FOUND = "PROJECT_NOT_FOUND"
+    """clipwright.json not found."""
+    PROJECT_EXISTS = "PROJECT_EXISTS"
+    """An existing project already exists at the target init location."""
+    UNSUPPORTED_OPERATION = "UNSUPPORTED_OPERATION"
+    """Unknown or unsupported operation type."""
+    INTERNAL = "INTERNAL"
+    """Unexpected internal error (§13.1 DC-AM-002).
+
+    Use a generic message; expose stack traces only in hints/logs.
+    The hint must include a prompt to report with reproduction steps.
+    """
+    TRACK_NOT_FOUND = "TRACK_NOT_FOUND"
+    """The track index in operations exceeds the total track count (§13.1 DC-AS-003)."""
+
+
+class ClipwrightError(Exception):
+    """Exception raised by the Clipwright library layer.
+
+    Always carries the three-part set: code / message / hint (§6.4 error contract).
+    hint must describe the concrete next action for the user or AI agent.
+    """
+
+    def __init__(self, code: ErrorCode, message: str, hint: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint