Apply a theme to the current project
apply_themeWrite a design kit into a project (DESIGN.md, tokens, stamp). Detects conflicts and aborts by default to save user edits; preview for dry run, force to overwrite.
Instructions
Write a design kit into a project on disk: DESIGN.md, a tokens file named for the chosen format, and identityforge.json, a stamp recording the applied kit and a hash of every file written. This is the only tool here that touches the filesystem. It reads the stamp before writing, so it can tell its own output from the user's work. A file that already exists but is not recorded in the stamp, or one whose content changed since it was written, is a CONFLICT: by default the tool then writes NOTHING, names every conflicting file, and returns an error, so a hand-written DESIGN.md survives. Files whose content already matches the kit are left untouched. Set preview to plan without writing anything at all, and force to overwrite conflicting files, which destroys their current content permanently with no recovery path. Everything is computed before the first write, so a failed fetch cannot half-apply. Call it once the user has settled on a kit; get_design_md and get_tokens inspect a kit without writing. The stamp also records the kit's permanent id and its version as the export reported them, which is what a later apply diffs against: re-applying tells you whether the kit itself moved to a new version, or whether only the rendered file changed. A version of null means the export did not report one, and must never be read as version 0. Free kits are public, and a Pro kit returns 403 unless the key is entitled.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Target directory to write into, absolute or relative to the server's working directory. Default: the MCP server's working directory. The stamp identityforge.json is written at its root. | |
| slug | Yes | Permanent id or slug of the kit to apply, from list_themes / search_themes. Prefer the id: it never moves, while a slug can be renamed and a retired slug keeps resolving through an alias. | |
| force | No | Apply despite conflicts. Default false. DESTRUCTIVE: it overwrites files this tool did not write or that were edited after it wrote them, their current content is gone permanently, and the result names each one. Only pass it after the user has seen the conflicting files and agreed to lose them. | |
| preview | No | Dry run. Default false. When true nothing is written at all, not even the stamp, and the result is the plan: which files would be created, which overwritten, which are already identical, and which conflict. Use it before applying into a project that may already have a DESIGN.md, and to show the user what would change. | |
| tokensEntry | No | Advisory note for the stamp: the project-relative path where the tokens file gets wired in, e.g. 'src/app/globals.css'. Recorded for the next agent, nothing is written to it. Carried forward from the previous stamp when omitted. | |
| tokensFormat | No | Token file format to write: dtcg (W3C JSON) | css (variables) | tailwind-v3 (config) | tailwind-v4 (@theme) | shadcn-registry. Default dtcg. Match it to the project's styling layer. |