npm package: @liangshanli/mcp-server-icon
Description: MCP Icon server for searching and fetching icons from iconfont.cn
Author: liliangshan
Latest version: 1.4.0

# MCP Icon Server

一个基于 MCP (Model Context Protocol) 的图标服务器，用于从 iconfont.cn 搜索和获取图标。

## 功能特性

- 🔍 **图标搜索**: 从 iconfont.cn 搜索图标
- 📄 **图标详情**: 获取图标的详细信息
- 🎨 **SVG 获取**: 获取图标的 SVG 格式内容
- ⚡ **缓存机制**: 内置缓存提高性能
- 🔧 **灵活配置**: 支持自定义尺寸和颜色
- 🌐 **多语言支持**: 支持中文和英文界面
- 🖥️ **Web界面**: 提供可视化图标选择和保存功能
- 🏗️ **模块化架构**: 工具方法重构，提高代码可维护性

## 安装

### 全局安装（推荐）
```bash
npm install -g @liangshanli/mcp-server-icon
```

### 本地安装
```bash
npm install @liangshanli/mcp-server-icon
```

### 从源码安装
```bash
git clone https://github.com/liliangshan/mcp-server-icon.git
cd mcp-server-icon
npm install
```

## 使用方法

### 1. 直接运行（全局安装）
```bash
mcp-server-icon
```

### 2. 使用 npx（推荐）
```bash
npx @liangshanli/mcp-server-icon
```

### 3. 直接启动（源码安装）
```bash
npm start
```

### 4. 开发模式（带调试）
```bash
npm run dev
```

### 5. 守护进程模式
```bash
npm run daemon
```

## 编辑器集成

### Cursor 编辑器配置

1. 在项目根目录创建 `.cursor/mcp.json` 文件：

```json
{
  "mcpServers": {
    "icon": {
      "command": "npx",
      "args": ["@liangshanli/mcp-server-icon"],
      "env": {
        "LANGUAGE": "zh-CN",
        "WEB_SERVER_AUTO_OPEN": "true"
      }
    }
  }
}
```

### VS Code 配置

1. 安装 VS Code 的 MCP 扩展
2. 创建 `.vscode/settings.json` 文件：

```json
{
  "mcp.servers": {
    "icon": {
      "command": "npx",
      "args": ["@liangshanli/mcp-server-icon"],
      "env": {
        "LANGUAGE": "zh-CN",
        "WEB_SERVER_AUTO_OPEN": "true"
      }
    }
  }
}
```

### 作为 MCP 服务器

服务器启动后通过 stdin/stdout 与 MCP 客户端通信：

```json
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05"}}
```

### 环境变量

- `LANGUAGE`: 界面语言设置（`en` 或 `zh-CN`，默认: `en`）
- `WEB_SERVER_AUTO_OPEN`: 是否自动打开浏览器（`true` 或 `false`，默认: `true`）

## API 工具

### 1. search_icons

搜索图标

**参数:**
- `q` (string): 搜索关键词
- `sortType` (string): 排序类型，默认 `updated_at`
- `page` (number): 页码，默认 1
- `pageSize` (number): 每页数量，默认 54，最大 100
- `sType` (string): 搜索类型过滤
- `fromCollection` (number): 集合过滤，默认 -1（全部）
- `fills` (string): 填充类型过滤

**示例:**
```json
{
  "name": "search_icons",
  "arguments": {
    "q": "用户",
    "page": 1,
    "pageSize": 20
  }
}
```

### 2. get_icon_details

获取图标详细信息

**参数:**
- `iconId` (number): 图标 ID

**示例:**
```json
{
  "name": "get_icon_details",
  "arguments": {
    "iconId": 145442
  }
}
```

### 3. get_icon_svg

获取图标的 SVG 内容

**参数:**
- `iconId` (number): 图标 ID
- `width` (number): SVG 宽度，默认 24
- `height` (number): SVG 高度，默认 24
- `color` (string): SVG 填充颜色，默认 `currentColor`

**示例:**
```json
{
  "name": "get_icon_svg",
  "arguments": {
    "iconId": 145442,
    "width": 32,
    "height": 32,
    "color": "#FF9000"
  }
}
```

### 4. get_cache_stats

获取缓存统计信息

### 5. clear_cache

清除缓存

**参数:**
- `expiredOnly` (boolean): 仅清除过期条目，默认 false

### 6. start_web_server

启动Web服务器

**参数:**
- `port` (number): 服务器端口，默认 3000
- `autoOpen` (boolean): 是否自动打开浏览器，默认 true

### 7. stop_web_server

停止Web服务器

### 8. get_web_selection

获取Web选择结果

**参数:**
- `searchId` (string): 搜索ID

