@forgespace/branding-mcp 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,114 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [Unreleased]
-
-## [0.7.0] - 2026-03-07
-
-### Added
-
-- **Import cycle detection** — `madge --circular` via `npm run check:cycles`
-- **Dead code detection** — knip config with library export exclusions
-- **Security scanning** — Semgrep CE and Trivy integration in CI
-- **Issue templates** — Bug report and feature request templates
-- **Service catalog** — catalog-info.yaml for IDP service discovery
-- **Ecosystem health** — Dependabot config, .nvmrc, CODEOWNERS
-
-### Changed
-
-- **CI workflows** — Migrated to org-wide reusable workflows for security scans and Node.js setup
-- **Dependency updates** — Bumped lint-staged (15.5.2→16.3.2), actions/setup-node (4→6), actions/checkout (4→6), trufflesecurity/trufflehog (3.93.3→3.93.7), and minor/patch group updates
-
-### Removed
-
-- Unused dependencies: `culori`, `pdfkit`, `satori`, `sharp`, `@types/pdfkit`
-
-## [0.6.2] - 2026-03-07
-
-### Fixed
-
-- **WCAG contrast compliance** — Secondary (#3B82F6→#2563EB) and accent (#F59E0B→#B45309) colors now pass AA 4.5:1 on white backgrounds. Brand consistency score 75→100
-
-## [0.6.1] - 2026-03-06
-
-### Changed
-
-- **Modern Horn brand templates** — Default Forge Space logo SVGs updated to Modern Horn icon geometry and Sora wordmark (#A78BFA/#8B5CF6/#6D28D9)
-
-## [0.6.0] - 2026-03-01
-
-### Added
-
-- Public type exports from package entry point: `BrandIdentity`, `ColorPalette`, `TypographySystem`, `SpacingScale`, `ShadowSystem`, `BorderSystem`, `MotionSystem`, `GradientSystem`, `LogoOutput`, `BrandStyle`, `ColorHarmony`, `ExportFormat`
-- Enables downstream packages (`@forgespace/brand-guide`) to re-export types without reaching into internal paths
-
-## [0.5.0] - 2026-02-28
-
-### Added
-
-- New MCP tool: `generate_design_system` — complete design system in one call (identity + token export combined)
-- 10 new tests for design system tool (198 total across 16 suites)
-
-## [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

@@ -1,203 +0,0 @@
-# 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/catalog-info.yaml

@@ -1,16 +0,0 @@
-apiVersion: backstage.io/v1alpha1
-kind: Service
-metadata:
-  name: branding-mcp
-  description: MCP server for brand-aware design generation and WCAG validation
-  tags:
-    - typescript
-    - mcp
-    - design
-    - npm
-spec:
-  owner: forge-space
-  system: siza
-  lifecycle: production
-  dependsOn:
-    - brand-guide

package/commitlint.config.cjs

@@ -1,24 +0,0 @@
-module.exports = {
-  extends: ['@commitlint/config-conventional'],
-  rules: {
-    'type-enum': [
-      2,
-      'always',
-      [
-        'feat',
-        'fix',
-        'docs',
-        'style',
-        'refactor',
-        'perf',
-        'test',
-        'chore',
-        'ci',
-        'build',
-        'revert',
-      ],
-    ],
-    'header-max-length': [2, 'always', 100],
-    'subject-case': [0],
-  },
-};

package/data/README.md

@@ -1,13 +0,0 @@
-# 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/docs/API.md

@@ -1,110 +0,0 @@
-# MCP Tool API Reference
-
-## generate_brand_identity
-
-Generate a complete brand identity from minimal input.
-
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| brandName | string | yes | Brand name (1-100 chars) |
-| industry | string | yes | Industry sector |
-| style | BrandStyle | yes | Visual direction |
-| tagline | string | no | Brand tagline |
-| baseColor | hex string | no | Base color preference |
-| harmony | ColorHarmony | no | Color harmony type |
-| theme | ColorTheme | no | Light/dark/both |
-| headingCategory | FontCategory | no | Heading font category |
-| bodyCategory | FontCategory | no | Body font category |
-| scaleRatio | TypeScaleRatio | no | Typography scale ratio |
-
-**Returns:** Complete `BrandIdentity` JSON with colors, typography, spacing, and logo.
-
-## generate_color_palette
-
-Generate a color palette from a base color and harmony.
-
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| baseColor | hex string | no | Base hex color (#RRGGBB) |
-| harmony | ColorHarmony | no | Harmony type |
-| theme | ColorTheme | no | Neutral scale direction |
-
-**Returns:** `ColorPalette` with primary, secondary, accent, neutrals, semantic colors, and WCAG contrast data.
-
-## generate_typography_system
-
-Generate a typography system with font pairing.
-
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| headingCategory | FontCategory | no | Heading font type |
-| bodyCategory | FontCategory | no | Body font type |
-| scaleRatio | TypeScaleRatio | no | Modular scale ratio |
-| baseSize | number (12-24) | no | Base font size in px |
-
-**Returns:** `TypographySystem` with fonts, scale ratio, and type steps.
-
-## export_design_tokens
-
-Export a brand identity to various design token formats.
-
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| brand | string (JSON) | yes | Full BrandIdentity JSON |
-| format | ExportFormat | yes | json, css, tailwind, figma, react, sass |
-
-**Returns:** Formatted design tokens string.
-
-## create_brand_guidelines
-
-Generate a brand guidelines document.
-
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| brand | string (JSON) | yes | Full BrandIdentity JSON |
-| format | BrandDocFormat | no | html (default) or pdf |
-
-**Returns:** HTML brand book document.
-
-## validate_brand_consistency
-
-Check a brand identity for completeness and accessibility compliance.
-
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| brand | string (JSON) | yes | Full BrandIdentity JSON |
-
-**Returns:** `BrandValidationResult` with score (0-100), validity flag, and issues list.
-
-## refine_brand_element
-
-Iterate on a specific element of an existing brand.
-
-**Parameters:**
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| brand | string (JSON) | yes | Full BrandIdentity JSON |
-| element | string | yes | colors, typography, or spacing |
-| feedback | string | yes | Natural language refinement instruction |
-
-**Returns:** Updated `BrandIdentity` JSON.
-
-## Enums
-
-**BrandStyle:** minimal, bold, elegant, playful, corporate, tech, organic, retro
-
-**ColorHarmony:** complementary, analogous, triadic, split-complementary, tetradic, monochromatic
-
-**ColorTheme:** light, dark, both
-
-**FontCategory:** serif, sans-serif, monospace, display, handwriting
-
-**TypeScaleRatio:** minor-second, major-second, minor-third, major-third, perfect-fourth, augmented-fourth, perfect-fifth, golden-ratio
-
-**ExportFormat:** json, css, tailwind, figma, react, sass

package/docs/DATA_SOURCES.md

@@ -1,69 +0,0 @@
-# AI Training Data Sources
-
-Curated data sources for enhancing the branding MCP's knowledge base and the broader Forge Space ecosystem.
-
-## Color Theory & Design
-
-| Source                           | License    | Use Case                               |
-| -------------------------------- | ---------- | -------------------------------------- |
-| culori (color science library)   | MIT        | Color space conversions, OKLCH support |
-| Open Color (13 hues x 10 shades) | MIT        | Curated color palettes reference       |
-| Tailwind CSS default palette     | MIT        | Industry-standard web color scales     |
-| Carbon Design System tokens      | Apache 2.0 | Enterprise design token patterns       |
-
-## Typography
-
-| Source                      | License    | Use Case                                |
-| --------------------------- | ---------- | --------------------------------------- |
-| Google Fonts API            | Apache 2.0 | Font metadata, pairing data, popularity |
-| Fontpair.co                 | Free       | Curated font pairing combinations       |
-| Type Scale (type-scale.com) | Free       | Modular scale visualization reference   |
-| Typewolf                    | Free/Paid  | Font usage in the wild, trend data      |
-
-## Accessibility
-
-| Source                  | License | Use Case                            |
-| ----------------------- | ------- | ----------------------------------- |
-| WCAG 2.1 as JSON (W3C)  | W3C     | Structured accessibility guidelines |
-| WCAG as JSON (Tenon.io) | MIT     | Machine-readable WCAG criteria      |
-| A11Y Project Patterns   | MIT     | Accessible component patterns       |
-| ARIA Practices Guide    | W3C     | ARIA pattern implementations        |
-
-## Design Tokens
-
-| Source                 | License      | Use Case                       |
-| ---------------------- | ------------ | ------------------------------ |
-| W3C Design Tokens Spec | W3C          | Token format standard          |
-| Style Dictionary       | Apache 2.0   | Token transformation pipelines |
-| Tokens Studio          | MIT (plugin) | Figma-to-code token workflows  |
-
-## Brand Identity
-
-| Source         | License  | Use Case                       |
-| -------------- | -------- | ------------------------------ |
-| Brandfetch API | Freemium | Brand asset data for reference |
-| Logo.dev       | Freemium | Logo generation patterns       |
-| Coolors.co     | Free     | Color palette inspiration      |
-
-## Component Libraries (for integration)
-
-| Source              | License | Use Case                        |
-| ------------------- | ------- | ------------------------------- |
-| shadcn/ui           | MIT     | Component styling patterns      |
-| Radix UI Primitives | MIT     | Accessible primitive components |
-| Headless UI         | MIT     | Unstyled component patterns     |
-
-## SEO & Web Standards
-
-| Source                | License      | Use Case                             |
-| --------------------- | ------------ | ------------------------------------ |
-| Schema.org vocabulary | CC BY-SA 3.0 | Structured data for brand pages      |
-| Google Lighthouse     | Apache 2.0   | Performance scoring for brand assets |
-| web.dev               | Apache 2.0   | Web best practices reference         |
-
-## Security
-
-| Source                   | License      | Use Case                                    |
-| ------------------------ | ------------ | ------------------------------------------- |
-| OWASP Cheat Sheet Series | CC BY-SA 4.0 | Security guidelines for brand asset serving |
-| CSP Reference (MDN)      | CC BY-SA 2.5 | Content Security Policy for brand assets    |

package/docs/INTEGRATION.md

@@ -1,58 +0,0 @@
-# Ecosystem Integration Guide
-
-## mcp-gateway Registration
-
-Register branding-mcp as an upstream server in mcp-gateway:
-
-```json
-{
-  "name": "branding",
-  "command": "node",
-  "args": ["/path/to/branding-mcp/dist/index.js"],
-  "port": 8033,
-  "tools": [
-    "generate_brand_identity",
-    "generate_color_palette",
-    "generate_typography_system",
-    "export_design_tokens",
-    "create_brand_guidelines",
-    "validate_brand_consistency",
-    "refine_brand_element"
-  ]
-}
-```
-
-## uiforge-mcp Integration
-
-The UI generator can consume brand tokens to ensure generated components match the brand:
-
-```typescript
-// In uiforge-mcp, pass brandId to component generation
-const component = await generateComponent({
-  type: 'button',
-  brandId: 'brand_abc123',
-  // Brand tokens auto-applied to colors, fonts, spacing
-});
-```
-
-## uiforge-webapp Routes
-
-New frontend routes for brand management:
-
-- `/branding` — Brand dashboard
-- `/branding/new` — Create new brand identity
-- `/branding/:id` — View/edit brand
-- `/branding/:id/export` — Export design tokens
-- `/branding/:id/guidelines` — View brand guidelines
-
-## Design Token Flow
-
-```
-branding-mcp (generate) → export_design_tokens → format selection
-  ├── json    → W3C Design Tokens → Style Dictionary pipeline
-  ├── css     → CSS custom properties → direct import
-  ├── tailwind → Tailwind preset → tailwind.config.ts
-  ├── figma   → Figma token format → Tokens Studio sync
-  ├── react   → Theme object → ThemeProvider
-  └── sass    → SCSS variables → @import
-```

package/eslint.config.js

@@ -1,52 +0,0 @@
-import tseslint from '@typescript-eslint/eslint-plugin';
-import tsparser from '@typescript-eslint/parser';
-
-export default [
-  {
-    ignores: ['dist/', 'node_modules/', 'coverage/', '*.js', '!eslint.config.js'],
-  },
-  {
-    files: ['src/**/*.ts'],
-    ignores: ['src/__tests__/**'],
-    languageOptions: {
-      parser: tsparser,
-      parserOptions: {
-        ecmaVersion: 2022,
-        sourceType: 'module',
-        project: './tsconfig.json',
-      },
-    },
-    plugins: {
-      '@typescript-eslint': tseslint,
-    },
-    rules: {
-      'no-console': 'warn',
-      eqeqeq: ['error', 'always'],
-      'no-unused-vars': 'off',
-      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
-      '@typescript-eslint/no-floating-promises': 'error',
-      '@typescript-eslint/no-explicit-any': 'warn',
-      '@typescript-eslint/explicit-function-return-type': ['warn', { allowExpressions: true }],
-    },
-  },
-  {
-    files: ['src/__tests__/**/*.ts'],
-    languageOptions: {
-      parser: tsparser,
-      parserOptions: {
-        ecmaVersion: 2022,
-        sourceType: 'module',
-      },
-    },
-    plugins: {
-      '@typescript-eslint': tseslint,
-    },
-    rules: {
-      '@typescript-eslint/no-explicit-any': 'off',
-      '@typescript-eslint/no-floating-promises': 'off',
-      '@typescript-eslint/explicit-function-return-type': 'off',
-      '@typescript-eslint/no-unused-vars': 'off',
-      'no-console': 'off',
-    },
-  },
-];