视觉资源获取与定制化图标生成服务 (MCP 接入)

此工具集成了对多个主流图库API的查询功能，并加入了基于文本描述的AI图标合成能力，旨在为Cursor集成环境（MCP）提供强大的视觉内容供应。

核心运作机制

本服务通过MCP协议，为Cursor IDE环境提供以下图像相关操作：

1. 资产检索：接入Unsplash、Pexels、Pixabay等数据源，执行基于关键字的高效图像查找。
2. 本地化存储：支持将检索到的媒体文件安全地下载并保存至用户指定的本地路径。
3. 合成图标：利用描述性输入，驱动AI模型（如Together AI）生成项目所需的定制化标识或UI元素。

交互流程概述

用户指令 (于Cursor IDE内) → LLM推理/规划 → LLM触发MCP调用 → 工具执行操作 → 结果回传 → LLM展示最终输出

例如，用户可请求：“请为我检索五张与宇宙探索主题相关的图像。”LLM将调度此MCP工具执行搜索，并在反馈中呈现结果，用户后续可请求下载或进一步定制图标。

主要功能特性

• 多源图像数据库支持 (Unsplash, Pexels, Pixabay)
• 高质量、文本驱动的AI图标合成能力 (依赖Together AI)
• 简洁的工具调用API接口
• 稳健的异常处理机制
• 灵活的文件保存路径与命名控制
• 可配置的输出图像维度

环境配置先决条件

1. Python 环境要求

• Python 版本要求：3.10 或更高版本。
• 官方下载： https://www.python.org/downloads/
• 版本管理推荐：使用 pyenv。

bash

macOS 上的 pyenv 安装

brew install pyenv

安装特定版本 Python

pyenv install 3.13.2 pyenv global 3.13.2

2. Python 包管理：uv

推荐使用 uv 以加速依赖安装：

bash

macOS 安装 uv

brew install uv

或使用 pip 传统安装

pip install uv

3. 外部服务 API 凭证

请依序获取并配置以下服务的访问密钥：

Unsplash 访问令牌

1. 访问 Unsplash Developers
2. 完成注册/登录。
3. 创建新的应用并获取 Access Key。

Pexels 认证码

1. 访问 Pexels API 门户
2. 注册并申请获取 API 密钥。

Pixabay 开发者密钥

1. 访问 Pixabay API 文档
2. 注册并获取您的 API 密钥。

Together AI 秘钥

1. 访问 Together AI 密钥管理
2. 注册并生成新的 API 密钥用于生成任务。

4. IDE 环境

• 安装 Cursor IDE
• 确保 Cursor 已配置并能正确解析您的 Python 环境。

部署与初始化

1. 克隆仓库：

bash git clone https://github.com/yanjunz/mcp_search_images.git

1. 安装运行依赖：

bash python3 -m pip install fastmcp requests

若在安装过程中遇到 SSL 证书验证问题，可尝试使用信任主机选项：

bash python3 -m pip install fastmcp requests --trusted-host pypi.org --trusted-host files.pythonhosted.org --upgrade --force-reinstall --no-cache-dir

1. 配置敏感信息：

从模板文件创建生产配置文件：

bash

复制模板文件

cp config.json.template config.json

编辑配置文件，填入您的密钥

nano config.json # 或使用您偏好的编辑器

在 config.json 中更新 api 部分的密钥字段，例如：

