FreeVectorIcons

@freevectoricons/mcp

**Beta 版。**此软件包正在积极开发中。在 v1.0.0 发布前，工具架构、配置选项和错误行为都可能发生变化。请报告问题，或在用于生产环境前查看产品文档。

适用于 FreeVectorIcons 设计集合的模型上下文协议（MCP）服务。

将 Cursor、Claude Desktop 和其他 MCP 客户端连接到单个 FreeVectorIcons 集合（通过令牌派生绑定——仅需配置 FVI_TOKEN）：浏览图标目录、已上传的 SVG、策略简介、DESIGN.md 和相关项目文件。访问范围限定为单个集合令牌。

npm：@freevectoricons/mcp

概览

直接生成图标的 Agent 往往会产出不一致的 SVG、不稳定的标识符，并在不同会话中错误处理许可信息。FreeVectorIcons 将经过批准的资源存储在带版本管理的集合中，并为其提供稳定 ID 和元数据。

此服务会将该集合提供给 MCP 客户端。Agent 可以搜索并获取规范资源，而不是从头重新生成 SVG，还可以将设计写回集合以供审核。已上传的资源带有版本记录，因此 Agent 可以自由迭代，而不会丢失先前的工作。此服务通过标准输入/输出运行，并调用 FreeVectorIcons HTTP API。响应采用元数据优先的 JSON 格式；只有在工具请求内联内容或下载 URL 时，才会获取文件字节。

**托管连接器。**如果你的客户端支持远程 MCP 服务，可以跳过此软件包，改为连接 https://mcp.freevectoricons.com/mcp：无需安装，并可从客户端登录，或通过 Authorization: Bearer 标头发送集合令牌。请参阅 freevectoricons.com/mcp。如果 Agent 需要直接从磁盘上传文件，或你的设置更倾向于本地进程，则适合使用此软件包。

要求

• Node.js 20 或更高版本
• FreeVectorIcons 账户
• 作用域限定于集合的 MCP 令牌

设置

1. 在 freevectoricons.com 打开一个集合。
2. 前往 集成 → 设置 MCP。
3. 创建一个作用域限定于集合的令牌，并复制密钥。集合 ID 会根据令牌派生（无需单独的集合 ID 环境变量）。

将此服务添加到 MCP 客户端配置中（例如 .cursor/mcp.json）：

{
  "mcpServers": {
    "freevectoricons": {
      "command": "npx",
      "args": ["-y", "@freevectoricons/mcp"],
      "env": {
        "FVI_TOKEN": "<collection-token>"
      }
    }
  }
}

按上方所示使用 npx 运行此服务。MCP 使用标准输入/输出传递协议消息；进程不得向标准输出写入非协议内容。

请参阅 mcp.json.example 获取可直接复制粘贴的模板。

Claude Desktop

将相同的 mcpServers 块添加到 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

Cursor Marketplace（插件）

此代码库也是一个 Cursor 插件（.cursor-plugin/plugin.json + mcp.json）。

1. 上架后从 Cursor Marketplace 安装，或将此代码库复制到 ~/.cursor/plugins/local/freevectoricons 以进行本地测试（复制文件；避免损坏的符号链接）。
2. 打开 插件 → 配置，然后设置 集合令牌（FVI_TOKEN），其值来自 FreeVectorIcons → 集成 → 设置 MCP。
3. 可选：FVI_API_URL（默认为生产环境），FVI_READ_ONLY=true 用于隐藏写入工具。

提交／重新索引：cursor.com/marketplace/publish。

Google Antigravity 和 Gemini CLI

Gemini CLI 已于 2026 年 11 月 5 日通过针对托管端点的兼容性测试。Antigravity 在 0.3.0-beta.3 工具重命名后仍在测试中；通过测试前，请将其视为预览版，并报告问题。

Antigravity 插件。 此仓库同时也是 Antigravity 插件（.antigravity-plugin/plugin.json、mcp_config.json 和 skills/ 文件夹）。安装后，在 /plugin（CLI）或 Settings → Customizations（应用）中启用，并在提示时粘贴你的集合令牌。

Antigravity 配置块。 也可以将以下内容添加到 ~/.gemini/config/mcp_config.json（适用于所有项目）或 .agents/mcp_config.json（适用于一个工作区）：

{
  "mcpServers": {
    "freevectoricons": {
      "command": "npx",
      "args": ["-y", "@freevectoricons/mcp"],
      "env": {
        "FVI_TOKEN": "<collection-token>"
      }
    }
  }
}

Gemini CLI 扩展。 从此仓库安装，并在提示时输入你的集合令牌：

gemini extensions install https://github.com/FreeVectorIcons/fvi-mcp

稍后可使用 gemini extensions config freevectoricons 更改令牌。该扩展固定使用已发布的软件包版本，因此运行 gemini extensions update freevectoricons 时即可获取新版本。

环境变量

