@forgespace/branding-mcp 0.4.0

package/.env.example

@@ -0,0 +1,3 @@
+ANTHROPIC_API_KEY=REPLACE_WITH_YOUR_ANTHROPIC_API_KEY
+LOG_LEVEL=info
+NODE_ENV=development

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Changes
+
+<!-- Bullet list of changes -->
+
+## Type
+
+- [ ] feat: New feature
+- [ ] fix: Bug fix
+- [ ] refactor: Code refactoring
+- [ ] chore: Maintenance
+- [ ] docs: Documentation
+
+## Checklist
+
+- [ ] `npm run validate` passes
+- [ ] Tests cover new functionality
+- [ ] CHANGELOG.md updated
+- [ ] No secrets or credentials committed

package/.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run lint:check
+      - run: npm run format:check
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+
+  test:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22, 24]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run test:coverage
+      - name: Upload coverage
+        if: matrix.node-version == 22
+        uses: codecov/codecov-action@v5
+        with:
+          file: ./coverage/lcov.info
+          fail_ci_if_error: false
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - name: Verify dist output
+        run: test -f dist/index.js

package/.github/workflows/release-automation.yml

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    name: Validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test
+
+  release:
+    name: Create Release
+    needs: [validate]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+
+  publish:
+    name: Publish to npm
+    needs: [validate]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/security-scan.yml

@@ -0,0 +1,37 @@
+name: Security Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 6 * * 1'
+
+jobs:
+  audit:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - name: Audit production dependencies
+        run: npm audit --omit=dev --audit-level=high
+      - name: Audit dev dependencies (advisory only)
+        run: npm audit --audit-level=high || echo "::warning::Dev dependencies have vulnerabilities. Review manually."
+        continue-on-error: true
+
+  secret-scanning:
+    name: Secret Scanning
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: trufflesecurity/trufflehog@v3.93.4
+        with:
+          extra_args: --only-verified

package/.gitleaks.toml

@@ -0,0 +1,14 @@
+title = "Branding MCP Gitleaks Config"
+
+[allowlist]
+description = "Allowlist for placeholder values"
+regexTarget = "match"
+regexes = [
+  '''REPLACE_WITH_.*''',
+  '''your-.*-here''',
+  '''example\.com''',
+]
+paths = [
+  '''.env\.example''',
+  '''data/.*''',
+]

package/.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "jsxSingleQuote": true
+}

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.4.0] - 2026-02-28
+
+### Added
+
+- Gradient system generator with 5 style-aware presets (hero, button, card, text, background) across 8 brand styles
+- Multi-variant logo generator: wordmark, monogram, abstract, icon (4 SVG variants per brand)
+- Favicon generator producing 4 sizes (16, 32, 180, 512) with stroke optimization for small sizes
+- OG image templates: default (1200x630), article (1200x630), social (1200x1200) with brand gradient backgrounds
+- New MCP tool: `generate_brand_assets` for favicon and OG image generation from existing brand identity
+- All 6 exporters support gradient tokens (CSS, Tailwind, W3C JSON, Figma, React, Sass)
+- 55 new tests (188 total), 15 test suites
+
+### Changed
+
+- Logo generator uses brand typography font instead of hardcoded Inter
+- `LogoOutput` now includes `variants` record alongside backward-compatible `svg` field
+- `LogoConfig` accepts optional `style` for style-aware monogram/abstract shapes
+
+## [0.3.0] - 2026-02-28
+
+### Added
+
+- Shadow/elevation system generator with 6 levels (none, sm, md, lg, xl, 2xl), brand-tinted colors, light/dark theme support
+- Border/shape system generator with style-aware radius scales and border widths for all 8 brand styles
+- Motion/animation system generator with duration scales, cubic-bezier easings, and transition presets per brand style
+- New token types in `BrandIdentity`: `shadows`, `borders`, `motion` (backward-compatible, optional)
+- All 6 exporters updated: CSS variables, Tailwind preset, W3C JSON, Figma tokens, React theme, Sass variables now include shadow, border, and motion tokens
+- `generate_brand_identity` tool now includes shadows, borders, and motion in output
+- 36 new tests (133 total), 98.36% statement coverage, 100% function coverage
+
+## [0.2.0] - 2026-02-24
+
+### Added
+
+- AI interpretation layer for natural language brand refinement (`src/lib/branding-core/ai/`)
+- Strategy pattern: keyword (zero-cost), Claude API (Anthropic Messages), and auto (fallback) interpreters
+- `BrandIntent` abstraction decoupling NL understanding from generator execution
+- 20+ color keywords (warm, vibrant, premium, muted, dark, elegant, etc.) with HSL shift values
+- 15+ typography keywords (serif, editorial, dramatic, modern, compact, etc.) with font/scale mapping
+- `intent-applier` module applying HSL hue/saturation/lightness shifts before palette generation
+- Structured Claude prompts with brand context, JSON schema, and design principles
+- Optional `strategy` parameter on `refine_brand_element` tool (keyword/ai/auto)
+- `_interpretation` metadata in refinement responses showing strategy used and reasoning
+- 24 new tests for AI interpreter, intent applier, and strategy selection (97 total)
+
+## [0.1.0] - 2026-02-24
+
+### Added
+
+- Initial project structure with MCP server architecture
+- Color palette generator with 6 harmony modes (complementary, analogous, triadic, split-complementary, tetradic, monochromatic)
+- Typography system generator with modular type scales and curated font pairings
+- Spacing scale generator with geometric progression
+- SVG logo generator with brand colors and initials
+- 6 design token exporters: W3C JSON, CSS custom properties, Tailwind preset, Figma tokens, React theme, Sass variables
+- WCAG contrast checker (AA/AAA compliance)
+- Brand consistency validator with scoring
+- HTML brand guidelines generator
+- 7 MCP tools: generate_brand_identity, generate_color_palette, generate_typography_system, export_design_tokens, create_brand_guidelines, validate_brand_consistency, refine_brand_element
+- 2 MCP resources: brand templates catalog, brand knowledge base
+- Unit and integration test suite
+- CI/CD workflows (lint, test, build, security scan)

