al-iconfont-helper-mcp

一个用于检索和查询阿里巴巴图标库（iconfont）的 MCP (Model Context Protocol) 服务器。

功能特性

• list-icons: 检索 iconfont.json 中所有可用的图标列表
• check-icon: 检查指定名称的图标是否存在（支持 name 和 font_class 双字段匹配，支持模糊搜索）

安装与使用

方式一：通过 npx 直接使用（推荐）

无需安装，直接使用：

npx -y al-iconfont-helper-mcp

方式二：全局安装

npm install -g al-iconfont-helper-mcp
iconfont-helper-mcp

方式三：本地开发

# 克隆或下载项目
git clone <repo-url>
cd iconfont-helper

# 安装依赖
npm install

# 构建
npm run build

配置

方式一：环境变量配置（推荐）

设置 ICONFONT_JSON_PATH 环境变量指向你的 iconfont.json 文件：

# Windows
set ICONFONT_JSON_PATH=C:\path\to\your\iconfont.json

# Linux/macOS
export ICONFONT_JSON_PATH=/path/to/your/iconfont.json

方式二：动态传入路径

每次调用工具时通过 filePath 参数指定路径。

MCP 客户端配置

Claude Desktop

编辑 Claude Desktop 配置文件：

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

添加以下配置：

{
  "mcpServers": {
    "iconfont-helper": {
      "command": "npx",
      "args": ["-y", "al-iconfont-helper-mcp"],
      "env": {
        "ICONFONT_JSON_PATH": "/path/to/your/iconfont.json"
      }
    }
  }
}

Claude Code CLI

claude mcp add iconfont-helper -- npx -y al-iconfont-helper-mcp

其他 MCP 客户端

{
  "mcpServers": {
    "iconfont-helper": {
      "command": "npx",
      "args": ["-y", "al-iconfont-helper-mcp"]
    }
  }
}

工具说明

list-icons

检索所有可用的图标列表。

参数:

• filePath (可选): iconfont.json 文件路径，覆盖默认路径

返回示例:

{
  "success": true,
  "data": {
    "projectInfo": {
      "id": "5136097",
      "name": "ai-test",
      "fontFamily": "iconfont",
      "cssPrefixText": "icon-"
    },
    "totalIcons": 29,
    "icons": [
      {
        "name": "搜索",
        "fontClass": "sousuo",
        "unicode": "e622"
      }
    ]
  }
}

check-icon

检查指定名称的图标是否存在。

参数:

• name (必需): 要查找的图标名称
• filePath (可选): iconfont.json 文件路径
• fuzzy (可选): 是否启用模糊搜索，默认 false

返回示例:

{
  "success": true,
  "data": {
    "found": true,
    "matches": [
      {
        "name": "搜索",
        "fontClass": "sousuo",
        "unicode": "e622",
        "matchedField": "name"
      }
    ]
  }
}

错误处理

| 错误代码 | 说明 | |---------|------| | FILE_NOT_FOUND | 图标库配置文件不存在 | | INVALID_JSON | 图标库配置文件格式错误 | | INVALID_FORMAT | 图标库配置文件缺少必要字段 | | PATH_NOT_CONFIGURED | 未配置图标库文件路径 |

开发

# 运行测试
npm test

# 运行测试（监听模式）
npm run test:watch

# 运行测试（覆盖率）
npm run test:coverage

# 开发模式
npm run dev

使用示例

示例 1：列出所有图标

AI: 请列出项目中可用的图标

AI 会调用 list-icons 工具返回所有图标列表。

示例 2：检查图标是否存在

AI: 项目中有"搜索"图标吗？

AI 会调用 check-icon 工具，传入 name="搜索"。

示例 3：查找相似图标

AI: 找一下包含"icon"的图标

AI 会调用 check-icon 工具，启用模糊搜索（fuzzy=true）。

技术栈

• Node.js
• TypeScript
• @modelcontextprotocol/sdk
• Zod (参数验证)
• Vitest (测试框架)

License

MIT