变量	必需	默认值	描述
FVI_TOKEN	是	—	集合范围的 MCP 令牌（fvi_col_*）。集合绑定通过 GET /api/mcp/whoami 获取。
FVI_COLLECTION_ID	否	—	已弃用／仅用于覆盖。 如果设置的值与令牌所属集合不一致，适配器将安全关闭（COLLECTION_MISMATCH）。建议省略此项。
FVI_API_URL	否	https://freevectoricons.com/api	API 基础 URL（包含 /api）
FVI_READ_ONLY	否	false	为 true 时，不会注册写入工具。只能缩小令牌权限范围
FVI_TOOLS	否	—	要注册的工具名称，以逗号分隔。接受 0.3.0-beta.3 之前的旧名称。只能缩小访问范围
FVI_SKIP_TOKEN_CHECK	否	false	如果未来的令牌格式在本地被拒绝，可使用此应急开关
FVI_ALLOW_FILE_PATHS	否	false	允许上传工具使用 filePath。默认关闭
FVI_FILE_PATH_ROOTS	否	—	filePath 可读取的目录，以逗号分隔
FVI_TIMEOUT_MS	否	30000	API 调用的 HTTP 请求超时时间（毫秒）
FVI_UPLOAD_TIMEOUT_MS	否	120000	二进制上传请求的超时时间（毫秒）
FVI_RETRY_MAX	否	3	瞬时故障的最大重试次数
FVI_RETRY_BASE_MS	否	500	指数退避的基础延迟（毫秒）
FVI_LOG_LEVEL	否	info	日志级别：debug、info、warn 或 error（stderr，JSON）

仅在指向非生产环境的 API 时设置 FVI_API_URL。

默认启用写入工具。Agent 可以暂存新资源，并上传现有资源的新版本；每项更改都会保存为一个版本，你可以在集合界面中查看或恢复。仅当你希望获取资源而不上传时，才设置 FVI_READ_ONLY=true。

令牌安全

请像对待密码一样保护 FVI_TOKEN。它授予对一个集合的访问权限。

• 在团队环境中，优先使用操作系统密钥链集成或机密管理器。
• 如果在配置文件中使用环境变量，请限制文件权限，切勿将令牌提交到版本控制系统。
• 如果令牌可能已泄露，请在集合的 Integrations 选项卡中轮换令牌。
• 如果 Agent 只应读取集合内容而不上传，请设置 FVI_READ_ONLY=true。

切换集合（令牌重新绑定）

仅重启 MCP 服务，不会重新绑定仍在使用旧 FVI_TOKEN 的共享 stdio 连接器。

1. 在 Setup MCP 中为目标集合创建令牌。
2. 使用新的 FVI_TOKEN 重新添加／配置连接器环境变量（如果无法配置，则先卸载再添加）。
3. 测试 get_collection_context，并确认 collection.id / name。
4. 如果需要同时连接两个集合，请使用第二个命名服务条目。

工具

仅当 API 启用了相应功能时，才会列出记录类工具（get_asset_spreadsheet_preview、set_collection_strategy_brief、promote_asset_to_strategy_brief、set_asset_transcription_status、delete_collection_asset、probe_asset_text_layer）。当 FVI_READ_ONLY=true 或令牌缺少写入权限范围时，写入工具也会隐藏。

读取

工具	描述
get_collection_context	集合元数据、策略简报、资源摘要
list_collection_assets	所有资源（仅元数据）
search_collection_assets	按名称、标签、类别或风格搜索
get_asset	按 ID 获取单个资源
get_asset_content	获取目录 SVG、上传的 SVG、Markdown 的内嵌 UTF-8 内容
get_asset_download_url	获取 PNG、PDF、电子表格（XLS/XLSX）及其他二进制文件的短时有效 URL
get_asset_download_urls	每次调用获取最多 50 个资源的相同 URL
get_asset_spreadsheet_preview	获取 XLS/XLSX 的首个工作表预览（CSV/HTML，大小受限）
list_asset_versions	版本号、名称、大小、已验证的哈希值和来源
list_community_packs	公共社区图标包及其许可信息和 agentGuide URL
get_community_pack_guide	图标包的 AGENTS.md：许可、署名、URL 模式和精选使用指南

写入

