Prism Brand Package MCP Server

A specialized MCP (Model Context Protocol) server that exposes Prism's brand package system to AI assistants like Claude, Cursor, and other MCP-compatible tools. This server enables AI assistants to retrieve brand packages, design tokens, logos, and brand guidelines to help developers build brand-consistent applications.

Features

🎨 Brand Package Management

• Get project brand packages - Retrieve all brand packages for a specific project
• Get active brand package - Find the currently active brand package for a project
• Get brand package details - Access complete brand package information including manifest

🎯 Design Tokens & Assets

• Get design tokens - Extract CSS custom properties and global styles
• Get brand logos - Access logo files in multiple variants (primary, stacked, mark, monogram)
• Get brand guide - Retrieve brand guide content and documentation

📋 Project Management

• List user projects - Discover accessible projects and organizations
• Get project details - Access project metadata and brand input configuration

Quick Start

Installation

Option 1: NPX (Recommended)

No installation required - use directly with npx @prismai/prism-mcp-server

Option 2: Global Installation

npm install -g @prismai/prism-mcp-server

Configuration

Create or update your MCP configuration file:

Global config: ~/.cursor/mcp.json (for newer Cursor versions) or ~/.cursor-ide/mcp.json (for older versions)
Project config: .cursor/mcp.json

Option 1: Hosted on Vercel (Recommended)

{
  "mcpServers": {
    "prism": {
      "url": "https://www.prismui.co/api/mcp",
      "auth": {
        "type": "bearer",
        "token": "prism_483609e2"
      }
    }
  }
}

Option 2: Local with NPX

{
  "mcpServers": {
    "prism": {
      "command": "npx",
      "args": ["-y", "@prismai/prism-mcp-server"],
      "env": {
        "PRISM_API_KEY": "prism_483609e2",
        "PRISM_API_URL": "https://www.prismui.co/api/"
      }
    }
  }
}

Option 3: Local with Global Installation