{ "api": { "unsplash_access_key": "您的Unsplash密钥", "pexels_api_key": "您的Pexels密钥", "pixabay_api_key": "您的Pixabay密钥", "together_api_key": "您的Together密钥", "timeout": 30, "max_retries": 3, "retry_delay": 5 }, // ...其他配置... }

安全警示：务必确保 config.json 文件未被纳入版本控制（.gitignore 已配置）。

服务启动指南

模式一：直接 Python 脚本执行

最直接的启动方式：

bash python3.11 main.py

服务启动成功日志示例：

启动图片搜索服务 - 端口: 5173 注册工具: search_images, download_image, generate_icon INFO: Uvicorn running on http://0.0.0.0:5173 (Press CTRL+C to quit)

模式二：利用 fastmcp 命令行接口

若已安装 fastmcp 包，可使用以下命令：

1. 开发/调试模式（通常包含热重载）：

bash fastmcp dev main.py

1. 生产部署模式：

bash fastmcp run main.py

1. 端口冲突处理（指定非默认端口，如5174）：

bash PORT=5174 fastmcp dev main.py

模式三：使用 uv 环境管理启动

若您使用 uv 作为环境管理器：

bash

生产模式启动

uv run --with fastmcp fastmcp run main.py

或者在开发模式下：

bash uv run --with fastmcp fastmcp dev main.py

MCP 服务与 Cursor 间通信原理

为排除连接障碍，理解以下通信机制至关重要：

1. 服务初始化：执行脚本后，服务设置 SSE (Server-Sent Events) 应用，监听指定端口（默认5173），并向 MCP 框架注册其工具集。

2. Cursor 连接建立：当在 Cursor 中配置此 MCP 工具时，IDE会尝试与配置的URL握手。服务需对初始化请求做出合规的MCP响应，尤其是工具列表的汇报。成功后，Cursor方会将工具标记为可用。

3. 连接故障排查步骤：

   • 确认服务进程是否存活：lsof -i :5173。
   • 基础网络连通性测试：curl http://localhost:5173。
   • 验证MCP协议实现：检查启动日志中工具注册信息。
   • 检查本地防火墙规则是否阻断了端口5173的访问。

4. 端到端验证流程： bash # 1. 终止旧服务实例 pkill -f "python.*main.py"

   2. 在前台启动新服务，以便观察实时日志

   python3.11 main.py

   3. 在另一终端测试基础HTTP响应

   curl http://localhost:5173

   4. 测试ServerLink专用的SSE端点

   curl http://localhost:5173/sse

   5. 在Cursor中尝试添加并激活工具

如果连接仍失败，请核查Python版本兼容性或尝试重新安装核心依赖包，有时依赖缓存问题会导致错误：

bash python3.11 -m pip uninstall fastmcp mcp uvicorn starlette -y python3.11 -m pip install fastmcp mcp uvicorn starlette

使用操作指南

在 Cursor IDE 中集成与调用

1. 确认服务运行：确保服务通过 python3.11 main.py 正在后台或前台运行。

2. Cursor 配置步骤：

   • 进入 Cursor 设置 (左下角齿轮图标)。
   • 导航至 "AI & Copilot" 设置区域。
   • 在 "MCP Tools" 部分，选择 "Add MCP Tool"。
   • 填写信息：
     • 名称: 视觉资源工具
     • 类型: SSE (Server-Sent Events)
     • URL: http://localhost:5173
     • 保存。
   • 备用 ServerLink 配置 (若标准SSE不工作)：
     • 类型: sse
     • ServerLink: http://localhost:5173/sse

关键提示：若遇到 Fail to create client 错误，请执行连接诊断（如上文所述）并确保服务日志有活动记录。

1. 工具激活与使用：

   • 一旦配置成功，LLM应能自动识别该工具。
   • 若需明确调用，可提示LLM：“请利用视觉资源工具查找所需图像。”

2. 即时素材获取：

   • 在代码编写过程中，直接描述对素材的需求，例如：“请为我生成一个符合暗色主题的‘设置’图标。”

3. 资源检查：

   • 默认下载资源存放于项目根目录下的 icons/ 目录。
   • 验证已保存文件： bash ls -la icons

功能调用示例

图像检索

用户可以直接向LLM提供检索指令：

查找主题为"cyber security"的图片集。

或者更精细的请求：

在Pexels上搜索3张关于"quantum computing"的专业照片。

文件下载

在LLM展示搜索结果列表后，可要求下载：

请将列表中的第一张图片保存为 main_banner.jpg。

或指定路径和文件名：

把第三个结果存储到 ~/Assets/downloads/api_preview.webp

定制图标合成

通过详尽描述需求来驱动AI生成：

合成一个极简风格的云存储图标，使用渐变蓝和白，尺寸设定为128x128，命名为cloud_storage.svg

实际集成场景参考

请参阅 示例对话文档 以获取在实际开发工作流中与Claude/LLM协作的交互范例。

工作流优化建议

1. 查询优化：使用高信息密度的关键词以提升检索精准度。
2. 源头选择：根据素材性质（如艺术性 vs. 商业性）选择最佳图库。
3. 命名规范：采用一致的命名约定，如 [领域]-[资产名]-[尺寸].ext。
4. 批量操作：优先请求一组相关的资产，而非逐个请求。
5. 上下文关联：在请求中提供代码或设计上下文，帮助LLM更好地理解视觉需求。

故障诊断要点

Cursor MCP 连接失败诊断

若在Cursor中配置服务时出现客户端创建失败，请依序排查：

1. 服务运行验证：确认端口5173是否被监听（参见 lsof 命令）。
2. 网络连通性测试：使用 curl -v http://localhost:5173 检查响应状态码和详细信息。
3. 配置调整：
   • 确认连接类型为 SSE。
   • 尝试使用循环回环地址 http://127.0.0.1:5173。
   • 对比标准URL (http://localhost:5173) 与 ServerLink 路径 (http://localhost:5173/sse)。
4. 重启策略：依次重启 MCP 服务进程，再重启 Cursor IDE（以清除旧的连接缓存）。
5. 日志审查：观察服务端的日志是否有来自 Cursor 的连接尝试记录。
6. 端口转移：若端口被占用，修改源码中的端口号（如设为5174）并重启服务。

常见辅助检查项

若遇到其他操作问题，请复核以下基础设置：

• 服务进程是否活跃。
• 文件写入路径是否存在且具有写权限。
• 所有必需的API凭证是否配置正确且有效。
• Python运行环境的依赖（fastmcp, requests 等）是否完整安装。

参与贡献

欢迎通过提交 Issue 或 Pull Request 的方式，对本项目的改进做出贡献。

许可证

本项目遵循 MIT License 协议。