工具	描述
create_asset_upload	创建资源记录和已签名的上传目标
park_asset	将内嵌文本或 base64 上传到集合
create_asset_version	上传现有资源的新版本（保留之前的版本）
set_collection_strategy_brief	替换 collection.metadata.strategyBrief（原生策略简报选项卡）
promote_asset_to_strategy_brief	将 Markdown 资源文本复制到原生简报中（不会删除资源）
set_asset_transcription_status	修改 textLayer / transcription 元数据（不执行 OCR）
update_asset	仅更新元数据的 PATCH：名称、标签、documentType、DRL 字段、自定义元数据和链接
set_collection_design_md	从内嵌 Markdown 或现有资源中固定规范的 DESIGN.md
update_collection_purpose	将集合用途设为 brand 或 records
create_asset_version_upload	为现有资源的新版本生成已签名的上传目标
complete_asset_upload	验证校验和与大小，然后将该版本设为当前版本
refresh_asset_upload	为 URL 已过期（15 分钟）的待处理上传签发新的上传 URL
revert_asset_to_version	将较早的版本复制为新版本。保留历史记录
delete_collection_asset	仅软取消关联集合条目 — 不会硬删除字节数据。需要 delete 权限范围
probe_asset_text_layer	尽力探测 PDF 嵌入文本（由 API 功能标志控制）

上传的资源会在 FreeVectorIcons 中保留版本历史记录。优化现有设计时，Agent 应优先使用 create_asset_version；上传新文件时则使用 park_asset。对于图像、PDF 和电子表格（.xls / .xlsx），Agent 应使用元数据和下载 URL — 工作簿字节数据不会输出到 MCP 工具结果中。使用 get_asset_spreadsheet_preview 查看受限的首个工作表预览。对于扫描版 PDF，在上传 Markdown 配套文件后设置转录状态。

已上传的 STRATEGY_BRIEF.md 仅作为辅助文档 — 在调用 promote_asset_to_strategy_brief 或 set_collection_strategy_brief 之前，它不会填充原生策略简报选项卡。

可选写入元数据：drlProjectId、drlAssetType、documentType、tags。

重命名的工具（0.3.0-beta.3）

工具名称移除了多余的 design_，以适配会在工具名称前添加服务端名称的客户端（Antigravity 的前缀长达 33 个字符，而 Gemini 允许的总长度为 64 个字符）。参数、作用域和行为均未改变。结果也未改变，唯一例外是 set_collection_strategy_brief 的试运行现在会报告 would.operation: "set_collection_strategy_brief"。

在此软件包和托管端点上，调用旧名称仍然有效，但旧名称不再列出。请将已保存的提示词、工具允许列表（FVI_TOOLS 接受新旧名称）和缓存的审批更新为新名称，然后重新连接或重启客户端，以便重新加载工具列表。旧名称将在后续版本中移除，届时会先在此处公告。

旧名称	新名称
complete_design_asset_upload	complete_asset_upload
create_design_asset_upload	create_asset_upload
create_design_asset_version	create_asset_version
create_design_asset_version_upload	create_asset_version_upload
delete_design_collection_asset	delete_collection_asset
get_design_asset	get_asset
get_design_asset_content	get_asset_content
get_design_asset_download_url	get_asset_download_url
get_design_asset_download_urls	get_asset_download_urls
get_design_asset_spreadsheet_preview	get_asset_spreadsheet_preview
get_design_collection_context	get_collection_context
list_design_asset_versions	list_asset_versions
list_design_collection_assets	list_collection_assets
park_design_asset	park_asset
probe_design_asset_text_layer	probe_asset_text_layer
promote_design_asset_to_strategy_brief	promote_asset_to_strategy_brief
refresh_design_asset_upload	refresh_asset_upload
revert_design_asset_to_version	revert_asset_to_version
search_design_collection_assets	search_collection_assets
update_design_asset	update_asset
update_design_asset_transcription_status	set_asset_transcription_status
update_design_collection_purpose	update_collection_purpose
update_design_collection_strategy_brief	set_collection_strategy_brief

set_asset_transcription_status 仍然只记录状态元数据，不会运行 OCR。

限制

• 限定集合范围。 一个令牌只能访问一个集合，无法访问全局图标目录。
• 目录质量。 目录中的 SVG 由 AI 生成并按计划优化；投入生产使用前请先验证资源。
• 不进行设计评审。 服务端会移动文件和元数据，但不会评估品牌契合度。
• OCR 尽力而为。 只有在 API 上启用后，probe_asset_text_layer 才会检测 PDF 中嵌入的文本；手写或扫描页面通常没有可用的文本层。检测失败时会将 transcription.status 设为 failed，但不会删除资源。
• 软解除关联，而非彻底删除。 delete_collection_asset 只会移除集合成员关系——存储的字节会保留，直到未来实施彻底删除策略。

开发

此软件包的构建、测试和发布流程见 CONTRIBUTING.md。

相关内容

• @freevectoricons/mcp 软件包架构 — 解决方案设计架构（stdio 传输、工具映射、安全边界）
• 确保 @freevectoricons/mcp 不受漏洞影响 — 已发布的软件包不含依赖项、审计关卡、Dependabot
• freevectoricons.com/mcp — 产品文档
• ai-icon-generator — 用于目录图标的开源流程

许可证

MIT——仅适用于此 MCP 服务软件。请参阅 LICENSE。

图标的使用受 FreeVectorIcons 社区许可证 单独约束。根据您的套餐和图标的使用方式，可能需要注明出处。