Skip to content

Grit Tooling

MCP server, Premiere CEP extension, and content pipeline tools.

This document will be auto-updated by Minh when code changes are detected.

MCP Tools

S3 Asset Management

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/assets.py

Tools for managing assets in the S3 asset library via S3Client.

Tool Description
grit_upload_asset Upload a local file to S3. S3 key defaults to s3_prefix + filename; MIME type is auto-detected from extension. For storyboard assets, prefer grit_ingest_image/grit_ingest_video which handle naming conventions automatically.
grit_list_assets List assets in the S3 bucket. Supports filtering by key prefix and media type (image, video, audio). Returns up to max_keys results (default 100).
grit_download_asset Download an S3 object to a local file path. Creates parent directories automatically.

Supported media type filters for grit_list_assets:

  • image — .png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff
  • video — .mp4, .webm, .mov, .avi, .mkv
  • audio — .mp3, .wav, .ogg, .m4a, .flac, .aac

Asset Ingest

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/ingest.py

Tools for renaming downloads and uploading to S3 with the correct naming convention. Auto-derives a short abbreviation from the storyboard title (e.g. "Wisp Finds Her Voice" → wfhv).

Tool Description
grit_ingest_image Rename a MidJourney download and upload to S3. Produces: grit/images/illustrations/{abbr}/scene{N}-clip{N}.{ext}. Returns a reminder to run reorganize.py on prod for variant generation.
grit_ingest_video Rename a Wan2.2 video download and upload to S3. Produces: grit/video/animations/{abbr}/scene{N}-clip{N}.{ext}. Returns a reminder to run reorganize.py on prod for variant generation.

Audio SFX Pipeline

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/audio.py

Seven MCP tools form the audio SFX pipeline, covering generation, post-processing, and delivery of game-ready sound effects.

Tool Depends On Description
grit_generate_sfx ElevenLabs API Text-to-SFX generation, returns 48kHz/16-bit/mono WAV. Supports seamless loops via loop parameter. Duration range: 0.5–22 seconds. Optional prompt_influence (0.0–1.0) controls how closely output follows the prompt.
grit_audio_inspect stdlib wave Read WAV properties (duration, sample rate, channels, bit depth).
grit_audio_trim SoX (Homebrew) Exact duration cut with fade-in/out.
grit_audio_normalize FFmpeg (Homebrew) EBU R128 two-pass LUFS normalization. Configurable targets: target_lufs (default −14.0), target_tp (default −1.0), target_lra (default 7.0).
grit_audio_loop_check stdlib wave, struct Head/tail RMS comparison for seamless loop verification.
grit_audio_post_process SoX + FFmpeg Chains trim + normalize + loop check in one call.
grit_ingest_audio boto3 (S3) Upload with naming convention + provenance .meta.json sidecar.

Prerequisites: SoX and FFmpeg must be installed (e.g., via Homebrew). ElevenLabs API credentials must be configured.

Post-processing notes:

  • Non-loop cues (LAUNCH, IMPACT, CANCEL) follow a trim → normalize path.
  • Loop cues skip normalization if FFmpeg loudnorm breaks loop points; raw loops are shipped and MetaSounds handles gain at runtime.

S3 path convention: Audio SFX assets are stored under the grit/audio/sfx/{group}/ prefix with naming pattern {sfx_name}.wav (e.g. grit/audio/sfx/{group}/{sfx_name}.wav). Each asset has a provenance sidecar at grit/audio/sfx/{group}/{sfx_name}.meta.json containing license, generator, prompt, and issue reference.

3D Mesh Pipeline (Blender Headless)

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/mesh3d.py

Tools for inspecting, decimating, and exporting 3D meshes using Blender in headless mode. Requires blender_path to be set in GritMCPConfig. Blender scripts communicate results back via a GRIT_MESH_STATS: JSON marker on stdout. Script execution has a 120-second timeout (180 seconds for QuadriFlow retopo).

