@chrisreedio/fontawesome-pro-mcp/README.md

Font Awesome Pro MCP Server for icon search and retrieval

# 🎯 Font Awesome Pro MCP Server

A Model Context Protocol (MCP) server that provides fuzzy search and retrieval functionality for Font Awesome Pro icons. Built with Node.js, TypeScript, and Express.

## ✨ Features

- **🔍 Fuzzy Search**: Find icons using intelligent search with Fuse.js
- **📦 Icon Retrieval**: Get complete icon data including SVG content
- **🔌 MCP Compatible**: Standard JSON-RPC interface for MCP clients
- **🌐 Multiple Access Methods**: HTTP API, MCP protocol, and direct SVG endpoints
- **💎 Font Awesome Pro Support**: Access to all Pro icon styles (solid, regular, light, thin, duotone)

## 📋 Prerequisites

- Node.js 18+ 
- Font Awesome Pro license with NPM access token configured in `~/.npmrc`:
  ```
  @fortawesome:registry=https://npm.fontawesome.com/
  //npm.fontawesome.com/:_authToken=YOUR_TOKEN_HERE
  ```

## 🚀 Installation

### Option 1: NPM Package (Coming Soon)

Once published to NPM, you can install directly:

```bash
# Install and run via npx (no local setup required)
npx @chrisreedio/fontawesome-pro-mcp

# Or install globally
npm install -g @chrisreedio/fontawesome-pro-mcp
fontawesome-pro-mcp
```

### Option 2: Development/Local Setup

```bash
# Clone the repository
git clone https://github.com/chrisreedio/fontawesome-mcp.git
cd fontawesome-mcp

# Install dependencies (uses your FA Pro token automatically)
npm install

# Build the project
npm run build
```

## 🎮 Usage

### Development
```bash
npm run dev
```

### Production
```bash
npm start
```

The server runs on `http://localhost:8000` by default. Set `PORT` environment variable to change.

## 🔌 MCP Client Integration

### Claude Desktop

#### Option 1: NPM Package (Recommended)

Once published, use the npx approach for the easiest setup:

**Configuration File Location:**
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%/Claude/claude_desktop_config.json`

**Configuration:**
```json
{
  "mcpServers": {
    "fontawesome-pro": {
      "command": "npx",
      "args": ["-y", "@chrisreedio/fontawesome-pro-mcp"]
    }
  }
}
```

**Setup Steps:**
1. Add the configuration to Claude Desktop
2. Restart Claude Desktop
3. NPX will automatically download and run the server

**Benefits:**
- ✅ No local setup required
- ✅ Automatic updates when package is updated
- ✅ No path configuration needed
- ✅ Font Awesome Pro dependencies handled automatically

#### Option 2: Local Development Setup

For development or if you prefer local installation:

**Configuration:**
```json
{
  "mcpServers": {
    "fontawesome-pro": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/fontawesome-mcp/dist/mcp-server.js"]
    }
  }
}
```

**Setup Steps:**
1. Clone and build the project locally
2. Make sure Font Awesome Pro is installed: `npm install`
3. Build the MCP server: `npm run build`  
4. Add the configuration with your actual project path
5. Restart Claude Desktop

After setup:
1. The Font Awesome tools will appear in your Claude conversations
2. You can search for icons with `fuzzySearch` and get specific icons with `getIcon`
3. All Font Awesome Pro styles are supported (solid, regular, light, thin, duotone, brands)

### Claude Code CLI

#### Option 1: NPM Package (Recommended)

Once published, you can install directly via npx:

```bash
claude mcp add fontawesome-pro -- npx -y @chrisreedio/fontawesome-pro-mcp
```

This method automatically handles dependencies and updates.

#### Option 2: Local Installation

For development or local use:

```bash
claude mcp add fontawesome-pro node /ABSOLUTE/PATH/TO/fontawesome-mcp/dist/mcp-server.js
```

Replace `/ABSOLUTE/PATH/TO/fontawesome-mcp` with the full path to your project directory.

After adding:
1. The server will be available in all Claude Code sessions
2. Use the Font Awesome tools directly in your coding conversations
3. Perfect for finding and integrating icons into your projects

## 🔗 API Endpoints

### ❤️ Health Check
```bash
GET /health
```
Returns server status and timestamp.

### 🌐 Simple HTTP API

#### 🔍 Search Icons
```bash
POST /api/search
Content-Type: application/json

{
  "query": "home",
  "limit": 5,
  "style": "solid"  // optional: solid|regular|light|thin|duotone|brands
}
```

#### 📦 Get Specific Icon
```bash
POST /api/icon
Content-Type: application/json

{
  "name": "house-signal",
  "style": "solid"
}
```

### 🔌 MCP JSON-RPC Protocol

#### 📋 List Available Tools
```bash
POST /rpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

#### ⚡ Call a Tool
```bash
POST /rpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "fuzzySearch",
    "arguments": {
      "query": "search",
      "limit": 3
    }
  }
}
```

### 🎨 Direct SVG Access
```bash
GET /svg/:style/:name.svg
```
Example: `http://localhost:8000/svg/solid/house-signal.svg`

