brandsystem-mcp: Instructions file for Codex

brandsystem-mcp

MCP server that extracts and manages brand identity (logo, colors, typography, voice, visual rules) for AI tools. Creates a .brand/ directory with structured YAML, DTCG tokens, and portable HTML reports.

Build and Test

npm install          # Install dependencies
npm run build        # Compile TypeScript to dist/
npm test             # Run vitest tests
npm run lint         # Type-check without emitting (tsc --noEmit)
npm run dev          # Watch mode for development
npm start            # Start the server (stdio transport)

Build must pass before committing. The entry point is src/index.ts (stdio transport) which creates the server from src/server.ts.

Branch and PR Workflow

main is protected by a ruleset (main-protection): no direct pushes, no force-pushes, PR required, and the CI matrix (build-and-test (20/22/24)) must pass before merge. Zero human approvals are required — CI is the gate. To land changes:

1. Create a branch (feat/..., fix/...) and commit there
2. Push and open a PR against main
3. Enable auto-merge: gh pr merge --auto --squash — the PR lands when CI is green
4. The branch is deleted automatically on merge

Do not attempt to push directly to main; the ruleset rejects it.

Architecture

src/
  index.ts         # Stdio transport entry point
  server.ts        # Creates McpServer, registers all 43 tools in priority order
  tools/           # One file per tool, mostly (41 files, 43 tools — brand-feedback.ts registers 3). Each exports a register(server) function.
                   # Counts drift; verify via `ls src/tools/*.ts | wc -l` and `grep -rc 'server\.tool(' src/tools/*.ts`
  lib/             # Shared utilities (brand-dir, css-parser, dtcg-compiler, content-scorer, etc.)
  types/           # TypeScript type definitions
  schemas/         # Zod schemas for validation
bin/
  brandsystem-mcp.mjs  # CLI entry point (npx @brandsystem/mcp)

Tool Registration Order (in server.ts)