npm package: @mekari/pixel3-mcp-server
Description: MCP server for Pixel 3
Latest version: 0.1.0

# @mekari/pixel3-mcp-server

A Model Context Protocol (MCP) server that provides AI assistants with access to Mekari Pixel (Pixel3) documentation, design tokens, and component generation capabilities.

## 🚀 Features

- **Semantic Search**: Advanced BM25-indexed search through Pixel3 documentation
- **Figma Integration**: Convert Figma designs to Pixel3 Vue components
- **Design Token Access**: Comprehensive access to Pixel3 design tokens (v2.1 and v2.4)
- **Component Library**: Search through all available Pixel3 components
- **AI Synthesis**: Optional OpenAI integration for enhanced responses
- **MCP Compliance**: Full Model Context Protocol server implementation

## 📦 Installation

### Global Installation
```bash
npm install -g @mekari/pixel3-mcp-server
```

### Local Development
```bash
git clone <repository-url>
cd pixel3/libs/mcp-server
npm install
npm run build
```

## 🛠️ Usage

### Command Line
```bash
# Run the server directly
mcp-server-pixel3

# Or with npx
npx @mekari/pixel3-mcp-server
```

### MCP Client Integration
The server implements the Model Context Protocol and can be integrated with any MCP-compatible client:

```json
{
  "mcpServers": {
    "pixel3": {
      "command": "npx",
      "args": ["@mekari/pixel3-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## 🔧 Available Tools

### 1. `ask_pixel`
Advanced semantic search through Pixel3 documentation using BM25 indexing.

**Parameters:**
- `query` (string): The search query to find relevant documentation
- `topK` (number, optional): Number of top results to return (1-12, default: 6)
- `maxContextChars` (number, optional): Maximum characters for context blocks (4000-24000, default: 12000)
- `openaiApiKey` (string, optional): OpenAI API key for AI synthesis

**Example:**
```json
{
  "query": "how to create button component",
  "topK": 8,
  "maxContextChars": 15000
}
```

### 2. `figma_to_pixel`
Convert Figma designs to Mekari Pixel (Pixel3) Vue components.

**Parameters:**
- `figmaNodeData`: Figma node data from Figma MCP server
- `componentName` (string, optional): Custom component name
- `outputFormat` (string): Output format - 'vue', 'vue-ts', or 'jsx'
- `includeStyles` (boolean): Include CSS styles and design tokens

**Example:**
```json
{
  "figmaNodeData": { "id": "1:2", "name": "Button", "type": "COMPONENT" },
  "componentName": "CustomButton",
  "outputFormat": "vue-ts",
  "includeStyles": true
}
```

## 📚 Data Sources

The server includes comprehensive Pixel3 documentation:

- **Component Documentation**: Complete component library with examples
- **Design Tokens**: Both v2.1 and v2.4 design token systems
- **API References**: Detailed component APIs and usage patterns
- **Best Practices**: Design system guidelines and recommendations

## ⚙️ Configuration

### Environment Variables

The server supports the following environment variables for configuration:

#### Core Configuration
- **`PIXEL_BM25_INDEX_PATH`**: Custom path to the BM25 index file (defaults to `data/bm25.index.json`)
- **`TOP_K`**: Default number of search results to return (defaults to 6)
- **`MAX_CONTEXT_CHARS`**: Default maximum characters for context blocks (defaults to 12000)

#### AI Integration
- **`OPENAI_API_KEY`**: OpenAI API key for AI synthesis (optional - only used if provided)

#### Server Configuration
- **`MCP_MODE`**: Automatically set to `'true'` by the server to disable console logging and prevent MCP communication corruption

#### Usage Examples

**Basic Configuration:**
```bash
# Set custom index path
export PIXEL_BM25_INDEX_PATH="/custom/path/to/index.json"

# Configure default search results
export TOP_K="8"

# Set maximum context length
export MAX_CONTEXT_CHARS="15000"
```

**With OpenAI Integration:**
```bash
# Enable AI synthesis capabilities
export OPENAI_API_KEY="sk-your-openai-api-key-here"
```

**In MCP Client Configuration:**
```json
{
  "mcpServers": {
    "pixel3": {
      "command": "npx",
      "args": ["@mekari/pixel3-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "TOP_K": "10",
        "MAX_CONTEXT_CHARS": "20000"
      }
    }
  }
}
```

#### Important Notes
- **`MCP_MODE`** is automatically set by the server and should not be manually configured
- **`OPENAI_API_KEY`** is optional - the server works without it but won't provide AI synthesis
- All numeric environment variables are parsed as strings and converted internally
- The server gracefully handles missing environment variables by using sensible defaults

### Build Configuration
```bash
# Build the server
npm run build

# Watch mode for development
npm run build:watch

# TypeScript watch mode
npm run watch
```

## 🧪 Testing

### Local Testing
```bash
# Test the server directly
node dist/index.js

# Test with JSON-RPC message
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
```

### Claude Integration
Copy one of the provided configuration files to Claude's MCP configuration directory:

- `claude-mcp-config.json` - Absolute path configuration
- `claude-mcp-config-relative.json` - NPX-based configuration
- `claude-mcp-config-dev.json` - Development configuration

### Local Development Configuration

For local development with MCP-compatible clients, use this configuration:

```json
{
  "mcpServers": {
    "pixel3-local": {
      "command": "node",
      "args": ["./libs/mcp-server/dist/index.js"],
      "cwd": "/path/to/your/pixel3/project",
      "env": {
        "NODE_ENV": "development",
        "TOP_K": "8",
        "MAX_CONTEXT_CHARS": "15000"
      }
    }
  }
}
```

**Alternative: Using npm script**
```json
{
  "mcpServers": {
    "pixel3-dev": {
      "command": "npm",
      "args": ["run", "mcp-server"],
      "cwd": "/path/to/your/pixel3/project",
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}
```

**Note**: Make sure to:
1. Replace `/path/to/your/pixel3/project` with your actual project path
2. Build the server first with `npm run build` in the `libs/mcp-server` directory
3. Ensure the `dist/index.js` file exists before starting the MCP client



## 🔍 Search Capabilities

The server uses a sophisticated BM25 search algorithm with:

- **Source Weighting**: Different weights for different documentation sources
- **Content Indexing**: Full-text search across all documentation
- **Ranked Results**: Intelligent result ranking based on relevance
- **Context Extraction**: Smart context block generation for AI consumption

## 🎨 Figma Integration

Convert Figma designs to Pixel3 components with:

- **Component Mapping**: Automatic Figma-to-Pixel component conversion
- **Style Preservation**: Maintain design tokens and styling
- **Multiple Formats**: Support for Vue, TypeScript, and JSX output
- **Responsive Design**: Generate responsive component layouts

## 📖 API Reference

### MCP Server Capabilities
- `prompts`: Prompt management
- `resources`: Resource subscription
- `tools`: Tool execution
- `logging`: Logging capabilities
- `completions`: Completion generation

### Rate Limiting
- Query cooldown: 5 seconds between similar queries
- Prevents rapid successive calls
- Maintains server performance