@forgespace/branding-mcp 0.4.0

package/src/__tests__/unit/og-image-generator.test.ts

@@ -0,0 +1,115 @@
+import { generateOgImage } from '../../lib/branding-core/generators/og-image-generator.js';
+import { generateColorPalette } from '../../lib/branding-core/generators/color-palette.js';
+import { generateTypographySystem } from '../../lib/branding-core/generators/typography-system.js';
+import { generateSpacingScale } from '../../lib/branding-core/generators/spacing-scale.js';
+import { generateGradientSystem } from '../../lib/branding-core/generators/gradient-system.js';
+import {
+  generateSvgLogo,
+  defaultLogoConfig,
+} from '../../lib/branding-core/generators/logo-generator.js';
+import type { BrandIdentity } from '../../lib/types.js';
+
+function createTestBrand(): BrandIdentity {
+  const colors = generateColorPalette('#6B4CE6');
+  const typography = generateTypographySystem('sans-serif', 'sans-serif');
+  const spacing = generateSpacingScale();
+  const gradients = generateGradientSystem(colors, 'minimal');
+  const logo = generateSvgLogo({
+    ...defaultLogoConfig('TestBrand', colors.primary.hex),
+    style: 'minimal',
+  });
+
+  return {
+    id: 'test_brand',
+    name: 'TestBrand',
+    tagline: 'Test tagline',
+    industry: 'tech',
+    style: 'minimal',
+    colors,
+    typography,
+    spacing,
+    gradients,
+    logo,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+describe('generateOgImage', () => {
+  const brand = createTestBrand();
+
+  it('default template produces 1200x630', () => {
+    const result = generateOgImage(brand);
+    expect(result.width).toBe(1200);
+    expect(result.height).toBe(630);
+    expect(result.template).toBe('default');
+  });
+
+  it('default template includes brand name', () => {
+    const result = generateOgImage(brand);
+    expect(result.svg).toContain('TestBrand');
+  });
+
+  it('article template produces 1200x630', () => {
+    const result = generateOgImage(brand, 'article', 'My Article');
+    expect(result.width).toBe(1200);
+    expect(result.height).toBe(630);
+    expect(result.template).toBe('article');
+  });
+
+  it('article template includes custom title', () => {
+    const result = generateOgImage(brand, 'article', 'My Article', 'Subtitle');
+    expect(result.svg).toContain('My Article');
+    expect(result.svg).toContain('Subtitle');
+  });
+
+  it('social template produces 1200x1200 square', () => {
+    const result = generateOgImage(brand, 'social');
+    expect(result.width).toBe(1200);
+    expect(result.height).toBe(1200);
+    expect(result.template).toBe('social');
+  });
+
+  it('all templates produce valid SVG', () => {
+    for (const template of ['default', 'article', 'social'] as const) {
+      const result = generateOgImage(brand, template);
+      expect(result.svg).toContain('xmlns="http://www.w3.org/2000/svg"');
+      expect(result.svg).toContain('</svg>');
+    }
+  });
+
+  it('uses brand font family', () => {
+    const result = generateOgImage(brand);
+    expect(result.svg).toContain(brand.typography.headingFont);
+  });
+
+  it('default parameters work', () => {
+    const result = generateOgImage(brand);
+    expect(result.svg).toBeTruthy();
+    expect(result.width).toBe(1200);
+    expect(result.height).toBe(630);
+  });
+
+  it('uses brand colors', () => {
+    const result = generateOgImage(brand, 'social');
+    expect(result.svg).toContain(brand.colors.primary.hex);
+  });
+
+  it('works without gradients', () => {
+    const brandNoGradients = { ...brand, gradients: undefined };
+    const result = generateOgImage(brandNoGradients);
+    expect(result.svg).toBeTruthy();
+    expect(result.svg).toContain(brand.colors.primary.hex);
+  });
+
+  it('works without logo', () => {
+    const brandNoLogo = { ...brand, logo: undefined };
+    const result = generateOgImage(brandNoLogo);
+    expect(result.svg).toBeTruthy();
+    expect(result.svg).toContain('TestBrand');
+  });
+
+  it('social template with custom title', () => {
+    const result = generateOgImage(brand, 'social', 'Custom Title');
+    expect(result.svg).toContain('Custom Title');
+  });
+});

package/src/__tests__/unit/shadow-system.test.ts

@@ -0,0 +1,63 @@
+import { generateShadowSystem } from '../../lib/branding-core/generators/shadow-system.js';
+
+describe('generateShadowSystem', () => {
+  it('generates all 6 elevation levels', () => {
+    const system = generateShadowSystem();
+    const names = Object.keys(system.levels);
+    expect(names).toEqual(['none', 'sm', 'md', 'lg', 'xl', '2xl']);
+  });
+
+  it('none level has zero values', () => {
+    const system = generateShadowSystem();
+    const none = system.levels.none;
+    expect(none.blur).toBe(0);
+    expect(none.spread).toBe(0);
+    expect(none.offsetY).toBe(0);
+    expect(none.cssValue).toBe('none');
+  });
+
+  it('blur increases with elevation', () => {
+    const system = generateShadowSystem();
+    const levels = ['sm', 'md', 'lg', 'xl', '2xl'] as const;
+    for (let i = 1; i < levels.length; i++) {
+      expect(system.levels[levels[i]].blur).toBeGreaterThan(system.levels[levels[i - 1]].blur);
+    }
+  });
+
+  it('uses brand color for tinting', () => {
+    const system = generateShadowSystem('#FF0000');
+    const md = system.levels.md;
+    expect(md.color).toMatch(/^rgba\(/);
+    expect(md.cssValue).toContain('rgba(');
+  });
+
+  it('dark theme reverses shadow direction', () => {
+    const light = generateShadowSystem('#6B4CE6', 'light');
+    const dark = generateShadowSystem('#6B4CE6', 'dark');
+    expect(light.levels.md.offsetY).toBeGreaterThan(0);
+    expect(dark.levels.md.offsetY).toBeLessThan(0);
+  });
+
+  it('dark theme has higher opacity', () => {
+    const light = generateShadowSystem('#6B4CE6', 'light');
+    const dark = generateShadowSystem('#6B4CE6', 'dark');
+    expect(dark.levels.lg.opacity).toBeGreaterThan(light.levels.lg.opacity);
+  });
+
+  it('generates valid CSS box-shadow strings', () => {
+    const system = generateShadowSystem();
+    for (const [name, level] of Object.entries(system.levels)) {
+      if (name === 'none') {
+        expect(level.cssValue).toBe('none');
+      } else {
+        expect(level.cssValue).toMatch(/\d+px.*rgba\(/);
+      }
+    }
+  });
+
+  it('works with default parameters', () => {
+    const system = generateShadowSystem();
+    expect(system.levels).toBeDefined();
+    expect(Object.keys(system.levels)).toHaveLength(6);
+  });
+});

package/src/__tests__/unit/spacing-scale.test.ts

@@ -0,0 +1,60 @@
+import { generateSpacingScale } from '../../lib/branding-core/generators/spacing-scale.js';
+
+describe('generateSpacingScale', () => {
+  it('generates scale with default 4px unit', () => {
+    const scale = generateSpacingScale();
+    expect(scale.unit).toBe(4);
+    expect(scale.values['0']).toBe('0px');
+    expect(scale.values['1']).toBe('4px');
+    expect(scale.values['2']).toBe('8px');
+    expect(scale.values['4']).toBe('16px');
+  });
+
+  it('generates scale with custom unit', () => {
+    const scale = generateSpacingScale(8);
+    expect(scale.unit).toBe(8);
+    expect(scale.values['1']).toBe('8px');
+    expect(scale.values['2']).toBe('16px');
+  });
+
+  it('includes all standard steps', () => {
+    const scale = generateSpacingScale();
+    const expectedKeys = [
+      '0',
+      '0.5',
+      '1',
+      '1.5',
+      '2',
+      '2.5',
+      '3',
+      '4',
+      '5',
+      '6',
+      '8',
+      '10',
+      '12',
+      '16',
+      '20',
+      '24',
+    ];
+    for (const key of expectedKeys) {
+      expect(scale.values[key]).toBeDefined();
+    }
+  });
+
+  it('zero spacing is always 0px', () => {
+    const scale = generateSpacingScale(8);
+    expect(scale.values['0']).toBe('0px');
+  });
+
+  it('values increase monotonically', () => {
+    const scale = generateSpacingScale();
+    const keys = Object.keys(scale.values)
+      .map(Number)
+      .sort((a, b) => a - b);
+    const values = keys.map((k) => parseInt(scale.values[String(k)]));
+    for (let i = 1; i < values.length; i++) {
+      expect(values[i]).toBeGreaterThanOrEqual(values[i - 1]);
+    }
+  });
+});

package/src/__tests__/unit/typography-system.test.ts

@@ -0,0 +1,71 @@
+import { generateTypographySystem } from '../../lib/branding-core/generators/typography-system.js';
+
+describe('generateTypographySystem', () => {
+  it('generates a system with default parameters', () => {
+    const system = generateTypographySystem();
+    expect(system.headingFont).toBeTruthy();
+    expect(system.bodyFont).toBeTruthy();
+    expect(system.monoFont).toBe('JetBrains Mono');
+    expect(system.baseSize).toBe(16);
+    expect(system.steps.length).toBeGreaterThan(0);
+  });
+
+  it('applies correct scale ratio', () => {
+    const system = generateTypographySystem('sans-serif', 'serif', 'major-third', 16);
+    expect(system.scaleRatio).toBe(1.25);
+  });
+
+  it('uses perfect fourth scale', () => {
+    const system = generateTypographySystem('sans-serif', 'serif', 'perfect-fourth');
+    expect(system.scaleRatio).toBe(1.333);
+  });
+
+  it('generates correct number of type steps', () => {
+    const system = generateTypographySystem();
+    expect(system.steps.length).toBe(9);
+  });
+
+  it('base step is at index 2 with baseSize', () => {
+    const system = generateTypographySystem('sans-serif', 'serif', 'major-third', 16);
+    const baseStep = system.steps[2];
+    expect(baseStep.name).toBe('base');
+    expect(parseFloat(baseStep.size)).toBeCloseTo(16, 0);
+  });
+
+  it('sizes increase progressively', () => {
+    const system = generateTypographySystem();
+    const sizes = system.steps.map((s) => parseFloat(s.size));
+    for (let i = 1; i < sizes.length; i++) {
+      expect(sizes[i]).toBeGreaterThan(sizes[i - 1]);
+    }
+  });
+
+  it('respects custom base size', () => {
+    const system = generateTypographySystem('sans-serif', 'serif', 'major-third', 18);
+    expect(system.baseSize).toBe(18);
+    const baseStep = system.steps[2];
+    expect(parseFloat(baseStep.size)).toBeCloseTo(18, 0);
+  });
+
+  it('generates line heights for all steps', () => {
+    const system = generateTypographySystem();
+    for (const step of system.steps) {
+      expect(parseFloat(step.lineHeight)).toBeGreaterThan(1);
+      expect(parseFloat(step.lineHeight)).toBeLessThanOrEqual(1.6);
+    }
+  });
+
+  it('generates valid font weights', () => {
+    const system = generateTypographySystem();
+    for (const step of system.steps) {
+      expect([400, 600, 700]).toContain(step.weight);
+    }
+  });
+
+  it('pairs serif heading with sans-serif body', () => {
+    const system = generateTypographySystem('serif', 'sans-serif');
+    expect(system.headingFont).toBeTruthy();
+    expect(system.bodyFont).toBeTruthy();
+    expect(system.headingFont).not.toBe(system.bodyFont);
+  });
+});

package/src/index.ts

@@ -0,0 +1,59 @@
+#!/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(): Promise<void> {
+  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);
+});

package/src/lib/branding-core/ai/brand-interpreter.ts

@@ -0,0 +1,30 @@
+import type { BrandIdentity } from '../../types.js';
+import type { BrandIntent, InterpreterOptions } from './types.js';
+import { interpretWithKeywords } from './keyword-interpreter.js';
+import { interpretWithClaude } from './claude-interpreter.js';
+import { logger } from '../../logger.js';
+
+export type InterpreterStrategy = 'keyword' | 'ai' | 'auto';
+
+export async function interpretFeedback(
+  feedback: string,
+  element: 'colors' | 'typography' | 'spacing',
+  currentBrand: BrandIdentity,
+  strategy: InterpreterStrategy = 'auto',
+  options?: InterpreterOptions
+): Promise<BrandIntent> {
+  const useAi = strategy === 'ai' || (strategy === 'auto' && !!options?.anthropicApiKey);
+
+  if (useAi && options?.anthropicApiKey) {
+    try {
+      return await interpretWithClaude(feedback, element, currentBrand, options);
+    } catch (error) {
+      logger.warn(
+        { error: error instanceof Error ? error.message : String(error) },
+        'AI interpretation failed, falling back to keywords'
+      );
+    }
+  }
+
+  return interpretWithKeywords(feedback, element, currentBrand);
+}

package/src/lib/branding-core/ai/claude-interpreter.ts

@@ -0,0 +1,76 @@
+import type { BrandIdentity } from '../../types.js';
+import type { BrandIntent, InterpreterOptions } from './types.js';
+import { buildRefinementPrompt, buildGenerationPrompt } from './prompts.js';
+import { logger } from '../../logger.js';
+
+async function callClaude(prompt: string, options: Required<InterpreterOptions>): Promise<string> {
+  const response = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': options.anthropicApiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: options.model,
+      max_tokens: options.maxTokens,
+      messages: [{ role: 'user', content: prompt }],
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Anthropic API error ${response.status}: ${body}`);
+  }
+
+  const data = (await response.json()) as {
+    content: Array<{ type: string; text: string }>;
+  };
+  const textBlock = data.content.find((b) => b.type === 'text');
+  if (!textBlock) throw new Error('No text content in Anthropic response');
+  return textBlock.text;
+}
+
+function parseIntentJson(raw: string): BrandIntent {
+  const jsonMatch = raw.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) throw new Error('No JSON object found in AI response');
+  return JSON.parse(jsonMatch[0]) as BrandIntent;
+}
+
+export async function interpretWithClaude(
+  feedback: string,
+  element: 'colors' | 'typography' | 'spacing',
+  currentBrand: BrandIdentity,
+  options: InterpreterOptions
+): Promise<BrandIntent> {
+  const opts: Required<InterpreterOptions> = {
+    anthropicApiKey: options.anthropicApiKey ?? '',
+    model: options.model ?? 'claude-sonnet-4-20250514',
+    maxTokens: options.maxTokens ?? 512,
+  };
+
+  const prompt = buildRefinementPrompt(feedback, element, currentBrand);
+  logger.info({ element, model: opts.model }, 'Interpreting feedback with Claude');
+
+  const raw = await callClaude(prompt, opts);
+  return parseIntentJson(raw);
+}
+
+export async function suggestBrandWithClaude(
+  brandName: string,
+  industry: string,
+  description: string,
+  options: InterpreterOptions
+): Promise<BrandIntent> {
+  const opts: Required<InterpreterOptions> = {
+    anthropicApiKey: options.anthropicApiKey ?? '',
+    model: options.model ?? 'claude-sonnet-4-20250514',
+    maxTokens: options.maxTokens ?? 512,
+  };
+
+  const prompt = buildGenerationPrompt(brandName, industry, description);
+  logger.info({ brandName, model: opts.model }, 'Generating brand suggestions with Claude');
+
+  const raw = await callClaude(prompt, opts);
+  return parseIntentJson(raw);
+}

package/src/lib/branding-core/ai/intent-applier.ts

@@ -0,0 +1,59 @@
+import type { BrandIdentity } from '../../types.js';
+import type { BrandIntent } from './types.js';
+import { generateColorPalette, hexToHsl, hslToHex } from '../generators/color-palette.js';
+import { generateTypographySystem } from '../generators/typography-system.js';
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function applyColorShifts(
+  baseHex: string,
+  hueShift: number,
+  saturationShift: number,
+  lightnessShift: number
+): string {
+  const hsl = hexToHsl(baseHex);
+  return hslToHex(
+    (hsl.h + hueShift + 360) % 360,
+    clamp(hsl.s + saturationShift, 0, 100),
+    clamp(hsl.l + lightnessShift, 5, 95)
+  );
+}
+
+export function applyIntent(brand: BrandIdentity, intent: BrandIntent): BrandIdentity {
+  const updated = { ...brand };
+
+  if (intent.color) {
+    const { baseColor, harmony, theme, hueShift, saturationShift, lightnessShift } = intent.color;
+
+    let effectiveBase = baseColor ?? brand.colors.primary.hex;
+
+    if (hueShift || saturationShift || lightnessShift) {
+      effectiveBase = applyColorShifts(
+        effectiveBase,
+        hueShift ?? 0,
+        saturationShift ?? 0,
+        lightnessShift ?? 0
+      );
+    }
+
+    updated.colors = generateColorPalette(effectiveBase, harmony ?? 'complementary', theme);
+  }
+
+  if (intent.typography) {
+    const { headingCategory, bodyCategory, scaleRatio, baseSize } = intent.typography;
+    updated.typography = generateTypographySystem(
+      (headingCategory ?? brand.typography.headingFont.includes('serif')) ? 'serif' : 'sans-serif',
+      bodyCategory ?? 'sans-serif',
+      scaleRatio,
+      baseSize ?? brand.typography.baseSize
+    );
+  }
+
+  if (intent.style) {
+    updated.style = intent.style;
+  }
+
+  return updated;
+}

package/src/lib/branding-core/ai/keyword-interpreter.ts

@@ -0,0 +1,95 @@
+import type { BrandIdentity } from '../../types.js';
+import type { BrandIntent, ColorIntent, TypographyIntent } from './types.js';
+
+const COLOR_KEYWORDS: Record<string, ColorIntent> = {
+  warm: { harmony: 'analogous', hueShift: 15 },
+  cool: { harmony: 'analogous', hueShift: -15 },
+  subtle: { harmony: 'analogous', saturationShift: -15 },
+  vibrant: { harmony: 'triadic', saturationShift: 15 },
+  bold: { harmony: 'complementary', saturationShift: 10 },
+  muted: { harmony: 'monochromatic', saturationShift: -20 },
+  dark: { theme: 'dark', lightnessShift: -15 },
+  light: { theme: 'light', lightnessShift: 15 },
+  monochromatic: { harmony: 'monochromatic' },
+  complementary: { harmony: 'complementary' },
+  analogous: { harmony: 'analogous' },
+  triadic: { harmony: 'triadic' },
+  premium: { harmony: 'analogous', saturationShift: -10, lightnessShift: -10 },
+  playful: { harmony: 'triadic', saturationShift: 15, lightnessShift: 5 },
+  corporate: { harmony: 'complementary', saturationShift: -10 },
+  organic: { harmony: 'analogous', hueShift: 30 },
+  elegant: { harmony: 'monochromatic', saturationShift: -15, lightnessShift: -5 },
+};
+
+const TYPOGRAPHY_KEYWORDS: Record<string, TypographyIntent> = {
+  serif: { headingCategory: 'serif' },
+  'sans-serif': { headingCategory: 'sans-serif' },
+  mono: { bodyCategory: 'monospace' },
+  monospace: { bodyCategory: 'monospace' },
+  display: { headingCategory: 'display' },
+  handwritten: { headingCategory: 'handwriting' },
+  compact: { scaleRatio: 'minor-second' },
+  tight: { scaleRatio: 'major-second' },
+  spacious: { scaleRatio: 'perfect-fourth' },
+  dramatic: { scaleRatio: 'golden-ratio' },
+  larger: { baseSize: 18 },
+  smaller: { baseSize: 14 },
+  editorial: { headingCategory: 'serif', scaleRatio: 'perfect-fourth' },
+  technical: { bodyCategory: 'monospace', headingCategory: 'sans-serif' },
+  modern: { headingCategory: 'sans-serif', bodyCategory: 'sans-serif' },
+  classic: { headingCategory: 'serif', bodyCategory: 'serif' },
+};
+
+function mergeColorIntents(intents: ColorIntent[]): ColorIntent {
+  const merged: ColorIntent = {};
+  for (const intent of intents) {
+    if (intent.harmony) merged.harmony = intent.harmony;
+    if (intent.theme) merged.theme = intent.theme;
+    if (intent.baseColor) merged.baseColor = intent.baseColor;
+    merged.saturationShift = (merged.saturationShift ?? 0) + (intent.saturationShift ?? 0);
+    merged.lightnessShift = (merged.lightnessShift ?? 0) + (intent.lightnessShift ?? 0);
+    merged.hueShift = (merged.hueShift ?? 0) + (intent.hueShift ?? 0);
+  }
+  return merged;
+}
+
+export function interpretWithKeywords(
+  feedback: string,
+  element: 'colors' | 'typography' | 'spacing',
+  _currentBrand?: BrandIdentity
+): BrandIntent {
+  const lower = feedback.toLowerCase();
+
+  if (element === 'colors') {
+    const matched: ColorIntent[] = [];
+    for (const [keyword, intent] of Object.entries(COLOR_KEYWORDS)) {
+      if (lower.includes(keyword)) {
+        matched.push(intent);
+      }
+    }
+    return {
+      color: matched.length > 0 ? mergeColorIntents(matched) : { harmony: 'complementary' },
+      reasoning: `Keyword match: ${matched.length > 0 ? 'matched color keywords' : 'default fallback'}`,
+    };
+  }
+
+  if (element === 'typography') {
+    const matched: TypographyIntent[] = [];
+    for (const [keyword, intent] of Object.entries(TYPOGRAPHY_KEYWORDS)) {
+      if (lower.includes(keyword)) {
+        matched.push(intent);
+      }
+    }
+    const merged: TypographyIntent = {};
+    for (const intent of matched) {
+      Object.assign(merged, intent);
+    }
+    return {
+      typography:
+        Object.keys(merged).length > 0 ? merged : { headingCategory: 'sans-serif' as const },
+      reasoning: `Keyword match: ${matched.length > 0 ? 'matched typography keywords' : 'default fallback'}`,
+    };
+  }
+
+  return { reasoning: 'No actionable keywords found for spacing refinement' };
+}