Tool Description
grit_mesh_inspect Open a .blend file and return polygon/vertex counts per object plus totals.
grit_mesh_decimate Reduce polygon count using the Decimate modifier (COLLAPSE type). Accepts either a target_poly_count or a ratio (0.0–1.0). Saves the result to output_file.
grit_mesh_export_fbx Export a .blend file to FBX with Unreal Engine-friendly settings (forward: −Y, up: Z, apply modifiers, no leaf bones, no animation bake).
grit_mesh_retopo Retopologize mesh objects to clean quad topology. Two methods: QuadriFlow (100% quads, better edge flow, 30-60s) and Voxel (faster, uniform quads). Accepts target_poly_count (default: 5000, used by QuadriFlow) and voxel_size (default: auto-calculated as max_dim / 50). See retopo notes below.
grit_mesh_analyze Analyze any 3D file (.blend, .fbx, .glb, .gltf, .obj) and return detailed mesh statistics: per-object poly/vert counts, world-space bounding box, dimensions, materials with Principled BSDF properties, UV maps, shape classification, and a suggested Meshy prompt. Renders a 3/4 angle EEVEE preview by default (render_preview=True); configurable render_path and render_size (default 1024px).
grit_mesh_auto_uv Apply smart UV projection to all mesh objects using Blender's Smart UV Project with configurable angle limit (default: 66°) and island margin (default: 0.01), then pack UV islands for efficient texture space usage.
grit_mesh_orient Orient and clean-name a mesh for UE5 import. Requires asset_name for naming. Sets metric units (configurable via scale_to_meters, default: true), applies scale/rotation transforms, sets origin to bottom-center of bounding box (for ground placement), and renames objects/mesh data/materials to a clean naming convention based on the asset name.
grit_mesh_material_split Experimental. Split baked texture into named material zones using HSV color bucketing. Samples the baked texture at each face's UV center, classifies by hue/saturation/value, and creates separate Principled BSDF materials per zone. Default zones: metal, wood, stone. Custom zone_definitions override via JSON string.
grit_mesh_compare Compare a reference 3D file against a generated file. Reports poly count ratio, per-axis dimension % difference, and bounding box volume ratio. Supports .blend, .fbx, .glb, .gltf, .obj.

mesh_decimate notes:

  • When target_poly_count is provided, the ratio is computed automatically from the current total.
  • The same ratio is applied to each mesh object individually, so unevenly sized meshes may not hit the exact target total.

mesh_retopo notes:

  • QuadriFlow includes automatic mesh cleanup (merge by distance at threshold 0.0001, recalculate normals) to handle GenAI mesh artifacts (near-duplicate vertices, inconsistent normals) that cause silent failures.
  • Silent failure detection: If QuadriFlow returns FINISHED but does not modify the mesh, the tool reports a warning per-object in the result under a "warnings" key, recommending method='voxel' or mesh_decimate as alternatives.
  • Recommended two-step approach for high-poly GenAI output (100k-400k tris): Run voxel remesh first to produce manifold geometry (~15k polys), then QuadriFlow for clean quads at the target poly count. Direct QuadriFlow on raw Meshy output often fails silently due to non-manifold geometry.
  • QuadriFlow ceiling: Voxel divisor /80 (~15k voxel polys) is the highest resolution where QuadriFlow succeeds. At /90+ (~19.5k+), it fails silently.
  • QuadriFlow uses a 180-second timeout; voxel uses the default 120-second timeout.

Example — two-step retopo workflow:

# Step 1: Split baked texture into material zones FIRST (before retopo strips textures)
grit_mesh_material_split(blend_file="/tmp/anvil_raw.blend",
                         output_file="/tmp/anvil_materials.blend")

# Step 2: Voxel remesh — makes geometry manifold, reduces to ~15k
grit_mesh_retopo(blend_file="/tmp/anvil_materials.blend", output_file="/tmp/anvil_voxel.blend",
                 method="voxel")

# Step 3: QuadriFlow — produces 100% clean quads at target poly count
grit_mesh_retopo(blend_file="/tmp/anvil_voxel.blend", output_file="/tmp/anvil_retopo.blend",
                 method="quadriflow", target_poly_count=5000)

S3 path convention: 3D models are stored under the grit/3d_models/{category}/{asset_name}/{variant}.{ext} prefix. Each upload includes a .meta.json sidecar with provenance and pipeline trace data.

3D Model Generation (Meshy AI)