### 9. save_icons

保存选中的图标

**参数:**
- `searchId` (string): 搜索ID
- `iconIds` (array): 要保存的图标ID数组

### 10. check_selection_status

检查选择状态

**参数:**
- `searchId` (string): 搜索ID

## 响应格式

### 搜索图标响应

```json
{
  "code": 200,
  "data": {
    "icons": [
      {
        "id": 145442,
        "name": "用户",
        "status": 1,
        "is_private": 0,
        "category_id": "1",
        "slug": "用户",
        "unicode": "58931",
        "width": 1024,
        "height": 1024,
        "defs": null,
        "path_attributes": "fill=\"#FF9000\"",
        "fills": 1,
        "font_class": "yonghu",
        "user_id": 4689,
        "repositorie_id": 1029,
        "created_at": "2015-04-08T03:37:56.000Z",
        "updated_at": "2022-11-30T14:45:12.000Z",
        "preview_image": null,
        "svg_hash": "1c5e2a9ebaeb74599a727720e6439cb9",
        "svg_fill_hash": "3768e9af3b85014e5cabfe723186fcfe",
        "fork_from": null,
        "deleted_at": null,
        "show_svg": "<svg class=\"icon\" style=\"width: 1em;height: 1em;vertical-align: middle;fill: currentColor;overflow: hidden;\" viewBox=\"0 0 1024 1024\" version=\"1.1\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M703.400215 995.074204c-3.51915 0-7.078209-0.991584-10.240225-3.066849-30.28884-19.875676-80.136132-25.263383-97.079012-25.678846l-22.119787 0-35.287691 0.271176c-0.048095 0-0.095167 0-0.143263 0L92.740194 966.599685c-10.326183 0-18.696828-8.370645-18.696828-18.696828l0-22.467711c-0.318248-6.266727-0.910743-40.603767 21.004383-78.307484 13.716396-23.598464 33.431414-43.86095 58.598606-60.225663 30.493501-19.828604 69.116147-33.909297 114.796536-41.84913 0.233314-0.039909 0.466628-0.075725 0.700965-0.107447 0.346901-0.047072 35.499515-4.858658 71.208808-14.273075 61.894675-16.317641 67.307965-30.743188 67.345828-30.884404 0.364297-1.430582 0.89437-2.803859 1.572822-4.095271 0.50756-2.699482 1.76418-12.858866-0.63752-40.079834-6.100952-69.136613-42.120306-109.995183-71.061452-142.825916-9.127891-10.354835-17.749246-20.133549-24.387433-29.722952-28.640294-41.37227-31.296797-88.416725-31.396057-90.39887-0.01535-0.311085-0.022513-0.62217-0.022513-0.933255 0-18.779715 9.363252-27.418466 17.624403-35.041074l0.433882-0.401136c0.271176-0.25071 0.442068-0.436952 0.542352-0.556679 0.093121-1.340531-0.566912-4.743024-1.013073-7.04137-0.169869-0.873903-0.339738-1.750877-0.50142-2.632967-7.179516-38.981826-7.670703-99.19214-1.175779-137.837298 2.409886-50.813293 46.224788-89.711208 48.105624-91.356684 0.071631-0.062422 0.143263-0.12382 0.214894-0.185218 6.290263-5.338588 12.671601-11.169387 16.727986-17.636682 0.487094-0.775666 0.827855-1.37737 1.066285-1.836835-0.304945-0.786922-0.741897-1.793856-1.094938-2.608407-2.436492-5.618974-6.118348-14.109346-4.02364-25.02393 1.263783-6.589069 6.078439-18.362206 24.118304-23.173792 7.261381-1.937119 15.022135-2.333138 20.689205-2.62171l1.122567-0.058328c22.38994-1.178849 46.272883-2.176572 70.435189-0.324388 174.730557 13.396101 234.920404 78.686107 237.396805 81.459267 0.140193 0.155543 0.276293 0.314155 0.409322 0.474814 13.986549 16.756639 24.347524 37.635155 30.7964 62.055334 2.01489 7.619538 3.309372 14.016225 4.062526 20.072151 6.102998 35.464723 5.084808 71.904657 3.78214 96.269577-0.732687 13.675464-2.257413 28.030403-4.800329 45.175899-0.691755 4.656043 0.068562 5.564739 0.355087 5.906523 0.75827 0.906649 1.686409 1.892093 2.667759 2.934842 3.862981 4.099365 9.152451 9.713222 11.964496 18.721387 1.410116 4.502547 2.069125 9.360182 2.069125 15.267728 0 0.311085-0.008186 0.62217-0.022513 0.933255-0.099261 1.982144-2.755764 49.0266-31.395034 90.397846-6.639211 9.590426-15.259542 19.36914-24.387433 29.722952-28.942169 32.829709-64.960501 73.689303-71.061452 142.827963-2.4017 27.220968-1.14508 37.379329-0.63752 40.079834 0.678452 1.291412 1.208525 2.664689 1.572822 4.094248 0.036839 0.141216 5.471618 14.613836 67.648726 30.964222 35.7052 9.388834 70.557986 14.146185 70.90591 14.193257 0.303922 0.040932 0.606821 0.090051 0.908696 0.145309 46.095851 8.549723 84.956927 22.991644 115.505687 42.923602 25.252127 16.476253 44.930305 36.7019 58.489112 60.114123 21.50171 37.128619 20.626783 70.714552 20.195971 77.443813l0 22.332634c0 10.326183-8.370645 18.696828-18.696828 18.696828L775.884063 966.602755c-10.326183 0-18.696828-8.370645-18.696828-18.696828s8.370645-18.696828 18.696828-18.696828l158.188812 0L934.072875 924.897911c0-0.686638 0.00921-1.106194 0.081864-1.769296 0.104377-1.508353 1.627057-28.332279-16.349363-58.130955-10.82044-17.937534-26.589588-33.609469-46.870494-46.580898-26.100448-16.693194-59.762105-28.967752-100.05274-36.482913-4.63967-0.642636-39.012526-5.564739-75.080999-15.059997-70.761624-18.629289-87.964424-39.353286-93.189426-54.395888-4.004197-7.765871-6.245238-23.195282-2.984984-60.153008 7.18054-81.369216 49.41955-129.282458 80.260975-164.268274 8.747221-9.921977 16.301268-18.491143 21.693068-26.279526 21.120017-30.510898 24.437575-66.300009 24.765033-70.606081-0.032746-2.252297-0.260943-3.223415-0.36225-3.549849-0.248663-0.798179-1.89721-2.547009-3.490497-4.238534-1.25048-1.327228-2.667759-2.832512-4.136204-4.587482-7.950066-9.504468-10.782577-21.079084-8.66024-35.384905 2.367931-15.960507 3.781116-29.206182 4.449335-41.684378 1.951445-36.502355 0.913812-63.747883-3.363607-88.341001-0.057305-0.326435-0.105401-0.654916-0.145309-0.983397-0.531096-4.438079-1.530866-9.354042-3.14769-15.46932-4.986571-18.884093-12.726859-34.770921-23.006993-47.232744-1.714038-1.747807-15.385409-15.125489-45.883003-29.67588-54.882981-26.183336-120.791064-35.849486-166.417217-39.34817-21.934568-1.681292-44.442188-0.732687-65.614393 0.382717l-1.178849 0.060375c-1.766226 0.090051-4.735861 0.2415-7.55814 0.525979 2.447748 5.841032 5.453199 14.632255 2.296299 25.136493-1.184989 3.939729-3.003404 7.792477-5.723352 12.129248-6.732331 10.733459-15.923668 19.23611-24.054859 26.145473-1.597381 1.441838-34.223452 31.356149-35.351136 65.738213-0.028653 0.86981-0.11768 1.736551-0.267083 2.594081-5.972015 34.304294-5.568832 90.780563 0.898463 125.894292 0.140193 0.765433 0.288572 1.52575 0.435928 2.282996 1.980097 10.205433 5.294586 27.284413-10.879792 42.202171l-0.434905 0.402159c-2.086521 1.924839-4.943592 4.560876-5.41636 5.468548l0 0c0.00307 0-0.13303 0.426719-0.164752 1.584078 0.328481 4.295839 3.654226 40.060391 24.76401 70.554916 5.3918 7.788383 12.945847 16.356526 21.693068 26.279526 30.841426 34.984792 73.079412 82.899058 80.259952 164.266227 3.260254 36.95875 1.019213 52.388161-2.984984 60.154032-5.226025 15.042601-22.427802 35.766598-93.189426 54.395888-36.365232 9.574053-71.006194 14.497179-75.18947 15.074324-39.83424 6.958482-73.196069 18.883069-99.160417 35.44528-20.185738 12.876262-35.971259 28.599362-46.919613 46.732347-18.282389 30.281677-17.133216 57.860802-17.055444 59.33641 0.050142 0.543376 0.054235 0.867764 0.054235 1.433652l0 4.309142 427.01135 0 35.287691-0.271176c0.047072 0 0.095167 0 0.143263 0l22.423709 0c0.141216 0 0.280386 0.001023 0.421602 0.005117 2.895957 0.064468 71.446215 1.943258 116.949572 31.803333 8.633634 5.665023 11.039427 17.254989 5.374404 25.888624C715.458855 992.104569 709.488887 995.074204 703.400215 995.074204zM631.466905 689.8762c0.454348 0.36839 0.890276 0.757247 1.305739 1.164522C632.378671 690.653913 631.943766 690.26301 631.466905 689.8762zM414.041968 689.8762c-0.471744 0.382717-0.901533 0.768503-1.292436 1.152243C413.160901 690.626283 413.592736 690.24152 414.041968 689.8762z\" fill=\"#FF9000\" /></svg>"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "pageSize": 54,
    "total": 1
  },
  "searchParams": {
    "q": "用户",
    "sortType": "updated_at",
    "sType": "",
    "fromCollection": -1,
    "fills": ""
  }
}
```

