Stocky 是一个基于 Model Context Protocol（MCP）的服务器，用于让 AI 助手搜索、查看和下载来自 Pexels 与 Unsplash 的免版税图库照片。它通过自然语言调用，无需手动操作 API。
用途：Stocky 面向需要为项目寻找高质量免版税图片的 AI 助手场景。用户可以用自然语言描述需求，例如“搜索黎明时分雾气缭绕的松树林照片”或“从 Pexels 找 30 张横向的山脉照片”，AI 客户端会调用 Stocky 提供的工具完成搜索和下载。
主要能力：
- 多提供商并发搜索：同时查询 Pexels 和 Unsplash，结果按提供商分组返回，并包含 total_results；若某个提供商失败，会返回 errors 映射说明原因。
- 丰富元数据：每张图片包含尺寸、摄影师、标签以及所有可用尺寸。
- 许可与署名：根据各提供商要求生成署名信息。Pexels 要求在展示 API 结果时提供指向 Pexels 的显著链接，并尽可能标注摄影师；Unsplash 要求同时标注摄影师和 Unsplash，链接需带 UTM 参数，且图片应使用 API 返回的 URL 热链而非重新托管。设置 ENABLE_ATTRIBUTION_LINKS=true 后，每个结果会附带符合格式的 attribution 块（文本和 HTML）。
- 搜索缓存：短 TTL 缓存避免重复查询消耗配额。
- 诚实错误：失败的提供商会明确报告，而不是静默返回“无结果”。
- 筛选：支持方向、颜色和排序，并按提供商进行验证。无效的方向或颜色会被丢弃而非转发，因为 Pexels 会静默忽略错误筛选并返回 200，而 Unsplash 会直接返回 HTTP 400。
使用方式：
- 获取 API 密钥：只需配置一个提供商即可运行。
- 添加到 MCP 客户端：推荐配置无需安装，也可通过 pip 或 uv 安装，或从源码检出运行。Stocky 从客户端启动它的环境中读取配置，不加载自己的 .env 文件，因此密钥必须放在客户端配置的 env 块中。
- 配置：建议设置 STOCKY_DOWNLOAD_ROOT，将下载路径限制在一个目录内。Stocky 始终拒绝非图片扩展名，并在获取前验证提供商返回的图片 URL 是公开的 HTTP(S) 地址。
Stocky 暴露三个 MCP 工具，由客户端在用户自然语言请求时调用：
- search_stock_images：返回按提供商分组的结果，以及 total_results 和 errors（如有失败）。
- get_image_details：获取图片详细信息；若提供商不提供请求的尺寸，则使用最接近的可用尺寸。
- download_image：下载图片；下载 Unsplash 图片时会触发强制的下载报告端点。 此外还提供 stock-images://help 资源，供助手按需阅读使用指南。
适用场景：适合需要为设计、内容创作、演示等任务快速获取免版税图片的 AI 助手工作流。
限制与注意事项：
- 需要至少一个提供商的 API 密钥，密钥必须通过客户端配置的 env 块传入，名称区分大小写。
- 版本 2.0 要求 Python 3.10+，不再使用 pycurl，安装方式改为 uv sync 或 pip install -e .，requirements.txt 和 setup.py 已移除。
- 下载 Unsplash 图片到磁盘或返回 base64 与 Unsplash 的热链要求存在冲突；若在应用中展示图片，应使用搜索结果中的热链 URL 而非下载。
- Pexels 对格式错误的密钥也会返回 200，因此密钥拼写错误可能看似正常，需直接验证密钥。
- 启动超时通常是由于 GUI 客户端 PATH 最小化导致找不到 uvx 或虚拟环境 python，可使用绝对路径或系统级安装的 uvx。
- 所有日志输出到 stderr，stdout 用于协议通信。
