agentic-ph/icon-mcp

Icon MCP Server

A powerful Model Context Protocol (MCP) server that provides unified search capabilities across multiple icon libraries with fuzzy search, intelligent caching, and comprehensive filtering options.

🚀 Features

• Multi-Library Support: Search across multiple icon libraries simultaneously
• Fuzzy Search: Advanced search with typo tolerance using Fuse.js
• Intelligent Caching: Fast response times with smart caching strategies
• Comprehensive Filtering: Filter by library, style, category, tags, and more
• NPM Package Integration: Automatic icon library management via NPM packages
• TypeScript: Full type safety and excellent developer experience
• MCP Protocol: Standard Model Context Protocol for seamless integration

📦 Supported Icon Libraries

• Bootstrap Icons - Official open source SVG icon library for Bootstrap
• Feather - Beautiful open source icons
• Octicons - GitHub's icon library
• Tabler Icons - Free and open source icons

🛠️ Installation

NPM Package

npm install -g icon-mcp

From Source

git clone https://github.com/your-org/icon-mcp.git
cd icon-mcp
npm install
npm run build

Build Icon Index

# Build icon indices from NPM packages
npm run build-icons

🚀 Quick Start

As MCP Server

# Start the MCP server
npm start

Configuration

The server can be configured via environment variables:

# Cache configuration
CACHE_TTL=300000          # Cache TTL in milliseconds (default: 5 minutes)
CACHE_MAX_SIZE=1000       # Maximum cache entries (default: 1000)

# Search configuration
DEFAULT_SEARCH_LIMIT=50   # Default search result limit
FUZZY_THRESHOLD=0.3       # Default fuzzy search threshold

# Logging
LOG_LEVEL=info           # Logging level (error, warn, info, debug)

🔌 Configuration for MCP Clients

Claude Desktop

Add the icon MCP server to your Claude Desktop configuration:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "icon-search": {
      "command": "npx",
      "args": ["icon-mcp"],
      "env": {
        "CACHE_TTL": "300000",
        "DEFAULT_SEARCH_LIMIT": "50",
        "LOG_LEVEL": "info"
      }
    }
  }
}

VS Code MCP Extension

Configure the MCP extension in VS Code settings:

{
  "mcp.servers": [
    {
      "name": "icon-search",
      "command": "npx",
      "args": ["icon-mcp"],
      "cwd": "${workspaceFolder}",
      "env": {
        "CACHE_TTL": "300000",
        "DEFAULT_SEARCH_LIMIT": "50"
      }
    }
  ]
}

Local Development Setup

For development with a local build:

{
  "mcpServers": {
    "icon-search-dev": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/icon-mcp",
      "env": {
        "NODE_ENV": "development",
        "LOG_LEVEL": "debug",
        "CACHE_TTL": "60000"
      }
    }
  }
}

Docker Configuration

Using the Docker image:

{
  "mcpServers": {
    "icon-search-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "CACHE_TTL=300000",
        "--env",
        "LOG_LEVEL=info",
        "icon-mcp:latest"
      ]
    }
  }
}

Environment Variables for Client Configuration

Configure the server behavior through environment variables:

Connection Verification

After configuring your MCP client, verify the connection:

1. Check Server Status: The server should appear in your MCP client's server list
2. Test Basic Tool: Try the list_libraries tool to verify connectivity
3. Check Logs: Look for connection messages in the client logs

Troubleshooting

Common Issues

Server Not Starting

# Check if the package is installed
npm list -g icon-mcp

# Reinstall if needed
npm install -g icon-mcp

Permission Errors

# On Unix systems, ensure proper permissions
chmod +x $(which icon-mcp)

Icon Index Missing

# Build the icon index
cd /path/to/icon-mcp
npm run build-icons

Debug Mode

Enable debug logging for troubleshooting:

{
  "mcpServers": {
    "icon-search": {
      "command": "npx",
      "args": ["icon-mcp"],
      "env": {
        "LOG_LEVEL": "debug",
        "NODE_ENV": "development"
      }
    }
  }
}

Connection Testing

Test the server manually:

# Start the server directly
npx icon-mcp

# Or with debug output
LOG_LEVEL=debug npx icon-mcp

Advanced Configuration

Custom Icon Libraries

Configure additional icon libraries by setting up the icon index:

# Add custom libraries to package.json dependencies
npm install custom-icon-library

# Rebuild the icon index
npm run build-icons

Performance Tuning

For high-performance scenarios:

{
  "env": {
    "CACHE_TTL": "1800000",
    "CACHE_MAX_SIZE": "5000",
    "DEFAULT_SEARCH_LIMIT": "100",
    "FUZZY_THRESHOLD": "0.2"
  }
}

Memory Optimization

For memory-constrained environments:

{
  "env": {
    "CACHE_MAX_SIZE": "500",
    "DEFAULT_SEARCH_LIMIT": "25",
    "NODE_OPTIONS": "--max-old-space-size=512"
  }
}

📖 API Reference

Available Tools

search_icons

Search for icons by name across all or specific libraries with fuzzy matching.

Parameters:

• query (string, required): Search term for icon names
• libraries (string[], optional): Specific libraries to search in
• fuzzy (boolean, optional): Enable fuzzy search (default: true)
• limit (number, optional): Maximum results to return (default: 10)
• threshold (number, optional): Fuzzy search threshold 0.0-1.0 (default: 0.3)
• includeScore (boolean, optional): Include match scores (default: true)

Example:

