character-forge-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| FAL_KEY | No | fal.ai key for pictures, video, voice and music. Optional: without it you get cards and ready prompts only. | |
| CHARACTER_FORGE_DIR | No | Where characters are saved (default `~/character-forge`), one folder per character. | |
| CHARACTER_FORGE_MODELS | No | Path to your own `models.json`, to switch models or prices. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
character-forge builds vivid, story-ready characters (film, games, ads, books): a full character card plus an A-pose concept sheet. Characters are random in the sense "you can't guess who you'll get", but every part of the card grows from one core (wound → lie → fear → defense/gift → truth).
Always start with character_method: it contains the method, the card format and the variant-tournament protocol (3 variants of one concept compete; only the strongest ships). Run a single variant only if the user asks for a quick character. In brief mode keep everything the user specified, in every variant. Always write cards in English, whatever language the user writes in.
After a character exists, media is made only on request, one paid step at a time (ask before each): concept → location → idle video → voice (spoken in the video's moment, every language); music after the location. When the user asks what's next, call character_next and offer what it lists, with prices.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| character_methodA | Returns the character-development method (core + 9 sections), the card format, the variant-tournament protocol and the reference lists (arcs, flaws, fears, traits, archetypes, uniqueness questions). Call once before writing a character. |
| character_createA | The one way to start a character, from whatever the user gave: nothing (random), a text brief, a concept image, or a concept image plus a brief. Rolls coherent ENGINES (wound → lie → fear → worst trait / best trait → truth → arc) plus surprising SPARKS — by default 3 competing variants of the same concept for the variant tournament — and says how to treat the brief and the image. Same seed = same roll. |
| character_checkA | Checks a card for coherence: schema completeness, mechanical red flags (generic filler, repeats, want = need, thin core) and a coherence interview built from the card's own content that tests every causal link back to the core. Pass either a draft card (same shape as character_save's card) or the id of a saved one. |
| character_roleA | Returns the instructions and rubric for one role in the variant tournament (coherence, critic, judge, author, designer, editor). Reviewers should call this first. |
| character_saveA | Validates a complete character card and saves it as card.json and card.md. Returns the id and file paths (use character_get to show the card). Use overwrite: true with meta.slug = id to update a saved card. |
| character_conceptA | Builds an A-pose model-sheet prompt from a saved card's look and, with FAL_KEY set, generates it on fal.ai: a faceless figure built from look.body (the character's own proportions) is drawn front and back and given to GPT Image as the pose reference, with the full look → concept.png (the card is re-rendered with it). pose_image puts the character in the pose of any picture → concept-pose.png. Without FAL_KEY (or with dry_run) returns the prompt only. Costs ≈ $0.02 per sheet. |
| character_listB | Lists saved characters (newest first), with variant group and tournament verdict when present. |
| character_getA | Returns a saved character card as markdown (to show) or JSON (to edit and re-save with overwrite). |
| character_promptA | ONLY when the user asks for a specific prompt. Returns the rules and card material for writing ONE generation prompt for a saved character — concept, illustration, voice, video, song or theme. Write it, then call character_prompt_save. Prompts only; no generator is called. Never run this as part of creating a character. |
| character_prompt_saveB | Saves one written generation prompt into the character's prompts/ folder as .md (overwrites the previous one of that kind). |
| character_sceneA | ONLY on request. Draws the character in their own place doing what they usually do (an idle moment), using concept.png as the character reference (GPT Image 2.6 edit, ≈$0.05 at medium). Saves scene.png — the first and last frame for character_video. Write a specific prompt from the card (location, idle pose, light) or omit it for a default. |
| character_videoA | ONLY on request, after character_scene. Animates scene.png into a looping idle clip (default Kling O1 Standard ≈ $0.084/s, silent; veo ≈ $0.15/s with sound). See loop for how the clip is closed into a loop. Confirm the cost with the user first. |
| character_voiceA | ONLY on request; confirm the cost first. Creates the character's own voice from a description and an English reference script (write both with character_prompt kind 'voice'), plus any other languages listed in translations, each performed from the same description. Adults: ElevenLabs Voice Design, a saved voice and its reference take (≈$0.10 per 1000 characters of the script). Under 18: Qwen 3 Voice Design, deepened by pitch_semitones and cloned into a speaker embedding (≈$0.03). Saves assets/voice/. |
| character_voice_translationA | ONLY on request, after character_voice: a new voice in another language, generated from the voice prompt translated by meaning (description + monologue), so the delivery follows the card → voice/reference..mp3, which the site plays in that language. Same price as a line. |
| character_voice_lineA | ONLY on request, after character_voice; one line per call, confirm the cost (≈$0.10 per 1000 characters). Saves assets/voice/lines/.mp3. |
| character_themeA | ONLY on request, after a theme prompt is saved (character_prompt kind "theme" → character_prompt_save). Generates the instrumental leitmotif from its composition plan with ElevenLabs Music v2.5 ($0.60 per started minute: a 30 s theme costs $0.60) and saves assets/theme.mp3. Confirm the cost with the user first. |
| character_pickA | After the judge's verdict: moves the winning variant from the drafts into the library and deletes the other variants of its group (losers are not kept). If the character was started from the user's own concept image (meta.concept_image), it becomes the winner's concept. Write meta.verdict into the winner first. |
| character_translateA | When the user asked for other languages: saves the card translated (e.g. lang 'ru') as card..json next to the English original, which stays the source. Translate every free-text field in the character's own voice, as the editor would write it in that language; keep the structure, list lengths, numbers, ids, enums and colours exactly. |
| character_costsA | Free. Shows the character's paid generations (concept, scene, video, music, voice) with estimated USD from models.json pricing, and the total. |
| character_nextA | Free. Use when the user asks what's next for a character: lists what is done and the next possible steps (concept → location → video → voice, music after the location, translations), with prices. Offer them; run paid ones only after a yes. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| random_character | A random but strong, coherent character: 3 competing variants, the strongest wins and gets a T-pose concept. |
| character_from_brief | A character from what matters to you; 3 variants that all honour the brief compete, the strongest wins. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 20 tools
Each tool maps to a distinct pipeline stage (create, save, get, list, check, pick, translate, costs, next, method, role), and descriptions add explicit gating like "ONLY on request" or "Free." A few boundaries blur: character_prompt can produce a 'theme' prompt while character_theme generates music, character_concept also handles arbitrary pose_image work, and the three character_voice* tools require careful reading to separate. These are resolvable from descriptions but still invite occasional misselection.
Every tool uses the same character_ prefix with snake_case noun/verb suffixes, including predictable sub-verb families (character_prompt/character_prompt_save, character_voice/character_voice_translation/character_voice_line). The pattern is consistent throughout all 20 tools.
20 tools is on the heavy side but the domain genuinely is a long multi-stage pipeline: card lifecycle, variant tournament, four paid media generators, translations, and cost/next-step helpers. Each tool corresponds to a real, non-duplicated step, though the voice and prompt sub-families could arguably be collapsed.
The surface covers creation, validation, tournament selection, image/video/voice/music generation, translation, and cost accounting — a full lifecycle. The notable gap is deletion/cleanup: characters and generated assets can be created and overwritten but never removed, and written prompts can be saved but not listed or read back.