Mcp Icon Visual

mcp-icon-visual

一款 MCP 服务，让 AI Agent 能够搜索、获取、比较和渲染 SVG 图标。使用 Rust 和 rmcp SDK 构建。

它将本地文件系统访问与远程渲染 API 相结合，可从任意来源解析 SVG——内嵌字符串、URL、本地文件或 Iconify ID——并将其渲染到视觉对比网格中。

核心理念：每个工具都返回图像。具备视觉能力的大模型获得的不只是元数据——它还能看见图标。这让图标选择从凭猜测变成视觉对话。

search_icons("machine learning") — 4x4 网格，单元格编号为 0–15，以 PNG 格式返回

Agent 工作流

这些工具专为具备视觉能力的 AI Agent 组合使用而设计。下面介绍三种经过验证的模式。

1. 视觉搜索与选择

Agent 搜索图标并通过视觉挑选出最佳匹配——无需盲选 URL。

                          ┌─────────────────────────────┐
                          │        Agent + Vision        │
                          └──────────────┬──────────────┘
                                         │
                        ┌────────────────┼────────────────┐
                        v                v                v
                  search_icons     search_icons     search_icons
                  "cloud"          "upload"          "storage"
                        │                │                │
                        v                v                v
                  ┌──────────┐    ┌──────────┐    ┌──────────┐
                  │ 4x4 grid │    │ 4x4 grid │    │ 4x4 grid │
                  │  (sees)  │    │  (sees)  │    │  (sees)  │
                  └────┬─────┘    └────┬─────┘    └────┬─────┘
                       │               │               │
                       └───────────────┼───────────────┘
                                       v
                              "cells 3, 7, 12 match
                               the project style"
                                       │
                                       v
                               render_grid [3 winners]
                                       │
                                       v
                              ┌──────────────────┐
                              │  final comparison │
                              │   grid (sees)     │──> pick best
                              └──────────────────┘

Agent 执行多次搜索，逐一查看每个网格，按单元格编号挑选候选图标，然后渲染最终的并排对比图来做出选择。当 Agent 了解项目的视觉风格时，这种方式尤其有效。

2. 迭代编辑图标

Agent 修改 SVG 代码，并使用 render_grid 作为视觉差异对比，跟踪每次迭代的进展。

         get_svg "mdi/cloud"
                │
                v
          ┌───────────┐
          │ raw SVG    │
          │ markup     │
          └─────┬─────┘
                │
       ┌────────┴─────────────────────────────────────┐
       │              Edit Loop                        │
       │                                               │
       │   Agent modifies SVG code                     │
       │        │                                      │
       │        v                                      │
       │   render_grid [original, v1, v2, v3]          │
       │        │                                      │
       │        v                                      │
       │   ┌──────────────────────────────┐            │
       │   │ cell 0: original             │            │
       │   │ cell 1: thicker strokes      │            │
       │   │ cell 2: rounded corners      │            │
       │   │ cell 3: filled variant       │            │
       │   └──────────────┬───────────────┘            │
       │                  │                            │
       │        agent sees all versions                │
       │        decides next edit                      │
       │                  │                            │
       │                  └──── loop ──────────────────┘
       │
       v
  save final SVG to disk

每次迭代时，Agent 都会将所有版本（原始版本和编辑版本）作为内嵌 SVG 传递给 render_grid。它会在同一张图像中并排看到这些版本，并决定继续迭代还是停止。原始版本始终保留在单元格 0 中作为参考。

3. 风格匹配与一致性

Agent 确保新图标与项目现有图标的视觉风格一致。

  Project icons on disk             Candidate sources
  ─────────────────────             ─────────────────
  /app/icons/nav-home.svg           search_icons "settings"
  /app/icons/nav-search.svg              │
  /app/icons/nav-profile.svg             v
          │                        picks cells 2, 5, 9
          │                              │
          └──────────┬───────────────────┘
                     v
              render_grid [
                /app/icons/nav-home.svg,      ← cell 0: existing
                /app/icons/nav-search.svg,    ← cell 1: existing
                /app/icons/nav-profile.svg,   ← cell 2: existing
                candidate_url_1,              ← cell 3: candidate
                candidate_url_2,              ← cell 4: candidate
                candidate_url_3,              ← cell 5: candidate
                "<svg>...custom edit...</svg>" ← cell 6: agent's edit
              ]
                     │
                     v
              ┌────────────────────────────────┐
              │ grid image:                     │
              │  existing icons  vs  candidates │
              │  (agent sees style match/clash) │
              └────────────────┬───────────────┘
                               │
                      agent judges:
                  "cell 4 matches stroke weight
                   and corner radius of cells 0-2,
                   cell 3 is too thin,
                   cell 5 wrong fill style"
                               │
                               v
                       get_svg cell_4_url
                               │
                               v
                    save to /app/icons/nav-settings.svg

通过在同一个网格中混合本地文件路径和远程来源，Agent 可以一次性直观比较项目现有图标与候选图标。网格因此成为风格审查工具。

组合工作流

这些模式可以自然组合。一个真实场景中的工作流可能包括：

1. 搜索多个关键词（工作流 1）
2. 比较最佳候选图标与项目现有图标（工作流 3）
3. 编辑最接近的匹配项，修复风格不一致之处（工作流 2）
4. 验证最终图标，再次与完整图标集进行比较（工作流 3）

