Skip to content

MCP.md

Latest commit

 

History

History
398 lines (298 loc) · 12 KB

MCP.md

File metadata and controls

398 lines (298 loc) · 12 KB
Raw

Rafiki MCP

Rafiki ships a local MCP server at mcp_server.py. It exposes the common image-generation functions directly, typed wrappers for stable local workflows, and a constrained bridge to the canonical CLI for everything else.

For hosted narrative video generation (prompt/script → finished video via Agent Opus), see AGENT-OPUS-MCP.md. That is a separate remote MCP — keep it next to Rafiki/Floyo in your mental model; do not confuse it with OpusClip long-form → shorts in kk-kb.

The server uses the official Python MCP SDK's FastMCP API and runs over stdio by default, which is the right fit for local desktop tools.

Official SDK reference: https://py.sdk.modelcontextprotocol.io/

Install For Local Clients

From this checkout:

./.venv/bin/python -m py_compile mcp_server.py

Run the spend-free agent smoke before changing MCP or CLI bridge behavior:

npm run smoke:dry-run

The smoke uses a disposable prompt file and output root. It runs the Node CLI in --dry-run --json mode, calls rafiki_status, lists MCP tools, runs the MCP rafiki_run bridge in dry-run mode, and checks archive-health --json over the resulting dry-run manifests. It clears provider-key environment variables inside the smoke process so a passing run never proves live provider access.

Rafiki commits .env.schema as the agent-readable env contract. Agents should inspect it with varlock load --agent --show-all from an agent/operator shell that has Varlock on PATH, and should not read .env or .env.local directly.

Codex:

codex mcp add rafiki -- /path/to/rafiki/.venv/bin/python /path/to/rafiki/mcp_server.py

Claude Code:

claude mcp add --scope user rafiki -- /path/to/rafiki/.venv/bin/python /path/to/rafiki/mcp_server.py

Generic MCP JSON:

{
  "mcpServers": {
    "rafiki": {
      "command": "/path/to/rafiki/.venv/bin/python",
      "args": ["/path/to/rafiki/mcp_server.py"]
    }
  }
}

The server loads .env from the Rafiki repo root for human local use, so API keys do not need to be duplicated into every client config. For agent sessions that may make real provider calls, wrap the MCP process with Varlock so the agent gets validated env injection without reading secret files:

codex mcp add rafiki -- /path/to/varlock run --inject vars --path /path/to/rafiki/ -- /path/to/rafiki/.venv/bin/python /path/to/rafiki/mcp_server.py

Generic MCP JSON with Varlock injection:

{
  "mcpServers": {
    "rafiki": {
      "command": "/path/to/varlock",
      "args": ["run", "--inject", "vars", "--path", "/path/to/rafiki/", "--", "/path/to/rafiki/.venv/bin/python", "/path/to/rafiki/mcp_server.py"]
    }
  }
}

rafiki_status returns machine-specific install commands for the current checkout when you need copy-paste commands for your own client.

Exposed Tools

  • rafiki_status: show repo paths, which env vars are present, and local install commands without exposing secret values.
  • rafiki_generate: generate one image through the Python core.
  • rafiki_batch: run an image-prompts.md batch with run isolation.
  • rafiki_list_styles: list style presets and descriptions.
  • rafiki_usage: return the local usage log.
  • rafiki_registry_search: search the persisted asset registry by title, caption, and tags.
  • rafiki_registry_export: export the registry to CSV or JSON.
  • rafiki_archive_health: report missing images, malformed manifests, duplicate filenames, sidecar orphans, and cleanup guidance without writing files.
  • rafiki_viewer_rebuild: rebuild project, run, or approved viewers without regenerating images.
  • rafiki_library_rebuild: check or rebuild the master library.html archive viewer without regenerating images.
  • rafiki_render: render one HTML file or a directory of HTML files to PNG.
  • rafiki_canva_export: build a Canva bulk-upload bundle from approved or latest-run images.
  • rafiki_notion_export: dry-run or export approved/latest-run images to a Notion gallery database.
  • rafiki_media_index: index configured multimedia roots or one explicit local root into the multimedia registry cache. Defaults to dry_run: true.
  • rafiki_media_search: search the multimedia registry for images, videos, audio, styles, and manifests.
  • rafiki_subjects: list indexed subject profiles, or return one subject when subject is passed.
  • rafiki_jobs: list local dry-run and executed job records stored under data/jobs.
  • rafiki_job_status: return hardened status fields for a single job by ID, including status, polling_status, error, provider, kind, cost_estimate, and explicit mutating: false / external: false safety flags. Never calls any provider.
  • rafiki_media_warnings: return the warnings list collected during the last multimedia registry index run without triggering a re-index. Returns an empty list if the registry has not been built yet.
  • rafiki_train_lora: plan or launch a Replicate FLUX LoRA training job. Defaults to dry-run (execute: false).
  • rafiki_video_generate: plan or launch a storyboard video generation job. Defaults to dry-run (execute: false).
  • rafiki_floyo_generate: plan or launch a Floyo (flowyo.ai) hosted-ComfyUI video workflow (default wan22_endframe). Defaults to dry-run (execute: false); on execute it submits only. See FLOYO.md.
  • rafiki_keyframes_generate: generate keyframe stills from a keyframes.json beat via Replicate (FLUX + the trained character image LoRA). Defaults to dry-run; submits only on execute. See FLOYO.md.
  • rafiki_style_anchors: read or derive a normalized style profile from a style-anchor JSON file.
  • rafiki_run: run supported fallback CLI workflows without a shell.