## 🛠️ Available Tools

### fuzzySearch
Search Font Awesome Pro icons using fuzzy matching.

**Parameters:**
- `query` (string): Search query for icons
- `limit` (number, optional): Maximum results to return (default: 20)  
- `style` (string, optional): Filter by icon style

**Returns:** Array of matching icons with metadata.

### getIcon
Get a specific Font Awesome Pro icon with complete data including SVG content.

**Parameters:**
- `name` (string): The icon name (e.g., "home", "user")
- `style` (string): The icon style (solid|regular|light|thin|duotone|brands)

**Returns:** Icon object with SVG content.

## 📄 Response Format

Icons are returned with the following structure:
```json
{
  "name": "house-signal",
  "style": "solid", 
  "label": "House Signal",
  "search": {
    "terms": ["abode", "building", "connect", "family", "home", "residence", "smart home", "wifi", "www"]
  },
  "unicode": "e012",
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 576 512\">...</svg>"
}
```

## 🏗️ Architecture

```
src/
├── server.ts          # Express server + MCP setup
├── fa/               # Font Awesome helpers
│   ├── types.ts      # TypeScript interfaces
│   └── loader.ts     # Metadata loading + SVG retrieval
└── methods/          # MCP method implementations
    ├── fuzzySearch.ts # Icon search functionality  
    └── getIcon.ts     # Icon retrieval functionality
```

## 🚢 Production Deployment

For production use, you'll want to run the server as a persistent service that automatically restarts on failure and survives system reboots. Here are the most common deployment approaches:

### ⚡ PM2 Process Manager (Recommended)
PM2 is a popular Node.js process manager that handles automatic restarts, logging, and clustering.

```bash
# Install PM2 globally
npm install -g pm2

# Start the server
pm2 start npm --name "fontawesome-mcp" -- start

# Save current PM2 processes
pm2 save

# Setup auto-restart on system reboot
pm2 startup

# Monitor the process
pm2 status
pm2 logs fontawesome-mcp
```

### 🐳 Docker
Containerized deployment for consistent environments and easy scaling.

First, create a `Dockerfile`:
```dockerfile
FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy source and build
COPY . .
RUN npm run build

# Expose port
EXPOSE 8000

# Start server
CMD ["npm", "start"]
```

Then build and run:
```bash
# Build image
docker build -t fontawesome-mcp .

# Run container
docker run -d -p 8000:8000 --restart unless-stopped --name fontawesome-mcp fontawesome-mcp

# View logs
docker logs fontawesome-mcp
```

### 🐧 systemd Service (Linux)
For Linux servers, systemd provides robust service management.

Create `/etc/systemd/system/fontawesome-mcp.service`:
```ini
[Unit]
Description=Font Awesome MCP Server
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/fontawesome-mcp
ExecStart=/usr/bin/node dist/server.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=8000

[Install]
WantedBy=multi-user.target
```

Enable and start the service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable fontawesome-mcp
sudo systemctl start fontawesome-mcp

# Check status
sudo systemctl status fontawesome-mcp
```

### 🔧 Environment Variables
Set these environment variables for production:
```bash
NODE_ENV=production
PORT=8000
LOG_LEVEL=info
```

## 🛠️ Development

### Scripts
- `npm run dev` - Development server with hot reload
- `npm run dev:mcp` - Start local MCP server in development mode
- `npm run build` - Build TypeScript to JavaScript
- `npm run start` - Run production server
- `npm run start:mcp` - Run local MCP server from built files
- `npm run clean` - Remove build artifacts

### Testing
Run the comprehensive test suite to verify functionality:

```bash
# Run all tests
npm test

# Run tests in watch mode (for development)
npm run test:watch

# Run tests with coverage report
npm run test:coverage
```

The test suite includes:
- **Unit Tests**: Core search and icon retrieval methods
- **Integration Tests**: Local MCP server functionality via stdio
- **HTTP API Tests**: All REST endpoints and MCP JSON-RPC interface
- **Error Handling**: Validation and edge case scenarios

Tests verify both the HTTP server and local MCP server implementations work correctly.

### Publishing

To publish this package to NPM:

```bash
# Ensure you're logged into NPM
npm login

# Publish the scoped package as public (required for @username/package-name format)
npm publish --access public
```

**Note:** This package uses a scoped name (`@chrisreedio/fontawesome-pro-mcp`), so the `--access public` flag is required to make it publicly accessible. Without this flag, NPM would try to publish it as a private package.

The package includes a `prepublishOnly` script that automatically builds the project before publishing.

### Key Dependencies
- **Express**: HTTP server framework
- **Fuse.js**: Fuzzy search implementation
- **js-yaml**: YAML parsing for FA metadata
- **zod**: Schema validation
- **@modelcontextprotocol/sdk**: MCP protocol support

## 📄 License

MIT

## 💎 Font Awesome Pro

This project requires Font Awesome Pro. Font Awesome Pro is a commercial product - ensure you have appropriate licensing for your use case.