BrandSweets Studio

Open-source brand guidelines, built by agents and read by clients.

BrandSweets Studio is a small TypeScript toolkit with three parts:

• A local MCP server. AI agents such as Claude, Codex and Cursor create and maintain a brand project through typed tools: identity, palette, typography, voice, assets and guide chapters. It also validates the project and exports it.
• A client-facing guide renderer. A brand project becomes a finished, art-directed guidelines page. It covers marks, palette, type, voice, applications and downloads, with copyable colours, a live type tester, a lightbox and a print stylesheet.
• A portable static export. One self-contained directory with HTML, CSS, a little JS, the fonts, every asset, a ZIP brand kit and design tokens. It uses relative links only and makes no network requests, so you can host it anywhere, including under a sub-path.

Available now: the MCP server, the file-based project format, the guide and the static export. Coming later: a visual editor for people. It will share the same schema and core services the MCP tools use (see Roadmap).

The example brand, Morrow House, is fictional. Its name, place names, people, copy and artwork were made up for this repository. Any resemblance to a real business is coincidental. The entrance photograph in the example is AI-generated (OpenAI image generation, October 2026) and shows no real property. See ASSETS.md.

Quickstart

Requires Node.js 22.18 or newer (the scripts use Node's built-in TypeScript support).

npm ci            # reproducible install from package-lock.json
npm run demo      # build, seed Morrow House through the MCP server, export it
npm run preview   # serve it read-only at http://127.0.0.1:4176/guides/morrow-house/

npm run demo starts the real MCP server over stdio. It connects with the official MCP client and replays examples/morrow-house/seed.ts as ordinary tool calls, the same tools any agent gets. The exported guide lands in .local/demo/exports/morrow-house/. You can copy that directory to any static host.

Other scripts:

Connect an agent

Print ready-to-paste configuration with absolute paths for your machine:

node dist/cli.js config --root ~/BrandSweets --input-root ~/BrandSweets/inbox

• --root is the workspace. Projects live in <root>/projects/<id>/ and exports in <root>/exports/<id>/.
• --input-root is the only directory agents may import local files from. It defaults to the workspace root.

The snippets cover Claude Code, Claude Desktop, Cursor and Codex. For example, for Claude Desktop and Cursor:

{
  "mcpServers": {
    "brandsweets": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/brandsweets-studio/dist/cli.js", "mcp", "--root", "/Users/you/BrandSweets", "--input-root", "/Users/you/BrandSweets/inbox"]
    }
  }
}

Then ask your agent something like: "Create a BrandSweets project for my bakery, add the logos in my inbox folder, and export the guide." The full tool reference is in docs/MCP.md.

CLI

brandsweets mcp       Run the MCP server over stdio
brandsweets list      List projects
brandsweets validate  Print diagnostics (exit 1 on errors)
brandsweets export    Export a project's static guide
brandsweets verify    Check an export's links, fragments and manifest
brandsweets preview   Serve an export read-only on 127.0.0.1 (--base for a sub-path)
brandsweets dev       Export + preview + re-export on change
brandsweets config    Print MCP client configuration

Documentation

• docs/MCP.md: tools, resources, errors, client setup
• docs/PROJECT_FORMAT.md: the on-disk project format
• docs/ARCHITECTURE.md: how the pieces fit, and where an editor plugs in
• docs/ROADMAP.md: what is next, and the optional hosted service
• SECURITY.md: threat model and reporting
• CONTRIBUTING.md: development workflow
• docs/IMPLEMENTATION.md: implementation report for this first release

Licence

The code is MIT, see LICENSE. The Morrow House example artwork, and its AI-generated photograph, are released under CC0, so reuse them freely. The bundled fonts (Newsreader, Instrument Sans, IBM Plex Mono) are under the SIL Open Font License 1.1, with licence texts included. See examples/morrow-house/ASSETS.md.