{
  "query": "home",
  "libraries": ["bootstrap-icons", "feather"],
  "fuzzy": true,
  "limit": 20,
  "threshold": 0.3
}

Response:

{
  "query": "home",
  "results": [
    {
      "item": {
        "name": "house",
        "library": "bootstrap-icons",
        "tags": ["house", "home", "building"],
        "style": "regular",
        "path": "node_modules/bootstrap-icons/icons/house.svg",
        "categories": ["navigation"],
        "size": "16x16"
      },
      "score": 0.0
    }
  ],
  "totalResults": 15,
  "searchType": "fuzzy",
  "executionTime": 45,
  "libraries": ["bootstrap-icons", "feather"]
}

get_icon

Get detailed information about a specific icon.

Parameters:

• id (string, required): Unique identifier of the icon
• library (string, required): Library name where the icon is located

Example:

{
  "id": "house",
  "library": "bootstrap-icons"
}

list_libraries

Get a list of all available icon libraries.

Parameters: None

Response:

{
  "libraries": ["bootstrap-icons", "feather", "octicons", "lucide", "tabler-icons"],
  "count": 5
}

get_library_info

Get detailed information about a specific library.

Parameters:

• library (string, required): Name of the library

Response:

{
  "name": "bootstrap-icons",
  "displayName": "Bootstrap Icons",
  "description": "Official open source SVG icon library for Bootstrap",
  "version": "1.11.3",
  "iconCount": 1800,
  "categories": ["navigation", "communication", "media", "ui"],
  "styles": ["regular"],
  "isAvailable": true
}

search_by_category

Find icons by category or tag with fuzzy matching.

Parameters:

• category (string, required): Category name to search for
• libraries (string[], optional): Specific libraries to search in
• fuzzy (boolean, optional): Enable fuzzy search (default: true)
• limit (number, optional): Maximum results to return (default: 10)

🏗️ Architecture

Core Components

src/
├── index.ts                 # Main MCP server entry point
├── providers/               # Icon provider implementations
│   ├── icon-provider.interface.ts
│   ├── base-npm-provider.ts
│   ├── heroicons.provider.ts
│   ├── bootstrap-icons.provider.ts
│   ├── feather.provider.ts
│   ├── octicons.provider.ts
│   ├── lucide.provider.ts
│   ├── simple-icons.provider.ts
│   └── tabler-icons.provider.ts
├── services/               # Core services
│   ├── search.service.ts   # Unified search service
│   └── cache.service.ts    # Caching service
├── tools/                  # MCP tools
│   └── index.ts           # Icon search tools
├── types/                  # TypeScript type definitions
│   └── index.ts
└── utils/                  # Utility functions
    └── errors.ts

Provider System

The provider system allows easy addition of new icon libraries:

export abstract class IconProvider {
  abstract initialize(): Promise<void>;
  abstract searchIcons(query: string, options?: FuseSearchOptions): Promise<FuseResult<Icon>[]>;
  abstract getIcon(id: string): Promise<Icon | null>;
  abstract getAllIcons(): Promise<Icon[]>;
  abstract getInfo(): Promise<IconLibrary>;
}

Search Service

The search service provides unified search across all providers:

• Fuzzy Search: Powered by Fuse.js with configurable thresholds
• Caching: Intelligent caching with TTL and LRU eviction
• Filtering: Advanced filtering by library, style, category, and tags
• Performance: Optimized for fast response times

🧪 Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

# Run performance tests
npm run test:performance

🔧 Development

Setup Development Environment

git clone https://github.com/your-org/icon-mcp.git
cd icon-mcp
npm install

# Install icon library dependencies
npm install

# Build the project
npm run build

# Start in development mode
npm run dev

Adding New Icon Libraries

1. Add the library as an NPM dependency:

npm install new-icon-library

2. Create a provider class extending BaseNpmProvider:

export class NewLibraryProvider extends BaseNpmProvider {
  constructor() {
    super('new-library', 'New Library', '1.0.0', 'new-icon-library', ['icons/*.svg']);
  }

  protected getDescription(): string {
    return 'Description of the new library';
  }

  protected getSourceUrl(): string {
    return 'https://github.com/library/icons';
  }

  protected getLicense(): string {
    return 'MIT';
  }
}

3. Register the provider in src/providers/index.ts:

registry.register(new NewLibraryProvider());

4. Add the library configuration to scripts/build-index.js:

'new-icon-library': {
  name: 'new-library',
  displayName: 'New Library',
  description: 'Description of the new library',
  sourceUrl: 'https://github.com/library/icons',
  license: 'MIT',
  iconPaths: ['icons/*.svg'],
  styles: ['regular'],
}

Code Style

• TypeScript: Strict mode enabled
• ESLint: Configured with TypeScript rules
• Prettier: Consistent code formatting
• Husky: Pre-commit hooks for quality checks

📊 Performance

• Search Speed: < 100ms for most queries with caching
• Memory Usage: Efficient memory management with LRU caching
• Scalability: Supports thousands of icons across multiple libraries
• Fuzzy Search: Optimized Fuse.js configuration for best performance

🔒 Security

• Input Validation: All inputs validated with Zod schemas
• Output Sanitization: Safe handling of SVG content
• Error Handling: Comprehensive error handling without information leakage
• Dependencies: Regular security audits and updates

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Write tests for new features
• Follow TypeScript best practices
• Update documentation for API changes
• Ensure all CI checks pass

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Fuse.js for powerful fuzzy search capabilities
• Model Context Protocol for the standard protocol
• All the icon library maintainers for their amazing work

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

Made with ❤️ for the developer community