@fiskaly/ui-mcp

MCP (Model Context Protocol) server for the fiskaly design system. Enables AI tools like Claude Desktop, Cursor, Windsurf, and Lovable to discover and use @fiskaly/ui components and design tokens.

Implements #402 - Add Storybook MCP server for AI-assisted development

Table of Contents

For Consumers

• Quick Start
• What This MCP Can Do
• Adding Custom Instructions
• API Reference

For Developers

• How It Works
• Architecture
• Local Development

For Maintainers

• Data Extraction
• When to Update What
• Publishing
• File Structure

For Consumers

Quick Start

Claude Desktop / Cursor / VS Code

Add to your MCP configuration:

{
  "mcpServers": {
    "fiskaly-ui": {
      "command": "npx",
      "args": ["@fiskaly/ui-mcp"]
    }
  }
}

Authentication

The first time you use a tool that requires authentication (like get_tokens), you'll be prompted to log in.

To log in manually:

npx @fiskaly/ui-mcp --login

This will open your browser to authenticate with GitHub. Once complete, your credentials are saved locally.

To log out:

npx @fiskaly/ui-mcp --logout

HTTP API (Lovable, Web Apps)

Live endpoint: https://style.fiskaly.com/mcp

Authentication Required: To use the HTTP API, you must authenticate with your GitHub account (fiskaly organization member).

1. Go to https://style.fiskaly.com/auth/login to log in.
2. Copy the generated Bearer Token.
3. Configure your MCP client (e.g., Lovable) to send this token in the Authorization header: Bearer <your-token>.

Note for Lovable users: Lovable cannot install npm packages. Use the HTTP API to fetch design tokens (colors, typography, spacing) and component specs, then recreate components that match the fiskaly design system.

# Server info (public)
curl https://style.fiskaly.com/mcp

# List all components (requires token)
curl -H "Authorization: Bearer <token>" https://style.fiskaly.com/mcp/components

# Get design tokens by category
curl https://style.fiskaly.com/mcp/tokens/color

# Health check
curl https://style.fiskaly.com/health

What This MCP Can Do

| Capability | Description | Example | Usage | | -------------------------- | ------------------------------------ | --------------------------------------- | ---------------------------------------------------------------- | | List components | Browse all components by category | "Show me all form components" | AI tools can install packages or recreate based on specs | | Get component docs | Props, types, usage examples | "How do I use the Hero component?" | AI tools can install packages or recreate based on specs | | Get design tokens | Colors, typography, spacing, shadows | "What's the brand color?" → #2dd4bf | All AI tools use this (Lovable recreates, others install) | | Get setup instructions | Installation and configuration | "How do I install fiskaly UI?" | Package-manager-enabled tools (Claude, Cursor) use this directly | | Correct imports | Know the right import path | @fiskaly/ui/sections vs @fiskaly/ui | Package-manager-enabled tools (Claude, Cursor, VS Code) use this |

Example Queries

"List all section components"           → Hero, Stats, Pricing, FeaturesGrid...
"Show me the Button component"          → Props, variants, usage code
"What colors are in the brand palette?" → brand-500: #2dd4bf, bunker: #0f181b...
"How do I set up fiskaly UI?"           → npm install, Tailwind config, imports
"Build a pricing page"                  → Uses Pricing, Hero with correct imports

Storybook Integration

This MCP server is designed to work alongside the fiskaly Storybook.

• Live Storybook: https://style.fiskaly.com
• What this MCP does: Extracts component definitions, props, and design tokens directly from the Storybook source code (packages/ui).
• Benefit: AI tools get structured data (JSON) without needing to parse the visual Storybook or run a headless browser.

Using with Storybook

You can use the MCP to query component details while viewing the visual examples in Storybook:

1. Open style.fiskaly.com to see the component visually.
2. Ask your AI tool: "How do I use the Button component?"
3. The AI uses the MCP to get the exact props, types, and import paths consistent with the live Storybook.

Adding Custom Instructions

For best results, combine the MCP with project-specific instructions:

┌─────────────────────────────────────────────────────────────────────────────┐
│                              AI Tool                                        │
│                    (Claude Desktop, Cursor, Lovable)                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
┌───────────────────────────────────┐ ┌───────────────────────────────────────┐
│         @fiskaly/ui-mcp           │ │         Custom Instructions           │
│         (This Package)            │ │         (Your Project)                │
│                                   │ │                                       │
│  ┌─────────────────────────────┐  │ │  ┌─────────────────────────────────┐  │
│  │ • Component names & imports │  │ │  │ • Project-specific patterns     │  │
│  │ • Props & usage examples    │  │ │  │ • File structure conventions    │  │
│  │ • Design tokens (colors,    │  │ │  │ • Coding standards              │  │
│  │   typography, spacing)      │  │ │  │ • Business logic rules          │  │
│  │ • Installation steps        │  │ │  │ • Preferred component choices   │  │
│  └─────────────────────────────┘  │ │  └─────────────────────────────────┘  │
│                                   │ │                                       │
│  "What components exist?"         │ │  "How should I structure this?"       │
│  "How do I use Button?"           │ │  "What's our auth pattern?"           │
└───────────────────────────────────┘ └───────────────────────────────────────┘
                    │                               │
                    └───────────────┬───────────────┘
                                    ▼
                    ┌───────────────────────────────┐
                    │    AI generates code with:    │
                    │  • Correct @fiskaly/ui usage  │
                    │  • Your project conventions   │
                    └───────────────────────────────┘

