# Brand MCP

A standalone Model Context Protocol server for brand-guided design generation, using **Sample Brand**, a fictional demonstration identity.

The sample identity includes a violet-and-slate palette, original geometric diamond symbols, nine vector logo variants, three photorealistic AI-generated speaker cutouts plus five legacy geometric avatars, and seven social and one-page layout references. Names, roles, quotes, reference copy, statistics, and example.com addresses are demonstration content, not real people or factual claims.

## Start locally

Requires Node.js 22 or 24 and pnpm 11.

```sh
pnpm install --frozen-lockfile
pnpm build
pnpm start
```

`pnpm start` runs the stdio MCP server. See [examples/client-config.json](examples/client-config.json) and replace the example absolute path with your checkout path. Use the server key `sample-brand`.

For HTTP on port 8080:

```sh
pnpm start:http
```

The HTTP endpoint is `/mcp`; health is `/healthz`. The default host allowlist contains localhost, loopback addresses, and `sample-brand-mcp`. Set `SAMPLE_MCP_ALLOWED_HOSTS` for your deployment. HTTP mode does not expose filesystem materialization or file validation tools. It provides no authentication; configure authentication at your reverse proxy before exposing it beyond your intended audience.

## Workflows

1. Call `get_brand_guidelines` before generation.
2. Use `create_social_svg`, `create_quote_post`, `create_generation_prompt`, or local `create_one_pager`.
3. Review spelling corrections and validate the result. Resolve final-mode violations.

Social variants: `navy_poster`, `petition_push`, `violet_alert`, `statistic_card`, `contrast_cards`, and `quote_post`. Lower thirds are supported through `create_social_svg`.

For photographic quote posts, choose `speaker1`, `speaker2`, or `speaker3`. These are original AI-generated fictional people supplied as transparent PNG cutouts. `speaker4` through `speaker8` retain legacy geometric avatars. No real speaker attribution or portrait is bundled.

One-page templates: `material_cost_chain` and `access_barriers`. The tool materializes a clean working SVG into `deliverables/`. Replace its content and illustration, supply real sources, then validate its exact path using `validate_one_pager_file`. The populated references are layout demonstrations, not finished factual publications.

Resources use the `brand://sample/` namespace. Run `get_mcp_status` and `audit_brand_assets` to inspect the running server and asset availability.

## Customize

- [data/sample-brand.json](data/sample-brand.json): identity, typography, palette, speaker profiles, and generation rules.
- [assets/manifest.json](assets/manifest.json): asset inventory.
- `assets/logos/`: synthetic SVG logo variants.
- `assets/quote-people/`: transparent photographic PNG cutouts and legacy SVG-wrapped geometric avatars.
- `assets/post-references/` and `assets/one-pager-references/`: editable layout references.
- `src/brand.ts`: rendering and validation contracts. Palette and layout changes may also require updates here and in tests.

Local output paths can be configured with `SAMPLE_BRAND_WORKSPACE_DIR`, `SAMPLE_BRAND_OUTPUT_DIR`, and `SAMPLE_BRAND_ASSET_DIR`. This project uses its own package, configuration namespace, and Git history.

Install the supplied fonts before editing generated SVGs in a design application. Open font assets retain their required license and copyright notices under `assets/fonts/licenses/`.

## Verify

```sh
pnpm check
pnpm test
pnpm smoke
pnpm render:samples
```

With the HTTP server running, `pnpm smoke:http` checks the local endpoint. Set `SAMPLE_MCP_URL` to test another endpoint. `pnpm audit:prod` checks production dependencies.

The code remains `UNLICENSED`; publication does not grant an open-source license. Font licenses are supplied separately.