character-forge-mcp
CLAUDE.md1 starsChanged 4 days agoMITView on GitHub
character-forge-mcp is an open-source MCP server, CLI and Claude Code plugin that creates characters for film, games, ads and books. Each character comes as a package: a card (card.json, card.md), a look derived from the story, and an A-pose concept sheet (concept.png). On request, the tool also writes generation prompts for an illustration, voice, video or song. The method behind the card is a screenwriting konspekt: Sheridan's 9 sections plus Dougan's best/worst/other traits. All product text, including cards, prompts and…
- Reads credentials
In this repository9 other files it gives its agents.
- contributeSkill
- intentSkill
- security-checkSkill
- character-promptsSkill
- concept-artSkill
- design-lookSkill
- forge-characterSkill
- meetSkill
- translate-characterSkill
The file
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
What this is
character-forge-mcp is an open-source MCP server, CLI and Claude Code plugin that creates characters for film, games, ads and books. Each character comes as a package: a card (card.json, card.md), a look derived from the story, and an A-pose concept sheet (concept.png). On request, the tool also writes generation prompts for an illustration, voice, video or song. The method behind the card is a screenwriting konspekt: Sheridan's 9 sections plus Dougan's best/worst/other traits. All product text, including cards, prompts and docs, is English only.
Commands
npm run build # tsc → dist/ (tests and MCP clients run dist/, so build first)
npm test # build + node --test test/*.test.mjs
npm run build && node --test --test-name-pattern="variants" test/forge.test.mjs # single test
npm run inspect # MCP Inspector against dist/index.js
npm run lint # Biome lint + format check (CI runs it); npm run format fixes
# CLI (same binary; no args = MCP server on stdio)
CHARACTER_FORGE_DIR=./characters node dist/index.js roll --variants 3 --anchor fisherman
node dist/index.js check examples/marta-vell.json # red flags + coherence interview
node dist/index.js save examples/marta-vell.json --overwrite
node dist/index.js prompt marta-vell # A-pose image prompt
node dist/index.js media marta-vell --kind voice # brief for one generation promptBiome (biome.jsonc) lints and formats: tabs, double quotes, sorted imports. TypeScript is strict, and the package is ESM (NodeNext), so relative imports need a .js extension. The end-to-end test in test/forge.test.mjs spawns dist/index.js over stdio with a real MCP client.
Architecture
Core idea: random but coherent. A character is one causal chain: wound → lie → fear → defense (worst trait) / gift (best trait) → truth (need), landing on the DNA they were born with. src/engine.ts holds hand-curated WOUNDS, which are coherent by construction. src/random.ts picks one chain plus independent "sparks" (occupation, archetype, setting, visible mark) that the model has to make serve the chain, and rolls the DNA temperament (six 0–100 scales, each with a plasticity). The DNA is the only thing rolled on its own; never roll traits independently, every trait comes from the DNA, the wound or both. Rolls are seeded (mulberry32) and every field is rolled in a fixed order, so the same seed always gives the same result regardless of overrides; new rolls go at the end of the order so old seeds keep their characters.
Variant tournament (the default flow). rollVariants makes 3 variants of one concept. They share the anchor and world (SHARED_KEYS), and each has a distinct wound, archetype and age band. The roles are author, coherence reviewer, critic (prosecutor), judge and designer. They are defined once in src/tournament.ts (ROLE_GUIDES, RUBRIC, TOURNAMENT_PROTOCOL) and served by the character_role and character_method tools. Server instructions, MCP prompts and skills/forge-character/SKILL.md deliberately only point to that protocol; keep it that way so the copies don't drift. In Claude Code, the skill spawns real subagents (agents/*.md) with fresh context. After judging, the designer derives the winner's look section from the story. Only the winner gets the A-pose concept. In other MCP clients one model plays every role.
Card pipeline. src/schema.ts (zod) is the single source of truth for the card. It is also the character_save input schema the model sees, so field .describe() texts are effectively prompt text. Adding a field touches:
schema.tssections()insrc/render.ts, a single section/block model rendered to Markdownexamples/marta-vell.json, which must stay valid; tests use it- optionally the question list in
src/check.ts - optionally
METHOD_GUIDEinsrc/methodology.ts
Born vs acquired. core.dna holds what the character was born (or made) with: temperament and innate appearance (species, sex, lineage, body plan, covering, natural colours, face, frame proportions, build, born differences). Characters can be any being, so DNA fields are worded for any kind. Everything life did lives elsewhere: description.physical is how body, face and hair look now; look.body is posture. The DNA never changes: each life event has a weight (exactly one wound, the others major or minor) and records what it made of the DNA in changes (characteristic → value now, validated by range); changedBy() folds them, bodyOf() merges frame, changes and posture for the pose figure. traits.personality is who they are in life, the DNA after the wound. CARD_USE marks what a playing character always keeps in mind (written from inside: core.self_story is the wound as they tell it, never the author's core.wound), what only the author knows (the truth, the future, the logline, how the audience sees them) and what is visual. Saving keeps fields this version's schema doesn't know (keepUnknown), so a card written by a newer version or another branch never loses them. StoredCardSchema upgrades cards saved before the DNA layer on read (their temperament stays unknown and character_check asks for it); character_save takes the full CharacterCardSchema.
The card's look section (shape language, silhouette, perfection, posture, signature item, marks with origins, movement, outfit, palette with meanings, 3 "story reads") is the single source for every visual output, built on the DNA's appearance. Marks, movement and clothing live in look and nowhere else.
src/check.ts adds mechanical red flags (generic phrases, repeats, want ≈ need, thin core) and a coherence interview built from the card's own values.
Layers.
src/store.tsis the library on disk, atCHARACTER_FORGE_DIR(default~/character-forge), one folder per slug.StoredCardis a card with a known slug.writeCardre-renders md, and embedsassets/concept.pngif it exists. Each character folder keeps the card at its root, every generated file (images, video, sound) inassets/and every prompt inprompts/(saveAsset,savePrompt);loadCardmoves files from the old flat layout on first read.models.json(package root, orCHARACTER_FORGE_MODELS) holds the media provider (fal) and one model per kind: concept, scene, video, music, voice.src/config.tsre-reads it on every call, so switching a model needs no rebuild or restart; missing keys fall back to its defaults.src/concept.tsbuilds the A-pose prompt and ownsgenerateConcept(), the single pipeline shared by the CLI and the MCP tool. Image generation is fal.ai only: noFAL_KEYmeans prompt only. Decisions below were tested on Marta, with the same seed throughout:- Default pipeline (
mode: "gpt"):src/pose.tsdraws an OpenPose-style skeleton from the card's body (bodyOf: DNA frame, life events, posture; front and back), uploaded and given to GPT Image 2.6 edit as the pose reference together with the full look; about $0.02 a sheet. The paragraphs below describe the earlier paths, still available throughmode. - Z-Image image-to-image (
mode: "img2img"):src/pose.tsrenders a faceless A-pose figure from the card's body (bodyOf), anatomically proportioned on the 8-head canon (lit capsules and ellipsoids with a z-buffer; PNG via zlib, no image deps). It is colour-blocked withlook.blockingzone colours (hair, skin, top, bottom, left/right footwear), like an artist's block-in. Colour blocking was the decisive fix: a grey mannequin bleeds grey into the result, while blocked colours carry through.src/fal.tsuploads it to fal storage and repaints it withfal-ai/z-image/turbo/image-to-imageat strength 0.85. Z-Image has 8 steps, so strength is quantised to 1/8: 0.75 greys the colours, ≥0.9 loses the pose. - SDXL ControlNet Union held the skeleton pose but the quality was unusable (junk objects, text). The user rejected it; don't reintroduce it.
- ControlNet (
fal-ai/z-image/turbo/controlnet) is kept only as an option (mode: pose | depth | canny). In every variant it barely held the pose: drawn OpenPose skeletons were ignored; pose and depth on the mannequin gave pixel-identical outputs. Don't make it the default again without new evidence. - GPT Image 2.6 Flare Edit (
mode: "gpt", quality forced tolow; the endpoint defaults to the ~10× pricierhigh) takes the block-in as a reference. It was the best at keeping both views consistent: sides, accessories and mismatched boots. It still flattens shoulder tilt and drifts toward realism. Accessories need anitemlabel, or blobs get drawn as armour. - Style: concepts use
DEFAULT_ART_STYLE(house style).style: "card"useslook.art_style; any other text renders a variant saved asconcept-<style>.png. - Control images must be URLs. Upload them with
falUpload; data URIs were silently ignored. - The prompt must fit Z-Image's ~512-token encoder (a test enforces about 1800 characters, most important first, no hex codes). Long prompts silently dropped the outfit.
index.tsloads a.envfrom the working directory.src/media.tsserves generation prompts on request only, one kind per call:character_promptreturns the target-specific rules plus card material, the model writes the prompt, andcharacter_prompt_savestores it asprompts/<kind>.md. Never wire media prompts into character creation. The concept kind reusesbuildTposePrompt.src/resources.tsexposes every library card as an MCP resource (character-forge://<id>/card.md);character_getreturns the same document, andcharacter_savelinks it for library cards.src/tools/has one file per MCP tool, wired insrc/tools/index.ts.src/prompts/holds the MCP prompts.src/index.tsis the CLI and stdio entry. CLI commands reuse store, concept and random helpers. For example,RollOptionsSchemadrives both thecharacter_createinput and CLI flag parsing.character_createis the single entry for a new character (random, brief, concept image, or both); a user image travels inmeta.concept_image, andcharacter_pickimports it as the winner's concept.src/meet.ts(experimental,/meetskill,character_meet*tools) puts 2–5 saved characters into one scene. The director's protocol lives there; the skill and tool descriptions only point to it. Each character is played by onecharacter-playersubagent whose packet holds only whatCARD_USEputs in its mind plus the public scene (never another character's thoughts, never author-only fields), and others know them only bylook.stranger_view. Cards are read, never changed; scenes are saved asscene.mdandscene.json.src/methodology.tsholdsMETHOD_GUIDEand the konspekt's lists. Most lists are not rolled;referenceLists()gives them to the model as menus viacharacter_method.
Plugin. The repo root is a Claude Code plugin (.claude-plugin/plugin.json and marketplace.json, with skills/, agents/). The plugin's MCP server runs npx -y @gdhub/character-forge-mcp@latest from npm, so installing from GitHub needs no build; inside the repo .mcp.json runs the local dist/ instead. .claude/skills and .claude/agents are symlinks to the root folders for in-repo development; edit the originals. Don't install the plugin while developing here, or the skill and agents load twice. .mcp.json runs the local server with CHARACTER_FORGE_DIR=./characters, which is gitignored. The server reads its version from package.json; Release Please bumps it together with plugin.json and server.json (the official MCP Registry entry, published by the release workflow); a test checks they match.
Workflow and releases
- Nobody pushes to
main. Every change goes issue with its intent (theintentskill: want, why, constraints, done when, how to check, out of scope) → branch linked to it (gh issue develop N) → develop (with tests) → refactor (simplify) → review (code-review,npm run lint,npm test) → pull request whose body starts withCloses #N(a check enforces it; merging closes the issue). Thecontributeskill (.claude/skills/contribute) walks through it; CONTRIBUTING.md is the human version. - PR titles and commits follow Conventional Commits, and the type follows who the change is for (table in CONTRIBUTING.md, "Commit and PR titles"):
feat/fix/perfonly when people using the tool will notice — they make a release;docs,refactor,test,ci,build,chore(workflow, contributor skills, repo settings) don't.!only when users must change something. PRs are squash-merged, so the title is the commit Release Please reads. - Never bump versions or edit CHANGELOG.md by hand. Release Please keeps a release PR open; merging it tags the version, writes the changelog, creates the GitHub release and publishes to npm (
.github/workflows/release.yml). - CI (
.github/workflows/ci.yml) runs lint and tests on Node 20 and 22 and type-checks the site. Tests must never call paid APIs.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

