STARWARCLOUD STARWAR.AI
返回市场
健壮

健壮

作者：joelio15 星标更新：2025-10-14
安装使用来源：spider==github.com

项目介绍

<div align="center">Stocky Logo<br/>Stocky<br/>查找美丽的免版税库存图片 📸</div>

<div align="center">

Python 3.8+ MCP 兼容 MIT 许可证

</div>

✨ 特性

  • 🔍 多提供商搜索 - 同时在 Pexels 和 Unsplash 上进行搜索
  • 📊 丰富的元数据 - 获取全面的图片详情，包括尺寸、摄影师信息和许可信息
  • 📄 分页支持 - 轻松浏览大量结果集
  • 🛡️ 优雅的错误处理 - 对 API 失败进行强大的错误处理
  • ⚡ 异步性能 - 雷霆般的并发 API 调用速度
  • 🎯 提供商灵活性 - 搜索特定提供商或同时搜索所有提供商

摄影示例

指尖上的美丽库存摄影
用于演示目的的示例图片

山脉景观 通过多个提供商获得的惊人的景观

照片由 Simon Berger 在 Unsplash 提供

🚀 快速开始

安装

  1. 克隆仓库：
git clone https://github.com/yourusername/stocky-mcp.git
cd stocky-m
  1. 安装依赖项：
pip install -r requirements.txt

API 密钥设置

你需要从每个提供商获取免费的 API 密钥：

  1. Pexels 📷 - 在 pexels.com/api 获取你的密钥
  2. Unsplash 🌅 - 在 unsplash.com/developers 注册

API 密钥配置

在设置 MCP 服务器时需要配置你的 API 密钥。这些密钥用于与库存图片提供商的身份验证。

作为 MCP 服务器运行

Stocky 设计为作为 MCP（模型上下文协议）服务器运行，而不是独立应用程序。它应该在你的 MCP 客户端配置中进行配置。

🔧 MCP 客户端配置

将 Stocky 添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "stocky": {
      "command": "python",
      "args": ["/path/to/stocky_mcp.py"],
      "env": {
        "PEXELS_API_KEY": "your_pexels_key",
        "UNSPLASH_ACCESS_KEY": "your_unsplash_key",
      }
    }
  }
}

📖 使用示例

<div align="center"> <img src="images/photography-example2.jpg" alt="库存摄影示例" width="600"> <p><em>找到适合你项目的完美图片</em></p> </div>

搜索图片

跨所有提供商搜索：

results = await search_stock_images("日落海滩")

搜索特定提供商：

results = await search_stock_images(
    query="山地风景",
    providers=["pexels", "unsplash"],
    per_page=30,
    page=1
)

获取图片详情

details = await get_image_details("unsplash_abc123xyz")

下载图片

# 下载并保存到磁盘
result = await download_image(
    image_id="pexels_123456", 
    size="medium", 
    output_path="/path/to/save.jpg"
)

# 获取 base64 编码的图片数据
result = await download_image(
    image_id="unsplash_abc123", 
    size="original"
)

🛠️ 工具文档

search_stock_images

在多个提供商之间搜索免版税库存图片。

参数：

  • query (str, 必需) - 查找图片的搜索词
  • providers (list, 可选) - 要搜索的提供商列表：["pexels", "unsplash"]
  • per_page (int, 可选) - 每页结果数，最大 50（默认：20）
  • page (int, 可选) - 分页的页码（默认：1）
  • sort_by (str, 可选) - 按“相关性”或“最新”排序结果

返回值： 包含元数据的图片结果列表

get_image_details

获取特定图片的详细信息。

参数：

  • image_id (str, 必需) - 图片 ID 格式为 provider_id（例如，pexels_123456）

返回值： 包含完整元数据的详细图片信息

download_image

下载图片到本地存储或获取 base64 编码的数据。

参数：

  • image_id (str, 必需) - 图片 ID 格式为 provider_id（例如，pexels_123456）
  • size (str, 可选) - 要下载的图片大小变体（默认："original"）
    • 选项：thumbnail, small, medium, large, original
  • output_path (str, 可选) - 保存图片到本地的路径
    • 如果未提供，则返回 base64 编码的图片数据

返回值： 包含下载信息或错误的字典

📄 许可证信息

<div align="center"> <img src="images/photography-example3.jpg" alt="许可证信息" width="600"> <p><em>为你的创意项目提供的免版税图片</em></p> </div>

Stocky 返回的所有图片均可免费使用：

  • Pexels ✅ - 商业和个人用途均免费，无需归因
  • Unsplash ✅ - 在 Unsplash 许可下免费

在生产中使用前，请始终检查每张图片的具体许可证。

🤝 贡献

欢迎贡献！请随时提交拉取请求。对于重大更改，请先打开一个议题来讨论你想改变的内容。

  1. 分叉项目
  2. 创建你的功能分支 (git checkout -b feature/AmazingFeature)
  3. 提交你的更改 (git commit -m '添加一些AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 打开一个拉取请求

🙏 致谢

🐛 故障排除

常见问题

"未找到 API 密钥" 错误

  • 确保你的 .env 文件存在且包含有效的 API 密钥
  • 检查环境变量是否正确加载
  • 验证 API 密钥名称完全匹配（区分大小写）

没有返回结果

  • 尝试不同的搜索词
  • 检查你的互联网连接
  • 验证 API 密钥处于活动状态且未超过速率限制

安装问题

  • 确保已安装 Python 3.8+
  • 尝试创建虚拟环境：python -m venv venv
  • 更新 pip：pip install --upgrade pip

速率限制

每个提供商有不同的速率限制：

  • Pexels：每小时 200 次请求
  • Unsplash：每小时 50 次请求（演示），每小时 5000 次请求（生产）
<div align="center"> 由 Stocky 团队制作 💜 </div>