## 缓存机制

服务器内置了缓存机制来提高性能：

- 缓存过期时间：30 分钟
- 支持搜索缓存和图标详情缓存
- 提供缓存统计和清理功能

## 日志记录

所有操作都会记录到日志文件中：

- 请求和响应记录
- 错误日志
- 服务器状态日志

## 快速开始

### 1. 安装包
```bash
npm install -g @liangshanli/mcp-server-icon
```

### 2. 配置 Cursor 编辑器
在项目根目录创建 `.cursor/mcp.json` 文件：

```json
{
  "mcpServers": {
    "icon": {
      "command": "npx",
      "args": ["@liangshanli/mcp-server-icon"],
      "env": {}
    }
  }
}
```

### 3. 重启 Cursor
重启 Cursor 编辑器以加载新的 MCP 服务器配置。

### 4. 开始使用
图标搜索工具将在 Cursor 的 MCP 界面中可用。

## 系统要求

- Node.js 18.0.0 或更高版本
- 无外部依赖（使用 Node.js 内置 fetch）

## 开发

### 项目结构
```
mcp-server-icon/
├── src/
│   ├── server-final.js        # 主服务器文件
│   ├── server-final-http.js   # HTTP服务器文件
│   ├── utils/                 # 工具类目录
│   │   ├── http-server.js     # HTTP服务器工具类
│   │   ├── web-interface.js   # Web界面处理器
│   │   ├── window-utils.js    # 窗口工具类
│   │   ├── search-icons.js    # 图标搜索工具
│   │   ├── cache-manager.js   # 缓存管理工具
│   │   ├── web-server-manager.js # Web服务器管理工具
│   │   ├── icon-saver.js      # 图标保存工具
│   │   └── selection-checker.js # 选择状态检查工具
│   └── lang/                  # 多语言支持
│       ├── index.js
│       ├── en.js
│       └── zh-CN.js
├── bin/
│   └── cli.js             # CLI 入口点
├── start.js               # 启动脚本
├── start-server.js        # 服务器启动脚本
├── package.json
└── README.md
```

