图标-MCP

Name: 图标-MCP
Author: agentic-ph

作者：agentic-ph4 星标更新：2025-08-02

安装使用来源：spider==github.com

项目介绍

Icon MCP Server

一个强大的模型上下文协议（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

构建图标索引

# 从 NPM 包构建图标索引
npm run build-icons

🚀 快速开始

作为 MCP 服务器

# 启动 MCP 服务器
npm start

配置

服务器可以通过环境变量进行配置：

# 缓存配置
CACHE_TTL=300000          # 缓存生存时间（毫秒，默认：5分钟）
CACHE_MAX_SIZE=1000       # 最大缓存条目数（默认：1000）

# 搜索配置
DEFAULT_SEARCH_LIMIT=50   # 默认搜索结果限制
FUZZY_THRESHOLD=0.3       # 默认模糊搜索阈值

# 日志
LOG_LEVEL=info           # 日志级别（error, warn, info, debug）

🔌 MCP 客户端配置

Claude Desktop

在 Claude Desktop 配置中添加图标 MCP 服务器：

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 客户端后，验证连接：

检查服务器状态：服务器应出现在 MCP 客户端的服务器列表中
测试基础工具：尝试 list_libraries 工具以验证连接性
检查日志：查看客户端日志中的连接消息

故障排除

常见问题

服务器无法启动

# 检查包是否已安装
npm list -g icon-mcp

# 如需重新安装
npm install -g icon-mcp

权限错误

# 在 Unix 系统上，确保正确的权限
chmod +x $(which icon-mcp)

图标索引丢失

# 构建图标索引
cd /path/to/icon-mcp
npm run build-icons

调试模式

启用调试日志以进行故障排除：

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

连接测试

手动测试服务器：

# 直接启动服务器
npx icon-mcp

# 或带有调试输出
LOG_LEVEL=debug npx icon-mcp

高级配置

自定义图标库

通过设置图标索引来配置额外的图标库：

# 将自定义库添加到 package.json 依赖项
npm install custom-icon-library

# 重建图标索引
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": "官方开源的 Bootstrap SVG 图标库",
  "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                 # 主 MCP 服务器入口点
├── providers/               # 图标提供者实现
│   ├── 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/               # 核心服务
│   ├── search.service.ts   # 统一搜索服务
│   └── cache.service.ts    # 缓存服务
├── tools/                  # MCP 工具
│   └── index.ts           # 图标搜索工具
├── types/                  # TypeScript 类型定义
│   └── index.ts
└── utils/                  # 实用函数
    └── 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 资源回收的智能缓存
过滤：通过库、风格、类别和标签进行高级过滤
性能：优化以实现快速响应时间

🧪 测试

# 运行所有测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 运行集成测试
npm run test:integration

# 运行性能测试
npm run test:performance

🔧 开发

设置开发环境

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

# 安装图标库依赖项
npm install

# 构建项目
npm run build

# 在开发模式下启动
npm run dev

添加新图标库

将库作为 NPM 依赖项添加：

npm install new-icon-library

创建一个扩展 BaseNpmProvider 的提供者类：

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

  protected getDescription(): string {
    return '新库的描述';
  }

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

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

在 src/providers/index.ts 中注册提供者：

registry.register(new NewLibraryProvider());

在 scripts/build-index.js 中添加库配置：

'new-icon-library': {
  name: 'new-library',
  displayName: 'New Library',
  description: '新库的描述',
  sourceUrl: 'https://github.com/library/icons',
  license: 'MIT',
  iconPaths: ['icons/*.svg'],
  styles: ['regular'],
}

代码风格

TypeScript：启用严格模式
ESLint：配置了 TypeScript 规则
Prettier：一致的代码格式化
Husky：预提交钩子进行质量检查

📊 性能

搜索速度：大多数查询在缓存情况下小于 100ms
内存使用：通过 LRU 缓存实现高效的内存管理
可扩展性：支持数千个图标跨越多个库
模糊搜索：优化的 Fuse.js 配置以获得最佳性能

🔒 安全

输入验证：所有输入都通过 Zod 模式进行验证
输出净化：安全处理 SVG 内容
错误处理：全面的错误处理，不泄露信息
依赖项：定期进行安全审计和更新

🤝 贡献

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature
提交更改：git commit -m '添加神奇的功能'
推送到分支：git push origin feature/amazing-feature
打开拉取请求

开发指南

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

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

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

📞 支持

问题：GitHub Issues
讨论：GitHub Discussions
文档：Wiki

为开发者社区制作 ❤️