FlashCut MCP Casting

MCP server for casting manga/anime characters to VOICEVOX speakers. It gives AI agents a small set of tools to inspect available voices, suggest a voice for a character, validate conflicts, and save the final casting state in Supabase.

This repo is intentionally standalone. It owns only the casting database and VOICEVOX speaker catalog used by this MCP. Do not point it at the main FlashCut application database.

Quick Start For Users

The published npm package is the recommended install path. Users do not need to clone this repo.

Requirements:

• Node.js 18 or newer.
• An MCP client such as Claude Desktop, Claude Code, Cursor, or another client that supports stdio MCP servers.
• Supabase values for the casting database.

Claude Desktop config example:

{
  "mcpServers": {
    "flashcut-casting": {
      "command": "npx",
      "args": ["-y", "flashcut-mcp-casting"],
      "env": {
        "SUPABASE_URL": "https://<project-ref>.supabase.co",
        "SUPABASE_ANON_KEY": "<anon-or-publishable-key>",
        "SUPABASE_SERVICE_ROLE_KEY": "<service-role-key>",
        "GOOGLE_GEMINI_API_KEY": "<optional>"
      }
    }
  }
}

Restart the MCP client after saving the config. On first launch, npx downloads and runs the latest published package.

To smoke-test from a terminal:

npx -y flashcut-mcp-casting

The command starts a stdio MCP server and waits for MCP client messages, so a blank terminal is expected.

Required Environment Values

| Variable | Required | Use | |---|---:|---| | SUPABASE_URL | yes | Supabase project URL. | | SUPABASE_ANON_KEY | yes | Read access for speaker/casting lookup. A modern publishable key may also work if your project uses one. | | SUPABASE_SERVICE_ROLE_KEY | for writes | Required for saving, deleting, renaming, merging castings, and embedding backfill. Keep this local to trusted MCP clients only. | | GOOGLE_GEMINI_API_KEY | no | Enables semantic speaker matching and embedding backfill. Without it, the MCP still works with metadata-based matching. |

Do not put SUPABASE_SERVICE_ROLE_KEY in browser code, public repos, screenshots, or user-facing logs.

What This MCP Does

• Stores VOICEVOX speaker metadata in Supabase.
• Stores character casting state per project.
• Suggests voices from English speaker metadata and optional Gemini embeddings.
• Prevents one VOICEVOX speaker from being assigned to multiple characters in the same project.
• Supports lightweight casting tiers so one-off extras can share reusable pool voices without changing the database schema.
• Exposes voice image/product URLs so AI clients can render candidate boards for user approval.
• Saves character context with the casting, including description, personality_tags, role, and notes.

Main Workflow

Agents should use the MCP in this order:

1. Call get_casting_status for the target project.
2. Build or read the character registry.
3. Call prepare_casting_batch for all uncast characters.
4. Show the returned approval board to the user when choices require confirmation.
5. Call save_casting_batch for all approved assignments.
6. Use rename_character or merge_characters when provisional names later become known.
7. Return a machine-readable JSON summary for downstream FlashCut/manga workflows.

See docs/AGENT_GUIDE.md for detailed agent instructions.

Local Development Requirements

• Node.js 18 or newer.
• npm.
• Supabase project with this repo's migrations applied.
• Claude Desktop, Claude Code, Cursor, or another MCP client.
• Optional: GOOGLE_GEMINI_API_KEY for semantic speaker search.

Local .env

For a cloned repo, create .env in the repo root:

SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_ANON_KEY=<anon-or-publishable-key>
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>
GOOGLE_GEMINI_API_KEY=<optional>

The MCP loads .env from either the current working directory or the repo root next to dist/.

SUPABASE_SERVICE_ROLE_KEY is required for saves, deletes, and embedding backfill. Do not expose it in browser clients or user-facing logs.

Local Install And Build

npm install
npm run build
npm test

For another Windows machine, use the setup script:

.\scripts\setup-user.ps1 -SupabaseAccessToken "sbp_..."

If Supabase CLI is already logged in:

.\scripts\setup-user.ps1

The setup script installs dependencies, builds dist/index.js, and syncs Supabase URL/keys into .env without printing secret values.

Claude Desktop Config Options

Recommended: npm package via npx

Use this when you want the published package rather than a local clone:

