brandsystem-mcp

Start a brand system

brand_start

Idempotent

Adopt existing brand guidelines from PDFs, websites, Figma libraries, or hosted sources into a portable .brand runtime; use auto mode to extract, compile tokens, and generate reports in one call.

Instructions

Adopt a brand into a portable .brand/ runtime from whatever source already exists: existing brand guidelines (PDF), a website URL, a Figma library, or a hosted Brandcode Studio brand. THE entry point when the user says 'use my existing brand guidelines with AI', 'I have a PDF brand guide', 'use our Figma library', 'create a brand system', 'extract brand from website', or 'set up brand guidelines'. Pass website_url, guideline_pdf, figma_file_key, or brandcode_url — or pass no source and it discovers local candidates and presents a menu with a privacy explanation. Set mode='auto' with a website_url to run the full pipeline (extract, compile DTCG tokens + design-synthesis.json + DESIGN.md + brand runtime + interaction policy, generate HTML report) in one call. If .brand/ already exists, returns current status with next steps. NOT for reading an already-compiled brand (use brand_runtime or brand_context) or for sharing an existing brand with a team (use brand_brandcode_connect).

Input Schema

Name	Required	Description	Default
`mode`	No	'auto' (recommended): runs full pipeline in one call when website_url is provided. 'interactive': assesses available sources (including files discovered in the working directory) and presents a source menu.	interactive
`industry`	No	Industry vertical for smarter extraction (e.g. 'fintech', 'healthcare', 'content marketing')
`client_name`	Yes	Company or brand name (e.g. 'Acme Corp')
`website_url`	No	Company website URL to extract brand identity from (e.g. 'https://acme.com')
`brandcode_url`	No	Brandcode Studio brand URL for adopting an existing hosted brand (e.g. 'https://brandcode.studio/start/brands/acme'). Routes adoption through brand_brandcode_connect.
`guideline_pdf`	No	Path to a PDF brand guideline in or under the working directory (e.g. './brand-guidelines.pdf'). Routes adoption through brand_extract_pdf.
`figma_file_key`	No	Figma file key for design-file extraction. Routes adoption through brand_extract_figma.

Output Schema

Name	Required	Description	Default
`_metadata`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.17.0Oct 25, 2026
Removedv0.14.1Jul 18, 2026
Addedv0.13.4Jul 18, 2026
Removedv0.12.0Jul 17, 2026

Changed5 schema fields changedv0.11.0Jul 17, 2026

addedInput schema / properties / brandcode_url

Added value: +{
+  "description": "Brandcode Studio brand URL for adopting an existing hosted brand (e.g. 'https://brandcode.studio/start/brands/acme'). Routes adoption through brand_brandcode_connect.",
+  "format": "uri",
+  "type": "string"
+}

addedInput schema / properties / figma_file_key

Added value: +{
+  "description": "Figma file key for design-file extraction. Routes adoption through brand_extract_figma.",
+  "type": "string"
+}

addedInput schema / properties / guideline_pdf

Added value: +{
+  "description": "Path to a PDF brand guideline in or under the working directory (e.g. './brand-guidelines.pdf'). Routes adoption through brand_extract_pdf.",
+  "type": "string"
+}

changedInput schema / properties / mode / description

Previous value: -"'auto' (recommended): runs full pipeline in one call when website_url is provided. 'interactive': presents source menu for user to choose extraction method."New value: +"'auto' (recommended): runs full pipeline in one call when website_url is provided. 'interactive': assesses available sources (including files discovered in the working directory) and presents a source menu."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "_metadata": {
+      "additionalProperties": true,
+      "properties": {
+        "next_steps": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "what_happened": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "what_happened",
+        "next_steps"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "_metadata"
+  ],
+  "type": "object"
+}

First observedv0.5.0Apr 14, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare it is a non-destructive, idempotent, open-world write, but the description goes well past that: it names the exact artifacts produced in auto mode (DTCG tokens, design-synthesis.json, DESIGN.md, brand runtime, interaction policy, HTML report) and explains the already-exists behavior. The privacy explanation on local discovery is additional context an agent needs before prompting the user.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then triggers, then parameter contract, then exclusions — a sensible order. It is dense rather than padded, though the long trigger-phrase enumeration and the parenthetical artifact list make it longer than strictly necessary for an agent that already sees a 100% covered schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description instead covers the decision-relevant surface: which source param to pick, what auto mode does, what happens when .brand/ already exists, and where to go for adjacent intents. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds real semantics on top by explaining the mutual exclusivity of the four source parameters, the no-source fallback, and the specific interaction of mode='auto' with website_url. It does not repeat the enum or URI formats, which the schema already carries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Adopt a brand into a portable .brand/ runtime') and enumerates the four source types it accepts. The closing sentence explicitly distinguishes it from brand_runtime, brand_context, and brand_brandcode_connect, so an agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States when to use it in the user's own phrasing ('use my existing brand guidelines with AI', 'I have a PDF brand guide', 'use our Figma library'), and gives explicit exclusions pointing to the named alternatives. It also covers the degenerate case (no source passed → discovery menu) and the idempotent case (.brand/ exists → status returned).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server