Typed workflow tools return stable JSON with success, ok, tool, dry_run, mutating, and external fields, plus workflow-specific paths, URLs, counts, stdout/stderr, or error details. success is kept for existing clients; new clients should read ok. See MCP-OUTPUT-CONTRACT.md for the full field reference, per-tool catalogue, and the ratified output contract.

Typed Workflow Examples

Asset registry:

rafiki_registry_search:

{"query": "certification", "limit": 10}

rafiki_registry_export:

{"format": "json", "dry_run": true}

Archive health:

rafiki_archive_health:

{"output_root": "/absolute/path/to/output", "cleanup_report": true}

Viewers:

rafiki_viewer_rebuild:

{"project": "rap-all-weeks", "all_runs": true, "dry_run": true}

rafiki_viewer_rebuild:

{"project": "rap-all-weeks", "approved": true}

rafiki_library_rebuild:

{"output_root": "/absolute/path/to/output", "dry_run": true}

rafiki_library_rebuild:

{"output_root": "/absolute/path/to/output", "dry_run": false}

HTML rendering:

rafiki_render:

{"html_path": "/absolute/path/to/card.html", "dry_run": true}

rafiki_render:

{"html_dir": "/absolute/path/to/cards"}

Canva and Notion export:

rafiki_canva_export:

{"project": "rap-all-weeks", "dry_run": true}

rafiki_canva_export:

{"project": "rap-all-weeks", "no_zip": true}

rafiki_notion_export:

{"project": "rap-all-weeks", "database_id": "notion-db-id", "dry_run": true}

rafiki_notion_export:

{"project": "rap-all-weeks", "database_id": "notion-db-id", "dry_run": false}

Multimedia suite:

rafiki_media_index indexes configured roots from config/media-roots.json (or one explicit root). Defaults to dry-run so the registry cache is not written unless dry_run is false:

{"key": "alex-samuel", "importer": "alex-samuel", "dry_run": true}
{"root": "/absolute/path/to/media-root", "key": "custom-root", "importer": "generic", "dry_run": true}

rafiki_media_search:

{"query": "portrait", "kind": "image", "limit": 20}

rafiki_subjects:

{}
{"subject": "alexandra"}

rafiki_jobs:

{}

rafiki_job_status:

{"job_id": "video-generation-20260601-120000"}

rafiki_media_warnings:

{}
{"registry_path": "/absolute/path/to/media-registry.json"}

rafiki_style_anchors:

{"source": "/absolute/path/to/style-anchor.json", "name": "hollywood"}

Spend-capable provider jobs (dry-run by default):

rafiki_train_lora writes local manifests and job records. Set execute: true only after explicit operator approval; that path may call Replicate and spend credits:

{"subject": "alexandra", "execute": false}

Note: the MCP argument is execute, not dry_run. Omit execute or pass execute: false for the safe default.

{"subject": "alexandra", "input_images_url": "https://example.com/training.zip", "execute": false}

rafiki_video_generate follows the same execute gate:

{"storyboard": "/absolute/path/to/storyboard.json", "execute": false}
{"storyboard": "/absolute/path/to/storyboard.json", "model": "wan-video/wan2.1-with-lora", "execute": true}

CLI Bridge Examples

rafiki_run is still available for less common workflows. It accepts Rafiki CLI arguments only. Do not include python, rafiki, or generate.py. Prefer the typed tools above for registry, viewer rebuild, render, Canva, and Notion workflows.

{"args": ["--usage"]}
{"args": ["library"]}
{"args": ["archive-health", "--output-dir", "/path/to/fixture-output", "--json"]}
{"args": ["archive-health", "--cleanup-report"]}
{"args": ["approve", "rap-all-weeks", "--run", "20260507-100000"]}
{"args": ["clean", "rap-all-weeks", "--dry-run"]}
{"args": ["billing", "summary", "--json"]}
{"args": ["social-expand", "rap-all-weeks", "--dry-run"]}
{"args": ["regen", "--dry-run"]}

Use an explicit fixture or disposable --output-dir when archive health is a release gate. Running archive-health without --output-dir inspects the operator's live local archive and is advisory.

serve is intentionally blocked in the MCP bridge because it is a long-running portal process. Start it directly when needed:

./.venv/bin/python generate.py serve --open

If an agent starts a provider-capable CLI command directly, keep the same secret boundary:

varlock run --inject vars -- ./.venv/bin/python generate.py --prompt "..." --output output.png

Safety Notes

The MCP server never invokes a shell. rafiki_run Python workflows execute:

<python> /path/to/rafiki/generate.py <args...>

Render-only bridge calls execute:

node /path/to/rafiki/index.js <args...>

Typed tools mark local writes and external calls explicitly. rafiki_archive_health, rafiki_media_search, rafiki_subjects, rafiki_jobs, rafiki_job_status, rafiki_media_warnings, and rafiki_style_anchors are read-only and return mutating: false. rafiki_media_index is read-only when dry_run is true and mutates the local registry cache when dry_run is false. Registry export, viewer rebuild, library rebuild, render, and Canva export are local mutations when dry_run is false. Notion export is external and only mutates remote Notion state plus the local export log when dry_run is false. rafiki_train_lora and rafiki_video_generate are always mutating: true; they stay local-only when execute is false and may call external providers when execute is true.

Dry-run wrappers do not stamp archive metadata or write generated outputs. They only report the paths, URLs, counts, commands, and errors a real run would use when the underlying workflow exposes enough information to preview safely.

Some fallback CLI workflows still mutate local state or external systems: approve, billing import, clean, deploy, regen, and social-expand. The returned JSON includes mutating: true for those calls so MCP clients can surface approvals or logs clearly. Use each workflow's own --dry-run flag where available.

For copy-paste automation and agent archive recipes, see Local Automation And Agent Archive Recipes.