{
  "mcpServers": {
    "prism": {
      "command": "@prismai/prism-mcp-server",
      "env": {
        "PRISM_API_KEY": "prism_483609e2",
        "PRISM_API_URL": "https://www.prismui.co/api/"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | | -------------------- | -------- | --------------------------- | --------------------------------- | | PRISM_API_KEY | ✅ Yes | - | Your Prism API authentication key (get this from your Prism project settings) | | PRISM_API_URL | ❌ No | https://www.prismui.co/api/ | Prism API base URL | | MCP_SERVER_NAME | ❌ No | prism-brand-mcp | MCP server name | | MCP_SERVER_VERSION | ❌ No | 1.0.0 | MCP server version |

Getting Your API Key

1. Go to your Prism project at https://prismui.co/
2. Navigate to your project's Connect page
3. Your API key will be displayed there - copy it for use in the configuration above

Available Tools

Project Discovery

list_user_projects

List all projects accessible to the authenticated user.

• Parameters:
  • organizationId (optional): Filter projects by organization UUID
  • limit (optional): Number of projects to return (1-100, default: 20)
  • offset (optional): Pagination offset (default: 0)

get_project_details

Get detailed information about a specific project.

• Parameters:
  • projectId (required): Project UUID

Brand Package Management

get_project_brand_packages

Retrieve brand packages for a project.

• Parameters:
  • projectId (required): Project UUID
  • activeOnly (optional): Only return active brand packages (default: false)

get_active_brand_package

Get the currently active brand package for a project.

• Parameters:
  • projectId (required): Project UUID

get_brand_package_details

Get complete details for a specific brand package.

• Parameters:
  • brandPackageId (required): Brand package UUID

Design Assets & Tokens

get_design_tokens

Extract CSS design tokens and global styles.

• Parameters:
  • brandPackageId (required): Brand package UUID
  • includeGlobals (optional): Include global CSS styles (default: true)

get_brand_logos

Retrieve brand logo files with filtering options.

• Parameters:
  • brandPackageId (required): Brand package UUID
  • variant (optional): Logo variant ("primary", "stacked", "mark", "monogram")
  • mode (optional): Color mode ("light", "dark")
  • format (optional): File format ("png", "jpg", "svg")

get_brand_guide

Get brand guide documentation and README content.

• Parameters:
  • brandPackageId (required): Brand package UUID

UI Components

list_components

List all available UI components with categorization.

• Parameters: None
• Returns: Complete list of components grouped by category (Form, Layout, Navigation, Overlay, Feedback, Data Display, Interactive)

get_component_code

Get source code and metadata for a specific UI component.

• Parameters:
  • componentName (required): Component name in lowercase with hyphens (e.g., "button", "dialog", "dropdown-menu")
• Returns: Component source code, dependencies, usage examples, TypeScript interfaces, and metadata

Usage Examples

Getting Started with a Project

// 1. List your projects
await mcp.callTool("list_user_projects", { limit: 10 });

// 2. Get project details
await mcp.callTool("get_project_details", {
  projectId: "12345678-1234-1234-1234-123456789abc",
});

// 3. Get active brand package
await mcp.callTool("get_active_brand_package", {
  projectId: "12345678-1234-1234-1234-123456789abc",
});

Working with Design Tokens

// Get all design tokens
await mcp.callTool("get_design_tokens", {
  brandPackageId: "brand-package-uuid-here",
});

// Get tokens without global styles
await mcp.callTool("get_design_tokens", {
  brandPackageId: "brand-package-uuid-here",
  includeGlobals: false,
});

Retrieving Brand Assets

// Get all logos
await mcp.callTool("get_brand_logos", {
  brandPackageId: "brand-package-uuid-here",
});

// Get only primary logo in dark mode SVG
await mcp.callTool("get_brand_logos", {
  brandPackageId: "brand-package-uuid-here",
  variant: "primary",
  mode: "dark",
  format: "svg",
});

Working with UI Components

// List all available components
await mcp.callTool("list_components");

// Get specific component code
await mcp.callTool("get_component_code", {
  componentName: "button",
});

// Get complex component with usage example
await mcp.callTool("get_component_code", {
  componentName: "dialog",
});

Development

Local Development

# Clone and setup
cd apps/prism-mcp-server
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Type checking
npm run typecheck

Testing the Server

# Set environment variables
export PRISM_API_KEY="your_api_key_here"
export PRISM_API_URL="https://www.prismui.co/api/"

# Run the server
npm run dev

API Endpoints Used

This MCP server interfaces with the following Prism API endpoints:

• GET /api/v1/projects - List user projects
• GET /api/v1/projects/{id} - Get project details
• GET /api/v1/brand-packages - List brand packages
• GET /api/v1/brand-packages/{id} - Get brand package details
• GET /api/v1/components - List UI components
• GET /api/v1/components/{name} - Get component source code
• GET /health - Health check

Error Handling

The server provides detailed error messages for common issues:

• Authentication errors: Invalid or missing API key
• Not found errors: Invalid project or brand package IDs
• Validation errors: Malformed UUIDs or invalid parameters
• Network errors: API connectivity issues

Resources

In addition to tools, the server provides these resources:

• prism/health - Server and API health status
• prism/info - Server information and available tools

Troubleshooting

Common Issues

1. "API Error (401): Unauthorized"

   • Check that PRISM_API_KEY is set correctly
   • Verify the API key is valid and not expired

2. "API Error (404): Project not found"

   • Ensure the project ID is a valid UUID
   • Verify you have access to the project

3. "Network error: fetch failed"

   • Check internet connectivity
   • Verify PRISM_API_URL is correct

Debug Mode

Set DEBUG=true environment variable for verbose logging:

DEBUG=true PRISM_API_KEY=your_key npx @prismai/prism-mcp-server

License

MIT License - see LICENSE file for details.

Support

For issues and feature requests, please visit:

• GitHub Issues: Create an issue
• Documentation: Prism Brand Documentation

Built for the Prism Design System - Enabling AI-assisted brand-consistent development.