package/CONTRIBUTING.md

@@ -0,0 +1,203 @@
+# Contributing to Branding MCP
+
+Thank you for contributing to Branding MCP. This guide covers everything you need to know to submit high-quality contributions.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Code Standards](#code-standards)
+- [Testing Requirements](#testing-requirements)
+- [Pull Request Process](#pull-request-process)
+- [Review Process](#review-process)
+
+---
+
+## Code of Conduct
+
+All contributors are expected to be respectful, constructive, and professional. Harassment or exclusionary behavior will not be tolerated.
+
+---
+
+## Getting Started
+
+### 1. Fork and clone
+
+```bash
+git clone https://github.com/Forge-Space/branding-mcp.git
+cd branding-mcp
+npm install
+```
+
+### 2. Create a feature branch
+
+```bash
+git checkout -b feat/my-feature
+```
+
+### 3. Validate your environment
+
+```bash
+npm run validate
+npm test
+npm run build
+```
+
+---
+
+## Development Workflow
+
+### Repository structure
+
+Branding MCP is a TypeScript-based MCP server that provides brand identity resources for the Forge Space ecosystem.
+
+### Commands
+
+```bash
+npm install       # Install dependencies
+npm run build     # Build TypeScript to JavaScript
+npm run validate  # Validate MCP server configuration
+npm test          # Run test suite
+npm run dev       # Development mode with watch
+```
+
+### Branch flow
+
+```
+feature → main
+```
+
+This repository uses simplified trunk-based development. Feature branches merge directly to `main` after review.
+
+### Commit message format
+
+Follow Angular conventional commits:
+
+```
+feat(tools): add brand color palette tool
+fix(server): resolve resource loading error
+docs(readme): update usage examples
+refactor(types): simplify brand schema types
+test(tools): add validation tests
+chore(deps): upgrade @modelcontextprotocol/sdk
+```
+
+Types: `feat`, `fix`, `docs`, `refactor`, `test`, `perf`, `chore`
+
+---
+
+## Code Standards
+
+### TypeScript
+
+- Strict mode enabled
+- No `any` types without justification
+- All functions must have explicit return types
+- Use type imports: `import type { ... }`
+
+### Code quality
+
+- Functions: maximum 50 lines
+- Cyclomatic complexity: maximum 10
+- Line width: maximum 100 characters
+- No comments unless explicitly requested or documenting complex algorithms
+
+### MCP conventions
+
+- Follow Model Context Protocol specification
+- Tools must have clear descriptions and schemas
+- Resources must be properly typed
+- Prompts should be concise and actionable
+
+### Security
+
+- Never commit secrets or credentials
+- Use environment variables for configuration
+- Validate all user inputs
+- Sanitize all outputs
+
+---
+
+## Testing Requirements
+
+### Coverage targets
+
+- Overall coverage: minimum 80%
+- Tool handlers: 100%
+- Edge cases and error conditions required
+
+### What to test
+
+- Tool handler logic
+- Resource loading and validation
+- Schema validation
+- Error handling and edge cases
+- MCP protocol compliance
+
+### What NOT to test
+
+- Trivial getters/setters
+- Simple enum definitions
+- Third-party library behavior
+
+### Running tests
+
+```bash
+npm test                    # Run all tests
+npm test -- --coverage      # Generate coverage report
+npm test -- --watch         # Watch mode
+```
+
+---
+
+## Pull Request Process
+
+### Before opening a PR
+
+Ensure all of the following pass:
+
+```
+- [ ] npm run validate passes
+- [ ] npm test passes with all tests green
+- [ ] npm run build succeeds
+- [ ] MCP server starts without errors
+- [ ] No secrets or credentials committed
+- [ ] CHANGELOG.md updated under [Unreleased]
+- [ ] README.md updated if tools or resources changed
+- [ ] Commit messages follow conventional commit format
+```
+
+### PR checklist
+
+1. Push your branch: `git push origin feat/my-feature`
+2. Open PR targeting `main` branch
+3. Fill in the PR template completely
+4. Link related issues using `Closes #123` syntax
+5. Request review from maintainers
+6. Address all review feedback
+
+### PR title format
+
+```
+feat(tools): add logo variants tool
+fix(resources): resolve SVG encoding issue
+docs: update tool usage guide
+```
+
+---
+
+## Review Process
+
+1. **Automated CI** runs lint, type-check, build, tests, and MCP validation
+2. **Maintainer review** checks code quality, MCP compliance, and standards
+3. **Approval** requires CI passing + at least 1 maintainer approval
+4. **Merge** is done by a maintainer using squash merge to `main`
+
+Typical review turnaround: 2-5 business days.
+
+---
+
+## Questions?
+
+Open a [GitHub Discussion](https://github.com/Forge-Space/branding-mcp/discussions) or file an [issue](https://github.com/Forge-Space/branding-mcp/issues).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @forgespace/branding-mcp
+
+> **AI-powered brand identity generation via MCP — part of the [Forge Space](https://github.com/Forge-Space) open developer workspace.**
+
+[![CI](https://github.com/Forge-Space/branding-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Forge-Space/branding-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Generate complete design systems — colors, typography, spacing, shadows, borders, motion tokens, gradients, multi-variant logos, favicons, and OG images with multi-format export. 8 MCP tools, zero API dependencies, algorithmic-first generation.
+
+## Features
+
+- **Color Palette Generation** — HSL-based color harmonies (complementary, analogous, triadic, etc.) with WCAG contrast validation
+- **Typography System** — Modular type scales with curated font pairings
+- **Spacing Scale** — Geometric progression spacing system
+- **Shadow/Elevation System** — 6-level elevation scale with brand-tinted shadows, light/dark theme support
+- **Border/Shape System** — Style-aware radius scales and border widths for all 8 brand styles
+- **Motion/Animation System** — Duration scales, cubic-bezier easings, and transition presets per brand style
+- **Gradient System** — 5 style-aware gradient presets (hero, button, card, text, background)
+- **Multi-Variant Logo** — Wordmark, monogram, abstract, and icon variants with style-aware shapes
+- **Favicon Generation** — 4 sizes (16, 32, 180 apple-touch, 512 PWA) from brand icon
+- **OG Image Templates** — Default, article, and social formats with brand gradients
+- **Multi-Format Export** — W3C Design Tokens, CSS custom properties, Tailwind preset, Figma tokens, React theme, Sass variables
+- **Brand Validation** — WCAG contrast checking, completeness scoring, consistency analysis
+- **Brand Guidelines** — HTML brand book generation
+
+## Quick Start
+
+```bash
+npm install
+npm run build
+```
+
+### As MCP Server (stdio)
+
+```json
+{
+  "mcpServers": {
+    "branding": {
+      "command": "node",
+      "args": ["path/to/branding-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+### MCP Tools
+
+| Tool                         | Description                                        |
+| ---------------------------- | -------------------------------------------------- |
+| `generate_brand_identity`    | Complete brand from name, industry, and style      |
+| `generate_color_palette`     | Color palette with harmony and WCAG data           |
+| `generate_typography_system` | Font pairing + modular type scale                  |
+| `export_design_tokens`       | Export brand to JSON/CSS/Tailwind/Figma/React/Sass |
+| `create_brand_guidelines`    | Generate HTML brand book                           |
+| `validate_brand_consistency` | Check WCAG compliance and completeness             |
+| `refine_brand_element`       | Iterate on specific brand elements                 |
+| `generate_brand_assets`      | Generate favicons and OG images from brand         |
+
+### MCP Resources
+
+| Resource        | URI                 | Description                       |
+| --------------- | ------------------- | --------------------------------- |
+| Brand Templates | `brand://templates` | Pre-configured industry templates |
+| Brand Knowledge | `brand://knowledge` | Color theory and typography rules |
+
+## Development
+
+```bash
+npm run dev          # Watch mode
+npm run validate     # Lint + format + test
+npm run test         # Run tests
+npm run test:coverage # Coverage report
+npm run build        # Build TypeScript
+```
+
+## Architecture
+
+```
+src/
+├── index.ts                    # MCP server entry
+├── lib/
+│   ├── branding-core/          # Core library (reusable)
+│   │   ├── generators/         # Color, typography, spacing, logo, gradients, favicons, OG
+│   │   ├── exporters/          # Multi-format token export
+│   │   ├── validators/         # WCAG, consistency checks
+│   │   └── documents/          # Brand book generation
+│   ├── config.ts               # Environment config
+│   ├── logger.ts               # Pino logging
+│   └── types.ts                # TypeScript interfaces
+├── tools/                      # 8 MCP tool registrations
+└── resources/                  # Templates + knowledge base
+```
+
+## Ecosystem Integration
+
+Part of the [Forge Space](https://github.com/Forge-Space) ecosystem:
+
+- **mcp-gateway** — Register as MCP server (port 8033)
+- **uiforge-mcp** — Consumes brand tokens via `brandId` parameter
+- **uiforge-webapp** — Brand management UI at `/branding/*`
+- **forge-patterns** — Shared configs and conventions
+
+## License
+
+MIT

package/data/README.md

@@ -0,0 +1,13 @@
+# Knowledge Base
+
+This directory contains reference data for brand identity generation.
+
+## Structure
+
+- `color-theory/` — Color harmony rules, psychology, and accessibility standards
+- `typography/` — Font pairing data, type scale references, and readability guidelines
+- `brand-guidelines-examples/` — Reference brand guides for pattern extraction
+
+## Sources
+
+All data is sourced from open-licensed references. See `docs/DATA_SOURCES.md` for the complete catalog.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './lib/config.js';
+import { logger } from './lib/logger.js';
+import { registerGenerateBrandIdentity } from './tools/generate-brand-identity.js';
+import { registerGenerateColorPalette } from './tools/generate-color-palette.js';
+import { registerGenerateTypographySystem } from './tools/generate-typography-system.js';
+import { registerExportDesignTokens } from './tools/export-design-tokens.js';
+import { registerCreateBrandGuidelines } from './tools/create-brand-guidelines.js';
+import { registerValidateBrandConsistency } from './tools/validate-brand-consistency.js';
+import { registerRefineBrandElement } from './tools/refine-brand-element.js';
+import { registerGenerateBrandAssets } from './tools/generate-brand-assets.js';
+import { registerBrandTemplates } from './resources/brand-templates.js';
+import { registerBrandKnowledge } from './resources/brand-knowledge.js';
+async function main() {
+    const config = loadConfig();
+    logger.info({ env: config.nodeEnv }, 'Starting branding-mcp server');
+    const server = new McpServer({
+        name: '@forgespace/branding-mcp',
+        version: '0.1.0',
+    });
+    registerGenerateBrandIdentity(server);
+    registerGenerateColorPalette(server);
+    registerGenerateTypographySystem(server);
+    registerExportDesignTokens(server);
+    registerCreateBrandGuidelines(server);
+    registerValidateBrandConsistency(server);
+    registerRefineBrandElement(server);
+    registerGenerateBrandAssets(server);
+    registerBrandTemplates(server);
+    registerBrandKnowledge(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('Branding MCP server connected via stdio');
+}
+main().catch((error) => {
+    logger.fatal(error, 'Failed to start branding-mcp server');
+    process.exit(1);
+});
+process.on('SIGTERM', () => {
+    logger.info('Received SIGTERM, shutting down');
+    process.exit(0);
+});
+process.on('SIGINT', () => {
+    logger.info('Received SIGINT, shutting down');
+    process.exit(0);
+});
+//# sourceMappingURL=index.js.map