### 测试
```bash
npm test
```

## 许可证

MIT License

## 更新日志

### v1.1.0 (2024-12-19)

#### 🚀 重大更新

**工具方法重构**
- 将MCP工具方法按功能拆分到独立的工具类中
- 提高了代码的模块化程度和可维护性
- 新增工具类：
  - `SearchIconsTool`: 图标搜索功能
  - `CacheManagerTool`: 缓存管理功能
  - `WebServerManagerTool`: Web服务器管理
  - `IconSaverTool`: 图标保存功能
  - `SelectionCheckerTool`: 选择状态检查

**多语言支持**
- 新增中文（zh-CN）和英文（en）界面支持
- 通过 `LANGUAGE` 环境变量控制界面语言
- 支持控制台输出和Web界面的多语言切换

**HTTP服务重构**
- 将HTTP相关功能拆分到独立工具类
- 新增 `HttpServer` 类管理HTTP服务器
- 新增 `WebInterface` 类处理Web界面
- 提供更好的浏览器控制和窗口管理

**新增功能**
- Web界面图标选择和保存功能
- 可视化图标浏览和选择
- 增强的缓存管理功能
- 改进的错误处理和日志记录

#### 🔧 技术改进

- 模块化架构设计，便于维护和扩展
- 独立的配置选项和依赖注入
- 更好的错误处理和调试支持
- 保持向后兼容性

#### 📝 使用说明

**多语言设置：**
```bash
# 设置为中文
LANGUAGE=zh-CN npx @liangshanli/mcp-server-icon

# 设置为英文（默认）
LANGUAGE=en npx @liangshanli/mcp-server-icon
```

**Web界面使用：**
1. 使用 `search_icons` 工具搜索图标
2. 使用 `start_web_server` 工具启动Web服务器
3. 在浏览器中浏览和选择图标
4. 使用 `save_icons` 工具保存选中的图标

## 作者

liliangshan