studio-forge-mcp

Unified MCP Creative, Media & Document Editing Forge — isolated FFmpeg multimedia pipelines, SVG / raster / document transformations, Code Mode polymorphic dispatch, Schema-Driven Development (SDD), and sqlite-vec semantic memory.

Contents: What Is This? · Architecture · Code Mode & Token Efficiency · Technology Stack · Toolset & Credits · Quick Start · Installing in an MCP Ecosystem · Configuration · Testing & Verification · Development & Branching · License

What Is This?

studio-forge-mcp is a standalone Model Context Protocol (MCP) server designed for AI coding and design agents that need reliable, sandboxed media, vector, and document editing without bloating LLM context windows.

Instead of exposing dozens of single-action tools, studio-forge-mcp groups domain capabilities behind 3 polymorphic tools (media_forge_ffmpeg, design_suite_forge, forge_memory_search), strict Pydantic v2 SDD contracts, path-traversal-guarded sandboxes, and local sqlite-vec (vec0, float[64]) vector recall.

Current Status (v0.1.0 Scaffold): SDD schemas, sandbox path guards (input_path + output_path + symlink escape protection), sqlite-vec memory, /health endpoint, FastMCP stdio & streamable-http transports, stable launcher (scripts/forge-mcp-launch.sh), E2E protocol tests, and Docker runtime are operational. media_forge_ffmpeg and design_suite_forge currently validate, guard paths, and index jobs (status: "ready"), with full subprocess execution next on the roadmap.

↑ Back to top

Related MCP server: media-engine

Architecture

flowchart LR
    CLIENT["AI Agent / MCP Client"] -->|"stdio (forge-mcp-launch.sh)"| MCP["FastMCP Server (Python 3.14 + SDD)"]
    CLIENT -->|"Streamable HTTP :8895 (/mcp)"| MCP
    CLIENT -->|"GET /health"| HEALTH["Health JSON + vec_version()"]
    MCP -->|"media_forge_ffmpeg"| FFMPEG["FFmpeg Engine (probe, resize, crop, convert, audio)"]
    MCP -->|"design_suite_forge"| SUITE["Design & Doc Suite (SVG, Raster, PDF, WCAG, Office)"]
    MCP -->|"forge_memory_search"| VEC["SQLite + sqlite-vec (vec0 float[64])"]
    FFMPEG --> SB["Isolated Sandbox (FORGE_SANDBOX_ROOT)"]
    SUITE --> SB

↑ Back to top

Code Mode & Token Efficiency

studio-forge-mcp adopts Code Mode principles to minimize tool-catalog bloat and LLM round-trips:

flowchart TD
    REQ["Agent Tool Call (Polymorphic Dispatch)"] --> SDD["Pydantic v2 SDD Validation"]
    SDD --> GUARD["Sandbox Guard (_safe_sandbox_path on input + output)"]
    GUARD --> EXEC["Media / Design Handler"]
    EXEC --> IDX["Auto-Index Summary in sqlite-vec (vec0)"]
    IDX --> COMPACT["Return Compact JSON Result"]

↑ Back to top

Technology Stack

↑ Back to top

Toolset & Credits

Multimedia Engine — Powered by FFmpeg

Full credit to the FFmpeg project for the underlying audio, video, and frame-processing engine exposed through media_forge_ffmpeg:

• probe: inspect streams, codecs, resolution, duration, and container metadata.

• resize / crop: deterministic dimension transforms with bounded SDD constraints (1..16384).

• convert: transcode across container/image formats.

• extract_audio / waveform: isolate audio tracks and generate visual waveform previews.

Design, Vector & Document Suite (design_suite_forge)

• svg_optimize / raster_to_svg: clean and vectorize artwork for web and design tools.

• extract_palette / wcag_contrast: extract color palettes and verify WCAG accessibility ratios.

• doc_extract / pdf_render_pages: extract structured text/tables and render PDF pages (powered by Poppler and Python tooling).

Semantic Artifact Memory (forge_memory_search)

• Powered by sqlite-vec (v0.1.9, vec0 float[64]) with deterministic 64-dimensional character-trigram embeddings (src/studio_forge_mcp/memory.py) for instant, zero-external-API recall over past media_job and design_job runs.

↑ Back to top

Quick Start

uv sync --group dev
uv run pytest -v
uv run studio-forge-mcp

Docker (python:3.14-slim)

docker build -t studio-forge-mcp:0.1.0 .
docker run --rm -p 8895:8895 -v /tmp/studio-forge-sandbox:/sandbox studio-forge-mcp:0.1.0

Health endpoint: GET http://127.0.0.1:8895/health

↑ Back to top

Installing in an MCP Ecosystem

studio-forge-mcp supports both stdio (for local desktop/IDE MCP clients such as Antigravity ~/.gemini/config/mcp_config.json) and Streamable HTTP (for Docker or remote deployments on FORGE_HOST:FORGE_PORT, default http://127.0.0.1:8895/mcp).

Option A: Local stdio Launcher (Recommended for Desktop/IDE Clients)

Register scripts/forge-mcp-launch.sh in your mcp_config.json:

{
  "mcpServers": {
    "studio-forge-mcp": {
      "command": "/home/ancruz/Documents/workspaces/studio-forge-mcp/scripts/forge-mcp-launch.sh",
      "disabled": false
    }
  }
}

Option B: Streamable HTTP (Local or Docker)

1. Start the server (uv run studio-forge-mcp or docker run -d --name studio-forge-mcp -p 8895:8895 -v /path/to/sandbox:/sandbox studio-forge-mcp:0.1.0).

2. Register the HTTP endpoint in any Streamable HTTP-capable MCP client:

{
  "mcpServers": {
    "studio-forge-mcp": {
      "url": "http://127.0.0.1:8895/mcp"
    }
  }
}

↑ Back to top

Configuration

↑ Back to top

Testing & Verification

flowchart LR
    UNIT["test_studio_forge.py (Core SDD, Memory, CLI)"] --> PYTEST["uv run pytest -v (23 tests)"]
    GAPS["test_omission_gaps.py (Boundaries, Symlink/Output Guards)"] --> PYTEST
    E2E["test_e2e.py (Real stdio + Streamable HTTP MCP)"] --> PYTEST
    PYTEST --> QA["ruff check . + mypy src tests"]

↑ Back to top

Development & Branching

• Branches: main (stable releases) and dev (active development).

• Quality checks:

uv run pytest -v
uv run ruff check .
uv run mypy src tests

↑ Back to top

License

This project is licensed under the Apache License 2.0.

studio-forge-mcp uses permissive dependencies (MIT, BSD-3-Clause, MIT OR Apache-2.0) and invokes external system binaries (ffmpeg, poppler-utils) in isolated subprocesses rather than linking copyleft libraries directly, keeping Apache-2.0 clean and conflict-free across the stack.

↑ Back to top