Tools for generating and processing 3D models via the Meshy AI service, with Blender-based post-processing.

Tool Description
grit_meshy_text_to_3d Generate a 3D model from a text prompt via Meshy AI. Supports mode='preview' for fast drafts and mode='refine' (with preview_task_id) for high-quality output. Art styles: realistic, cartoon, sculpture, pbr. Optional topology (quad or triangle, default: quad) and target_polycount parameters.
grit_meshy_image_to_3d Generate a 3D model from a reference image via Meshy AI. Base64-encodes the local image and submits to the API. Optional topology (quad or triangle, default: quad) and target_polycount parameters.
grit_meshy_check Check the status of a Meshy generation task. Accepts task_type (text-to-3d, image-to-3d, or remesh; default: text-to-3d). With wait=true, polls until complete (up to 10 minutes, configurable interval). Optionally auto-downloads the result to download_path in a specified download_format (blend, glb, fbx, obj, stl).
grit_meshy_remesh Re-mesh a completed Meshy task to get .blend output and control poly count. This is the only way to get .blend files from Meshy via API. Default target formats: ["blend", "glb"]. Optional topology (quad or triangle, default: triangle) and target_polycount (100–300000, default: 30000). Poll result with grit_meshy_check (task_type='remesh').
grit_mesh_ingest Upload a processed .blend, .fbx, .glb, or .gltf file to S3 with the 3D model naming convention. Auto-inspects .blend files for poly count. Includes provenance sidecar with pipeline trace data (meshy_task_id, retopo_method, poly counts, material zones). Note: Defined in mesh3d.py, not meshy.py.

Video Pipeline (Wan2.2 Image-to-Video)

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/video.py, tools/mcp/grit-mcp/src/grit_mcp/tools/status.py

Tools for generating video from images using the Wan2.2 model via Tensor.art TAMS.

Tool Description
grit_upload_image Upload a local image to Tensor.art TAMS. Returns a resource_id to use with grit_generate_video.
grit_generate_video Submit a Wan2.2 image-to-video generation job. Accepts prompt, source image resource ID, duration (1–5 seconds, default: 5), seed, and template ID. The resolution_preset parameter exists but is currently ignored (hardcoded to 720p). Returns a job_id to track with grit_check_status.
grit_workflow_info Get details about a Tensor.art workflow template, including required input fields (node IDs, field names). Use to inspect a template before submitting jobs.
grit_check_status Check the status of a TAMS generation job. With wait=true, polls until the job completes or times out (up to 10 minutes for Wan2.2 cold starts). Returns result URLs on success.

Storyboard Parsing

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/storyboard.py

Tools for parsing storyboard markdown files and extracting prompts, narration, and metadata for each clip.

Tool Description
grit_list_clips List all clips in a storyboard markdown file with titles and which prompts are available (MidJourney, Wan2.2, narration).
grit_produce_clip Parse a storyboard markdown and extract all prompts, narration, camera movement, and audio notes for a specific clip (0-indexed).

Premiere Pro Assembly

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/premiere.py

Generates a JSON manifest that the Grit Assembly CEP panel reads to assemble video clips and narration audio into a Premiere Pro timeline.

Tool Description
grit_assemble_premiere Generate a JSON manifest for Premiere Pro timeline assembly. Accepts an ordered list of clips (video_path, audio_path, duration, label), sequence settings (frame_width default 1280, frame_height default 720, fps default 24), and writes the manifest to disk (default: ~/Desktop/grit-assembly.json). Open the Grit Assembly panel in Premiere Pro (Window > Extensions > Grit Assembly) to load and build the sequence.

Slack Review

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/review.py

Tools for team approval workflows via Slack. Recommended flow: generate → post for review → approved → ingest to S3.

Tool Description
grit_post_for_review Upload a video or image to Slack for team review. Includes storyboard context (title, scene, clip, prompt, seed). Reviewers react with 👍/👎. Returns a message_ts for tracking.
grit_check_reviews Check Slack reactions on a posted review. 👍 = approved, 👎 = rejected. On approval with ingest context (file_path, storyboard_title, clip_number), returns an ingest_payload with media_type, target S3 key, and all params needed to call the correct ingest tool. On rejection with s3_key, deletes the asset from S3 (legacy pre-review ingest).
grit_ingest_approved_from_slack Batch-ingest approved assets from a Slack channel. Queries recent messages, checks reactions, and automatically ingests clips with more 👍 than 👎 to S3. Requires a local_files_map (clip_number → file_path).