整个过程由一个具备视觉能力的 Agent 驱动，使用三种工具。

工具

search_icons

语义图标搜索。返回 4x4 PNG 网格（512x512，单元格编号为 0-15）以及单元格编号到 SVG URL 的映射。

参数	类型	默认值	描述
keyword	string	必填	语义搜索查询（例如 "cloud computing"、"arrows"）
background	string	"#FFFFFF"	网格背景颜色，CSS 十六进制值
color	string | null	null	将所有图标重新着色为此 CSS 十六进制颜色

get_svg

从任意来源获取原始 SVG 标记。返回完整的 SVG 字符串，供检查或修改。

参数	类型	描述
source	string	URL、Iconify ID（mdi/cloud）、绝对文件路径或内嵌的 <svg>

render_grid

将 1-16 个 SVG 渲染到 4x4 对比网格（512x512，单元格编号为 0-15）。适用于并排比较图标变体，或将本地图标与搜索结果一同预览。

参数	类型	默认值	描述
sources	string[]	必填	1-16 个 SVG 来源（URL、Iconify ID、文件路径或内联 SVG）
background	string	"#FFFFFF"	网格背景色，CSS 十六进制颜色

来源解析

所有工具共用统一的解析流程，可自动对来源进行分类：

来源类型	示例	解析方式
内联 SVG	<svg xmlns="...">...</svg>	原样返回
URL	https://mdn.alipayobjects.com/.../original	通过 API 解析
文件路径	/home/user/icons/logo.svg	从本地磁盘读取
Iconify ID	mdi/cloud、lucide/home	通过 API 解析

通过前缀（/、./、~/）或 .svg 扩展名检测文件路径。其他不包含 http:// 或 https:// 的内容均视为 Iconify ID。

网格格式

所有网格输出均为 512x512 PNG 图像，采用 4x4 布局（单元格大小为 128x128），编号按从左到右、从上到下的顺序为 0-15：

┌────┬────┬────┬────┐
│  0 │  1 │  2 │  3 │
├────┼────┼────┼────┤
│  4 │  5 │  6 │  7 │
├────┼────┼────┼────┤
│  8 │  9 │ 10 │ 11 │
├────┼────┼────┼────┤
│ 12 │ 13 │ 14 │ 15 │
└────┴────┴────┴────┘

单元格编号显示在各单元格的左下角。未使用的单元格只显示编号。

安装

npx（推荐）

无需构建。支持 Linux（x64/arm64）、macOS（Intel/Apple Silicon）和 Windows（x64）。

{
  "mcpServers": {
    "icon-visual": {
      "command": "npx",
      "args": ["-y", "@br-ai-n/mcp-icon-visual"]
    }
  }
}

从源代码安装

需要 Rust（edition 2024）：

cargo build --release --target x86_64-unknown-linux-musl

release 配置会生成完全静态的二进制文件（musl libc、rustls-tls、LTO、剥离符号）。

使用方法

# Default upstream API
./mcp-icon-visual

# Custom API endpoint
./mcp-icon-visual --api-base http://localhost:3000

该服务使用 MCP 协议通过 stdio 通信。

MCP 客户端配置

Claude Desktop / Cursor

{
  "mcpServers": {
    "icon-visual": {
      "command": "npx",
      "args": ["-y", "@br-ai-n/mcp-icon-visual"]
    }
  }
}

自定义 API 端点

{
  "mcpServers": {
    "icon-visual": {
      "command": "/path/to/mcp-icon-visual",
      "args": ["--api-base", "http://localhost:3000"]
    }
  }
}

项目结构

src/
├── main.rs           # Entrypoint, CLI args, stdio transport
├── server.rs         # IconServer + MCP tool routing + response builders
├── api_client.rs     # HTTP client for upstream rendering API
├── resolve.rs        # Source classification and SVG resolution
├── error.rs          # Error types
└── tools/
    ├── mod.rs
    ├── search_icons.rs   # SearchIconsParams
    ├── get_svg.rs        # GetSvgParams
    └── render_grid.rs    # RenderGridParams

测试

# Unit tests (source classification)
cargo test

# Integration tests (requires network access to icons.buan.me)
cargo test -- --ignored

依赖项

Crate	用途
rmcp	MCP 服务 SDK（工具路由、stdio 传输）
tokio	异步运行时
reqwest	HTTP 客户端（rustls-tls，不使用 OpenSSL）
serde / serde_json	序列化
schemars	为工具参数生成 JSON Schema
clap	CLI 参数解析
base64	Base64 编码
tracing	日志记录
thiserror	错误派生宏

许可证

MIT 许可证

版权所有 (c) 2025

特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人不受限制地使用本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和／或销售本软件副本的权利，并允许获得本软件的人这样做，但须满足以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或实质性部分中。

本软件按“原样”提供，不作任何明示或默示的保证，包括但不限于对适销性、特定用途适用性和不侵权的保证。在任何情况下，无论是因合同、侵权或其他原因而引起，作者或版权持有人均不对因本软件或本软件的使用或其他交易而产生、与之相关或由此引起的任何索赔、损害或其他责任负责。