npm package: @prismai/prism-mcp-server
Description: MCP server exposing Prism brand packages and design tokens to AI assistants
Latest version: 0.0.10

# 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

```bash
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)

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

#### Option 2: Local with NPX

```json
{
  "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

```json
{
  "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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```bash
# 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

```bash
# 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:

```bash
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](https://github.com/your-repo/prism-mcp-server/issues)
- Documentation: [Prism Brand Documentation](https://docs.prism.ai)

---

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