What Goes Where?

| Information Type | Location | Example | Lovable Usage | | ----------------------- | ----------------------- | ---------------------------------------- | ------------------------------------- | | Component APIs | MCP Server | "Button accepts variant, size, disabled" | Uses to recreate components | | Design tokens | MCP Server | "brand-500 is #2dd4bf" | Uses to match brand colors/typography | | Import paths | MCP Server | "Import Hero from @fiskaly/ui/sections" | N/A (can't install packages) | | Project file structure | Custom Instructions | "Pages go in src/app/" | Uses for project conventions | | Business logic patterns | Custom Instructions | "Use Zustand for client state" | Uses for architectural patterns | | Team conventions | Custom Instructions | "Prefix test files with .test.tsx" | Uses for coding standards |

Example Custom Instructions

Claude Desktop / Cursor (CLAUDE.md or .cursorrules):

## Component Library

Use @fiskaly/ui for all UI components. The MCP server provides details.

## Project Patterns

- Place pages in `src/app/`
- Use server components by default
- Prefer brand-500 (#2dd4bf) for CTAs

Lovable (Project Settings):

Use the fiskaly MCP (https://style.fiskaly.com/mcp) to get design tokens and component specs.
Since Lovable cannot install npm packages, recreate components based on the design system:
- Brand color: #2dd4bf (turquoise)
- Font: DM Sans
- Follow component patterns from MCP documentation

API Reference

MCP Tools

| Tool | Description | Input | | ----------------- | -------------------------------------- | ---------------------------------------------------------------------------- | | list_components | List all available components | { category?: "components" \| "sections" \| "forms" \| "layouts" \| "all" } | | get_component | Get component details, props, examples | { name: string } | | get_tokens | Get design tokens | { category?: "color" \| "typography" \| "border" \| "shadow" \| "all" } | | get_setup | Get installation instructions | {} |

MCP Resources

| URI | Description | | --------------------------- | ------------------------------------------ | | fiskaly://docs/components | Full @fiskaly/ui component documentation | | fiskaly://docs/theme | @fiskaly/theme design tokens documentation | | fiskaly://docs/setup | Installation and setup guide |

HTTP REST Endpoints

| Method | Endpoint | Description | | ------ | ----------------------- | --------------------- | | GET | /mcp | Server info | | GET | /mcp/components | All components list | | GET | /mcp/components/:name | Component details | | GET | /mcp/tokens | All design tokens | | GET | /mcp/tokens/:category | Tokens by category | | GET | /mcp/setup | Setup instructions | | GET | /mcp/docs/:type | Documentation by type | | POST | /mcp | MCP JSON-RPC endpoint | | GET | /health | Health check |

For Developers

How It Works

The MCP server bundles static data extracted at build time from the design system source files. No runtime Storybook instance is required - AI tools get instant responses from pre-compiled JSON.

Build Time                              Runtime
───────────────────────────────────     ───────────────────────────────
packages/ui/src/*/index.ts
packages/theme/dist/tokens.json    →    components.json
LOVABLE.md + */AI.md                    tokens.json
                                        docs.json
                                              │
                                              ▼
                                        MCP Server responds
                                        to AI tool queries

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  AI Tools (Claude, Cursor can install; Lovable uses tokens/specs)  │
└─────────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────────────┐
│    stdio transport      │     │      HTTP transport             │
│    (npx @fiskaly/ui-mcp)│     │      (Netlify Functions)        │
└─────────────────────────┘     └─────────────────────────────────┘
              │                               │
              └───────────────┬───────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      MCP Server Core                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │    Tools     │  │  Resources   │  │    Bundled Data      │  │
│  │              │  │              │  │                      │  │
│  │ list_comps   │  │ fiskaly://   │  │ • components.json    │  │
│  │ get_comp     │  │ docs/...     │  │ • tokens.json        │  │
│  │ get_tokens   │  │              │  │ • docs.json          │  │
│  │ get_setup    │  │              │  │                      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Local Development

npm install
npm run build          # Extract data + compile TypeScript
npm run dev            # Run MCP server (stdio)
npm run dev:http       # Run local HTTP server
npm run test           # Run vitest tests
npm run test:mcp       # Test MCP tool calls

Troubleshooting

Server doesn't start:

node --version         # Need 20+
npx @fiskaly/ui-mcp    # Try running directly

Tools not appearing in Claude Desktop:

1. Ensure valid JSON in config file
2. Restart Claude Desktop completely
3. Check logs: ~/Library/Logs/Claude/ (macOS)

Data Freshness & Caching

Important: The MCP server bundles data at build time as static ES module imports. Data is loaded once at process startup and never re-read from disk. This has implications depending on how you run the server.

How data flows

tokens.js (source)
    ↓  npm run build:tokens
theme/dist/tokens.json (generated)
    ↓  npm run extract-data
ui-mcp/src/data/tokens.json (copied)
    ↓  tsc (compile) or tsx (dev)
server.ts → static import → in-memory
    ↓
MCP responses (never changes until restart)

When the MCP server serves stale data

| Scenario | Why it's stale | Fix | | --------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------- | | npx @fiskaly/ui-mcp (published package) | Data was baked in at npm publish time. Changing local files has no effect. | Publish a new version, then restart the MCP client | | tsx src/cli.ts (local dev) | Data was extracted at last npm run build. File changes after build aren't picked up. | Run npm run build then restart the server | | Netlify HTTP endpoint | Data was bundled by esbuild at deploy time. | Push changes and wait for Netlify redeploy |

Monorepo development (recommended)

When working in this monorepo, use the local source instead of the published package to get immediate access to rebuilt data:

// .mcp.json (monorepo root)
{
  "mcpServers": {
    "fiskaly-ui": {
      "command": "npx",
      "args": ["tsx", "packages/ui-mcp/src/cli.ts"]
    }
  }
}

After changing tokens or components:

# 1. Rebuild theme tokens (if token values changed)
npm run build -w packages/theme

# 2. Re-extract MCP data
npm run build -w packages/ui-mcp

# 3. Restart your MCP client (Claude Code, Cursor, etc.)

Consumer usage (external projects)

External projects should use the published package:

{
  "mcpServers": {
    "fiskaly-ui": {
      "command": "npx",
      "args": ["@fiskaly/ui-mcp"]
    }
  }
}

Token data will update when a new version of @fiskaly/ui-mcp is published.

For Maintainers

Data Extraction

Data is extracted at build time from source files:

| Source | Output | Contains | | --------------------------------- | ----------------- | --------------------------- | | packages/ui/src/*/index.ts | components.json | Component names by category | | packages/theme/dist/tokens.json | tokens.json | W3C design tokens | | LOVABLE.md + */AI.md | docs.json | AI documentation |

Components are auto-detected from index.ts exports - no manual registration needed.

When to Update What

| Change | Action Required | | ------------------------------- | ------------------------------------------------- | | Add new component | None - auto-detected from index.ts exports | | Add new section/form/layout | None - auto-detected from index.ts exports | | Add new design tokens | None - auto-extracted from tokens.json | | Change component props | Update packages/ui/AI.md | | Change setup instructions | Update LOVABLE.md | | Remove/rename component | Update packages/ui/AI.md (note deprecation) |

After Making Changes

cd packages/ui-mcp
npm run build          # Re-extract data
npm run test           # Verify tests pass
npm run test:mcp       # Verify MCP tools work

Publishing

Reminder: The published npm package bundles static data. Consumers using npx @fiskaly/ui-mcp will only see updated tokens/components after a new version is published.

# 1. Ensure theme is built first (tokens are the source of truth)
npm run build -w packages/theme

# 2. Build MCP (extracts fresh data from theme + UI packages)
npm run build -w packages/ui-mcp

# 3. Version and publish
cd packages/ui-mcp
npm version patch      # or minor/major
npm publish

Version Strategy:

• Patch: Bug fixes, doc updates, token value changes
• Minor: New components, new tokens (backward compatible)
• Major: Removed components, breaking API changes

Common pitfall: If you update packages/theme/src/tokens.js but forget to run npm run build -w packages/theme before building ui-mcp, the extraction script will copy stale theme/dist/tokens.json into the MCP data.

File Structure

packages/ui-mcp/
├── src/
│   ├── server.ts          # Core MCP server logic
│   ├── server.test.ts     # Vitest tests
│   ├── cli.ts             # CLI entry point (stdio)
│   ├── index.ts           # Package exports
│   └── data/              # Extracted JSON (generated)
├── scripts/
│   ├── extract-data.ts    # Build-time extraction
│   ├── serve-local.ts     # Local HTTP server
│   └── test-mcp.ts        # MCP integration tests
├── netlify/
│   └── functions/
│       └── mcp.ts         # Netlify Function (HTTP)
├── public/
│   └── index.html         # Landing page for Netlify
├── mcp.md                  # Consumer docs (packaged with npm)
└── package.json

Related Packages

• @fiskaly/ui - React component library
• @fiskaly/theme - Design tokens and CSS
• @fiskaly/fonts - DM Sans and DM Mono fonts