@forgespace/branding-mcp 0.6.2 → 0.7.1

package/README.md

@@ -7,6 +7,7 @@
 </div>
 
 [![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)
+[![npm version](https://img.shields.io/npm/v/@forgespace/branding-mcp)](https://www.npmjs.com/package/@forgespace/branding-mcp)
 [![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. 9 MCP tools, zero API dependencies, algorithmic-first generation.
@@ -34,19 +35,35 @@ npm install
 npm run build
 ```
 
-### As MCP Server (stdio)
+### Run from npm (stdio)
+
+```bash
+npx -y @forgespace/branding-mcp@latest
+```
+
+### Install globally
+
+```bash
+npm install -g @forgespace/branding-mcp
+forgespace-branding-mcp
+```
+
+### IDE / client config
 
 ```json
 {
   "mcpServers": {
-    "branding": {
-      "command": "node",
-      "args": ["path/to/branding-mcp/dist/index.js"]
+    "forgespace-branding": {
+      "command": "npx",
+      "args": ["-y", "@forgespace/branding-mcp@latest"]
     }
   }
 }
 ```
 
+Set `ANTHROPIC_API_KEY` when you want AI-assisted refinement. The server also
+works in algorithmic-only mode without external APIs.
+
 ### MCP Tools
 
 | Tool                         | Description                                            |
@@ -78,6 +95,19 @@ npm run test:coverage # Coverage report
 npm run build        # Build TypeScript
 ```
 
+## Distribution
+
+- **npm** — installable as
+  [`@forgespace/branding-mcp`](https://www.npmjs.com/package/@forgespace/branding-mcp)
+- **MCP Registry metadata** — `server.json` and `mcpName` are included for
+  registry submission
+- **Tag release automation** — pushing `v*` runs npm publish with provenance,
+  then publishes the same version to the MCP Registry via GitHub OIDC
+- **Weekly registry ops** — `.github/workflows/mcp-registry-status.yml` refreshes
+  one issue with npm and MCP Registry drift, visibility, and next actions
+- **GitHub** —
+  [Forge-Space/branding-mcp](https://github.com/Forge-Space/branding-mcp)
+
 ## Architecture
 
 ```
@@ -101,10 +131,16 @@ src/
 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
+- **ui-mcp** — Consumes brand tokens via `brandId` parameter
 - **uiforge-webapp** — Brand management UI at `/branding/*`
 - **forge-patterns** — Shared configs and conventions
 
+## Community
+
+- [Documentation](https://docs.forgespace.co/docs)
+- [GitHub Discussions](https://github.com/orgs/Forge-Space/discussions)
+- [Issue tracker](https://github.com/Forge-Space/branding-mcp/issues)
+
 ## License
 
 MIT

package/dist/index.js

@@ -19,7 +19,7 @@ async function main() {
     logger.info({ env: config.nodeEnv }, 'Starting branding-mcp server');
     const server = new McpServer({
         name: '@forgespace/branding-mcp',
-        version: '0.1.0',
+        version: '0.7.1',
     });
     registerGenerateBrandIdentity(server);
     registerGenerateColorPalette(server);

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@forgespace/branding-mcp",
-  "version": "0.6.2",
+  "version": "0.7.1",
+  "mcpName": "io.github.forge-space/branding-mcp",
   "description": "MCP server for AI-powered brand identity generation — color palettes, typography systems, design tokens, and brand guidelines with multi-format export",
   "type": "module",
   "main": "dist/index.js",
@@ -24,18 +25,36 @@
     "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
     "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
     "typecheck": "tsc --noEmit",
+    "check:cycles": "madge --circular --extensions ts src/",
+    "knip": "knip",
+    "registry:check": "node scripts/registry-check.mjs",
     "pre-commit": "npm run lint && npm run format && npm run test",
-    "prepare": "husky"
+    "prepare": "husky",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "branding",
     "design-tokens",
     "color-palette",
     "typography",
     "brand-identity",
+    "agent-tools",
     "ai",
-    "forge-space"
+    "forge-space",
+    "internal-developer-platform"
   ],
   "author": "Forge Space",
   "license": "MIT",
@@ -49,22 +68,21 @@
   "homepage": "https://github.com/Forge-Space/branding-mcp#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "culori": "^4.0.1",
-    "pdfkit": "^0.16.0",
     "pino": "^10.3.1",
-    "satori": "^0.12.1",
-    "sharp": "^0.34.5",
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.4.3",
     "@types/node": "^22.15.0",
-    "@types/pdfkit": "^0.13.8",
     "@typescript-eslint/eslint-plugin": "^8.32.0",
     "@typescript-eslint/parser": "^8.32.0",
     "eslint": "^9.0.0",
     "husky": "^9.0.0",
     "jest": "^29.7.0",
-    "lint-staged": "^15.0.0",
+    "knip": "^5.86.0",
+    "lint-staged": "^16.3.2",
+    "madge": "^8.0.0",
     "prettier": "^3.0.0",
     "ts-jest": "^29.4.6",
     "typescript": "^5.1.6"

package/server.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.forge-space/branding-mcp",
+  "description": "AI-powered brand identity generation via MCP with design tokens, typography, logo assets, and brand guidelines export.",
+  "version": "0.7.1",
+  "registryType": "npm",
+  "repository": {
+    "url": "https://github.com/Forge-Space/branding-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@forgespace/branding-mcp",
+      "version": "0.7.1",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ],
+  "environmentVariables": [
+    {
+      "name": "ANTHROPIC_API_KEY",
+      "description": "Optional. Enables natural-language brand refinement with Anthropic when the AI strategy is selected.",
+      "isRequired": false,
+      "isSecret": true
+    }
+  ]
+}

package/.env.example

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

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,22 +0,0 @@
-## 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

@@ -1,73 +0,0 @@
-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

@@ -1,56 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

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

package/CHANGELOG.md

@@ -1,92 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [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)