使用说明

图标MCP服务器

一个强大的模型上下文协议（MCP）服务器，提供跨多个图标库的统一搜索功能，具有模糊搜索、智能缓存和全面的过滤选项。

🚀 特性

多库支持：同时搜索多个图标库
模糊搜索：使用Fuse.js进行高级搜索，允许拼写错误
智能高速缓存：智能缓存策略的快速响应时间
综合过滤：按库、样式、类别、标签等筛选
NPM包集成：通过NPM包自动管理图标库
TypeScript：全类型安全和出色的开发人员体验
MCP协议：无缝集成的标准模型上下文协议

📦 支持的图标库

Bootstrap图标 -Bootstrap官方开源SVG图标库
羽毛 -美丽的开源图标
Octicons -GitHub的图标库
Tabler图标 -免费和开源图标

🛠️ 安装

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客户端的配置

克劳德桌面

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

视窗: %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代码MCP扩展

在VS代码设置中配置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 验证连接的工具
检查日志：在客户端日志中查找连接消息

故障排除

常见问题

服务器未启动

# 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 （string[]，可选）：要搜索的特定库
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 （string，必填）：库的名称

答复：

{
  "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 （string[]，可选）：要搜索的特定库
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

添加新图标库

将库添加为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 'Description of the new library';
  }

  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: 'Description of the new library',
  sourceUrl: 'https://github.com/library/icons',
  license: 'MIT',
  iconPaths: ['icons/*.svg'],
  styles: ['regular'],
}

代码的风格

TypeScript：严格模式已启用
ESLint：配置了TypeScript规则
更漂亮：一致的代码格式
哈士奇：用于质量检查的预提交挂钩

📊 演出

搜索速度：对于大多数具有缓存的查询，<100ms
内存使用：使用LRU缓存进行高效内存管理
可扩展性：支持跨多个库的数千个图标
模糊搜索：优化Fuse.js配置以获得最佳性能

🔒 安全

输入验证：所有输入均已Zod模式验证
输出消毒：SVG内容的安全处理
错误处理：全面的错误处理，无信息泄露
依赖项：定期安全审计和更新

🤝 贡献

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
提交您的更改： git commit -m 'Add amazing feature'
推到分支： git push origin feature/amazing-feature
打开拉取请求

开发指南

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

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

Fuse.js 强大的模糊搜索功能
模型上下文协议对于标准协议
所有图标库维护者，感谢他们出色的工作

📞 支持

问题: GitHub问题
讨论: GitHub讨论
文档: 维基

由以下材料制成❤️ 面向开发者社区

使用说明

图标MCP服务器

🚀 特性

📦 支持的图标库

🛠️ 安装

NPM包

来源

构建图标索引

🚀 快速开始

作为MCP服务器

配置

🔌 MCP客户端的配置

克劳德桌面

VS代码MCP扩展

地方发展设置

Docker配置

客户端配置的环境变量

连接验证

故障排除

常见问题

调试模式

连接测试

高级配置

自定义图标库

性能调整

内存优化

📖 api参考

可用工具

search_icons

get_icon

list_libraries

get_library_info

search_by_category

🏗️ 建筑

核心组件

提供商系统

搜索服务

🧪 测试

🔧 发展

设置开发环境

添加新图标库

代码的风格

📊 演出

🔒 安全

🤝 贡献

开发指南

📄 许可证

🙏 致谢

📞 支持

相关 MCP

图标搜索工具

图标搜索工具

图标管理工具

TouchDesigner文档协议服务器

图标搜索服务

Noun Project 图标搜索与下载 MCP 服务

`search_icons`

`get_icon`

`list_libraries`

`get_library_info`

`search_by_category`