🎯 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:

# 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

# 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

npm run dev

Production

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:

{
  "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:

{
  "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:

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:

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

GET /health

Returns server status and timestamp.

🌐 Simple HTTP API

🔍 Search Icons

POST /api/search
Content-Type: application/json

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

📦 Get Specific Icon

POST /api/icon
Content-Type: application/json

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

🔌 MCP JSON-RPC Protocol

📋 List Available Tools

POST /rpc
Content-Type: application/json

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

⚡ Call a Tool

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

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:

{
  "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.

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

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:

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

[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:

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:

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:

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

# 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.