Icon Mcp

Icon MCP 服务

一个功能强大的模型上下文协议（MCP）服务，可在多个图标库中提供统一的搜索功能，并支持模糊搜索、智能缓存和全面的筛选选项。

🚀 功能

• 多库支持：同时搜索多个图标库
• 模糊搜索：使用 Fuse.js 进行高级搜索，并支持容错
• 智能缓存：通过智能缓存策略实现快速响应
• 全面筛选：按库、样式、类别、标签等进行筛选
• NPM 包集成：通过 NPM 包自动管理图标库
• TypeScript：完整的类型安全保障和出色的开发体验
• MCP 协议：标准的模型上下文协议，可无缝集成

📦 支持的图标库

• Bootstrap Icons - Bootstrap 官方开源 SVG 图标库
• Feather - 精美的开源图标
• Octicons - GitHub 的图标库
• Tabler Icons - 免费开源图标

🛠️ 安装

NPM 包

npm install -g icon-mcp

从源代码安装

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

构建图标索引

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

🚀 快速开始

作为 MCP 服务使用

# Start the MCP server
npm start

配置

可通过环境变量配置服务：

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

🔌 MCP 客户端配置

Claude Desktop

将图标 MCP 服务添加到 Claude Desktop 配置中：

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 扩展

在 VS Code 设置中配置 MCP 扩展：

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

本地开发环境设置

使用本地构建进行开发：

{
  "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 配置

使用 Docker 镜像：

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

客户端配置的环境变量

通过环境变量配置服务行为：

变量	描述	默认值	示例
CACHE_TTL	缓存生存时间，单位为毫秒	300000	600000
CACHE_MAX_SIZE	缓存条目的最大数量	1000	2000
DEFAULT_SEARCH_LIMIT	默认搜索结果数量	50	100
FUZZY_THRESHOLD	默认模糊搜索阈值（0.0-1.0）	0.3	0.5
LOG_LEVEL	日志详细程度	info	debug
NODE_ENV	环境模式	production	development

连接验证

配置 MCP 客户端后，验证连接：

1. 检查服务状态：服务应显示在 MCP 客户端的服务列表中
2. 测试基本工具：尝试使用 list_libraries 工具验证连通性
3. 检查日志：在客户端日志中查找连接消息

故障排除

常见问题

服务无法启动

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

# Reinstall if needed
npm install -g icon-mcp

权限错误

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

缺少图标索引

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

调试模式

启用调试日志以排查问题：

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

连接测试

手动测试服务：

# Start the server directly
npx icon-mcp

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

高级配置

自定义图标库

通过设置图标索引来配置其他图标库：

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

# Rebuild the icon index
npm run build-icons

性能调优

适用于高性能场景：

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

内存优化

适用于内存受限的环境：

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

📖 API 参考

可用工具

search_icons

通过名称在所有或指定的库中模糊搜索图标。

参数：

• query（字符串，必填）：图标名称的搜索词
• libraries（字符串数组，可选）：要搜索的指定库
• fuzzy（布尔值，可选）：启用模糊搜索（默认值：true）
• limit（数字，可选）：返回结果的最大数量（默认值：10）
• threshold（数字，可选）：模糊搜索阈值，范围为 0.0-1.0（默认值：0.3）
• includeScore（布尔值，可选）：包含匹配分数（默认值：true）

示例：

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

响应：

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

获取特定图标的详细信息。

参数：

• id（字符串，必填）：图标的唯一标识符
• library（字符串，必填）：图标所在的库名称

示例：

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

list_libraries

获取所有可用图标库的列表。

**参数：**无

响应：

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

get_library_info

获取特定库的详细信息。

参数：

• library（字符串，必填）：库名称

响应：

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

通过类别或标签模糊查找图标。

参数：

• category（字符串，必填）：要搜索的类别名称
• libraries（字符串数组，可选）：要搜索的指定库
• fuzzy（布尔值，可选）：启用模糊搜索（默认值：true）
• limit（数字，可选）：返回结果的最大数量（默认值：10）

🏗️ 架构

核心组件

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

提供程序系统

提供程序系统可轻松添加新的图标库：

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>;
}

搜索服务

搜索服务可在所有提供程序中进行统一搜索：

• 模糊搜索：由 Fuse.js 提供支持，可配置阈值
• 缓存：采用 TTL 和 LRU 淘汰策略的智能缓存
• 筛选：按库、样式、类别和标签进行高级筛选
• 性能：针对快速响应时间进行了优化

🧪 测试

# 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

🔧 开发

设置开发环境

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

添加新的图标库

1. 将该库添加为 NPM 依赖项：

npm install new-icon-library

2. 创建一个继承 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. 在 src/providers/index.ts 中注册该提供程序：

registry.register(new NewLibraryProvider());

4. 在 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'],
}

代码风格

• TypeScript：已启用严格模式
• ESLint：已配置 TypeScript 规则
• Prettier：统一代码格式
• Husky：用于质量检查的提交前钩子

📊 性能

• 搜索速度：启用缓存时，大多数查询耗时低于 100ms
• 内存使用：通过 LRU 缓存实现高效的内存管理
• 可扩展性：支持多个库中的数千个图标
• 模糊搜索：优化 Fuse.js 配置，以获得最佳性能

🔒 安全性

• 输入验证：使用 Zod 模式验证所有输入
• 输出清理：安全处理 SVG 内容
• 错误处理：全面处理错误，避免泄露信息
• 依赖项：定期进行安全审计和更新

🤝 贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 将更改推送到该分支：git push origin feature/amazing-feature
5. 发起 Pull Request

开发指南

• 为新功能编写测试
• 遵循 TypeScript 最佳实践
• 更新 API 变更的相关文档
• 确保所有 CI 检查均通过

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 Fuse.js，它提供了强大的模糊搜索功能
• 感谢 Model Context Protocol，它提供了标准协议
• 感谢所有图标库维护者的出色工作

📞 支持

• 问题反馈：GitHub Issues
• 讨论：GitHub Discussions
• 文档：Wiki

---

为开发者社区倾心打造 ❤️