{
  "mcpServers": {
    "flashcut-casting": {
      "command": "npx",
      "args": ["-y", "flashcut-mcp-casting"],
      "env": {
        "SUPABASE_URL": "https://<project-ref>.supabase.co",
        "SUPABASE_ANON_KEY": "<anon-or-publishable-key>",
        "SUPABASE_SERVICE_ROLE_KEY": "<service-role-key>"
      }
    }
  }
}

Install As A Claude Plugin

Claude plugin import accepts .zip and .plugin files. Build the plugin package:

npm run plugin:build

This creates both accepted formats:

release/flashcut-mcp-casting.zip
release/flashcut-mcp-casting.plugin

Import either file from Claude's plugin UI. Then configure the plugin/MCP environment values:

• SUPABASE_URL
• SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY
• Optional GOOGLE_GEMINI_API_KEY

The plugin package includes bundled server code, the manga casting skill, and docs. It does not include .env, refs/, local Supabase temp files, or node_modules/.

Local Clone MCP Config

Use the local sample file:

claude-desktop-config.flashcut-casting.json

Manual snippet:

{
  "mcpServers": {
    "flashcut-casting": {
      "command": "node",
      "args": [
        "C:\\Users\\Admin\\Documents\\flashcut-mcp-casting\\dist\\index.js"
      ]
    }
  }
}

Copy only the flashcut-casting entry into Claude Desktop's existing mcpServers object, then restart Claude Desktop.

Updating

For npx installs, restarting the MCP client is usually enough to pick up the latest npm package because the config uses npx -y flashcut-mcp-casting.

To pin a specific version:

"args": ["-y", "[email protected]"]

Commands

| Command | Purpose | |---|---| | npm run build | Build the MCP server to dist/index.js. | | npm run dev | Run the MCP entrypoint from TypeScript for local debugging. | | npm run plugin:build | Build release/flashcut-mcp-casting.zip and .plugin for Claude plugin import. | | npm test | Run Node test files under src/*.test.ts. | | npm run supabase:env -- --project-ref <ref> | Pull Supabase URL and API keys into .env. | | npm run embeddings:backfill | Generate Gemini embeddings for all VOICEVOX speakers and store them in Supabase. |

Tool Surface

The MCP exposes these tools:

• get_casting_status
• get_character_registry
• upsert_character_registry
• validate_character_registry
• upsert_page_manifest
• get_page_manifest
• validate_page_references
• search_voicevox_speakers
• get_voice_details
• suggest_voice_for_character
• prepare_casting_batch
• validate_casting_plan
• save_casting_batch
• get_character_casting
• delete_character_casting
• list_projects
• get_project_summary
• export_project_castings
• rename_project
• delete_project_castings
• rename_character
• merge_characters

See docs/AGENT_GUIDE.md for tool-by-tool usage and examples.

Database

Migrations live in supabase/migrations.

Core tables:

• voicevox_speakers: seed catalog of VOICEVOX voices, styles, traits, image URLs, product URLs, and optional embeddings.
• page_manifests: per-project uploaded page filenames, canonical page stems, and derived page order for panel reference validation.
• character_identities: per-project visual identity registry used to confirm who a character is before voice casting.
• character_castings: per-project character-to-speaker assignments plus character context.

See docs/ARCHITECTURE.md for schema details and operational notes.

Important Constraints

• This repo is independent from the main FlashCut database.
• All AI-facing descriptions and traits should be English.
• Japanese should be preserved only in source manga text and original_name fields.
• Never invent speaker_uuid or style IDs. Use only tool-returned values.
• Never assign one speaker_uuid to two characters in the same project.
• For crowd/background characters, use casting_tier: "extra" with pool castings such as Extra_Male_Adult_Pool; do not save every one-off extra as a DB character.
• Run validate_casting_plan before saving multiple castings.
• User approval should be a consolidated table, not one question per character, when multiple castings are pending.

Project Files

| Path | Purpose | |---|---| | src/index.ts | MCP server entrypoint and tool definitions. | | src/casting.ts | Supabase reads/writes and RPC calls. | | src/voicevox.ts | Voice summaries, batch proposals, suggestion scoring, validation logic. | | src/embeddings.ts | Optional Gemini embedding client. | | src/backfill-voicevox-embeddings.ts | Embedding backfill script. | | scripts/setup-user.ps1 | One-command Windows setup for users. | | scripts/sync-supabase-env.ts | Sync Supabase URL/API keys into .env. | | skills/manga-casting/SKILL.md | Cross-agent manga casting skill. |