Video Review Orchestration

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/orchestration.py

End-to-end automated video review workflow that handles the complete review → approval → ingest pipeline.

Tool Description
grit_orchestrate_video_review Monitors job completion, downloads videos, posts to Slack for review, checks reactions, auto-regenerates rejected videos with refined prompts (feedback-aware prompt adjustment), and uploads approved videos to S3. Supports configurable max_retries (default: 2) and poll_interval (default: 5s). Each job spec requires: job_id, clip_number, clip_title, prompt, duration, and source_image_resource_id.

Feedback-aware prompt refinement: On rejection, the orchestrator reads thread comments from Slack and adjusts the regeneration prompt based on detected keywords (duration, emotion, motion, quality, composition, lighting, timing). Falls back to a generic refinement suffix if no specific feedback is detected.

Campaign Orchestration

Module: tools/mcp/grit-mcp/src/grit_mcp/tools/campaign.py

End-to-end campaign workflow from strategic briefing through narration approval. Orchestrates Phases 1–3 of the content campaign pipeline.

Tool Description
grit_orchestrate_campaign_phase1 Orchestrate Phases 1–3: Strategic briefing → Storyboard development (automated agents) → Narration generation and approval. Phase 1 creates a validated briefing (funnel stage, clip count, timing). Phase 2 invokes Audrey (Growth Storyteller) to create the storyboard and Russell (Content Writer) to refine and lock narration. Phase 3 generates narration audio via ElevenLabs, posts to Slack, and monitors approval.

Campaign phase order:

  1. Strategic Briefing (MCP) — validates campaign viability, funnel stage (TOFU/MOFU/BOFU), clip count (2–5), and social best-practice timing. Note: the orchestrator currently defaults to clip_count=2.
  2. Storyboard Development (Automated Agents) — Audrey creates storyboard with visual strategy, MidJourney/Wan2.2 prompts, and narration; Russell refines and locks narration scripts
  3. Narration Generation & Approval (MCP) — generates audio from locked scripts, posts to Slack for storyboard direction approval (👍 = approve direction, 👎 = revise)
  4. Reference Image Generation (Manual MidJourney + MCP upload)
  5. Video Generation & Approval (MCP — semi-automated via grit_orchestrate_video_review)
  6. Sync & Assembly (MCP + manual via grit_assemble_premiere)
  7. Distribution (Manual)

Premiere CEP Extension

Path: tools/premiere-cep/grit-assembly/

The Grit Assembly panel is a CEP (Common Extensibility Platform) extension for Adobe Premiere Pro. It reads the JSON manifest produced by grit_assemble_premiere and executes ExtendScript to build the timeline.

Compatibility: Premiere Pro 2024 and later (v24.0+), CSXS runtime 9.0.

Panel location: Window > Extensions > Grit Assembly

Auto-load: The panel automatically loads a manifest from ~/Desktop/grit-assembly.json on open (matching the default output path of grit_assemble_premiere). Use the Browse button to select a different manifest file.

Key files:

  • index.html — Panel HTML entry point
  • jsx/assembly.jsx — ExtendScript that creates bins, imports media, and builds the sequence
  • js/panel.js — Panel UI logic (load manifest, trigger assembly)
  • css/panel.css — Panel styling
  • CSXS/manifest.xml — Extension manifest (Premiere Pro version requirements)
  • install.sh — Installation script (macOS only)

Installation (macOS): Run install.sh to enable unsigned CEP extensions and symlink the panel into the Adobe CEP extensions directory. Restart Premiere Pro after installation.

Asset Production Pipelines

For detailed end-to-end pipeline documentation including flow diagrams, post-processing decision trees, and runtime integration notes, see the Asset Production Pipelines index:

See also

Feature Repositories

  • lore-repo → project_id: the-smithy1/grit/lore-repo

Code Paths to Explore

  • tools/premiere-cep/** in lore-repo
  • tools/mcp/grit-mcp/src/** in lore-repo