Stocky

Stocky
美しいロイヤリティフリーのストック画像を見つけよう 📸

Stocky は、AI アシスタントが Pexels と Unsplash からロイヤリティフリーのストック写真を検索、閲覧、ダウンロードできるようにする MCP サーバーです。

🆕 バージョン 2.0 — すでに Stocky をお使いの方へ、こちらをお読みください

MCP クライアントの設定はそのまま動作します。 stocky_mcp.py を指定している場合、そのファイルはそのまま残っており、サーバーも引き続き起動します。アップグレードで壊れるものはありません。

ただし pip install -r requirements.txt は失敗します — そのファイルは削除され、setup.py も同様です。ソースチェックアウトからインストールする場合は、代わりに uv sync または pip install -e . を使用してください。2 分でわかる説明は1.x からのアップグレードを、詳細は CHANGELOG をご覧ください。

主な変更点: pycurl が不要になり（C のビルドエラーがなくなりました）、検索が実際に並行実行されるようになり、失敗したプロバイダーが何も返さずに終わるのではなく理由を報告するようになり、Python 3.10 以上が必要になりました。

✨ 機能

• 🔍 マルチプロバイダー検索 — Pexels と Unsplash に並行してクエリを実行します
• 📊 豊富なメタデータ — サイズ、撮影者、タグ、すべての画像サイズ
• ⚖️ ライセンス対応 — 各プロバイダーが要求するクレジット表示を生成し、Unsplash の API ガイドラインが求めるダウンロード報告を行います
• ⏱️ 検索キャッシュ — 短い TTL キャッシュにより、繰り返しのクエリがクォータを消費しません
• 🛡️ 正直なエラー — 失敗したプロバイダーは「結果なし」として黙って返されるのではなく、報告されます
• 🎯 フィルター — 向き、色、並び替えに対応し、プロバイダーごとに検証されます

美しいストック写真をすぐに デモンストレーション目的で使用されたサンプル画像

複数のプロバイダーから利用できる素晴らしい風景

Photo by Simon Berger on Unsplash

🚀 クイックスタート

1. API キーを取得する

どちらも無料です:

必要なのはどちらか一方だけです — Stocky は設定されたプロバイダーで動作します。

2. MCP クライアントに追加する

推奨の設定ではインストールはまったく不要です:

{
  "mcpServers": {
    "stocky": {
      "command": "uvx",
      "args": ["stocky-mcp"],
      "env": {
        "PEXELS_API_KEY": "your_pexels_key",
        "UNSPLASH_ACCESS_KEY": "your_unsplash_key"
      }
    }
  }
}

uv tool install stocky-mcp     # or: pipx install stocky-mcp

{
  "mcpServers": {
    "stocky": {
      "command": "stocky-mcp",
      "env": { "PEXELS_API_KEY": "your_pexels_key" }
    }
  }
}

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

Stocky は、クライアントが起動した環境から設定を読み込みます。独自の .env ファイルは読み込まないため、キーは上記の env ブロックに記述する必要があります。

⚙️ 設定

STOCKY_DOWNLOAD_ROOT は設定する価値があります。ダウンロードパスは モデルが生成したツール呼び出しに由来するため、これにより書き込みを 1 つの ディレクトリに制限できます。Stocky は常に画像以外のファイル拡張子を拒否し、 プロバイダーからの画像 URL を取得する前に公開 HTTP(S) アドレスであることを 検証しますが、ダウンロードルートが利用可能な中で最も強力な制御です。

📖 使用方法

Find the perfect image for your project

Stocky は 3 つの MCP ツールを公開します。これらを直接呼び出すのでは なく、自然言語で依頼するとクライアントが呼び出します。

夜明けの霧深い松林のストックフォトを検索してください。

Pexels から横位置の山の写真を 30 枚探してください。

pexels_123456 を中サイズで ~/Pictures/mountain.jpg にダウンロードしてください。

🛠️ ツール

search_stock_images

プロバイダーごとにグループ化された結果と、total_results、さらに いずれかのプロバイダーが失敗した場合はどれがなぜ失敗したかを説明する errors マップを返します。

無効な orientation や color は転送されるのではなく破棄されます。 Pexels は不正なフィルターを黙って無視して依然として 200 を返すため、 そうしなければ間違いが隠れてしまいますが、Unsplash はそれらを HTTP 400 で 明確に拒否します。

get_image_details

download_image

プロバイダーが要求されたサイズを提供していない場合は、失敗させるのでは なく、利用可能な最も近いサイズが使用されます。

リソース

stock-images://help — アシスタントが必要に応じて読むことができる使用ガイドです。

⚖️ ライセンスと帰属表示

画像は自由に使用できますが、両プロバイダーとも API アクセスの条件として帰属表示を要求しています。これは任意ではなく、このドキュメントの以前のバージョンで Pexels についてそうでないかのように示唆していたのは誤りでした。

Pexels は、API の結果を表示する場所にはどこでも Pexels への目立つリンクが必要であり、可能な場合は撮影者へのクレジット表示も求めています。

Unsplash は、撮影者と Unsplash の両方へのクレジット表示を、リンクに UTM パラメータを付けて行うこと、そして画像は再ホストするのではなく、API が返す URL からホットリンクすることを要求しています。

ENABLE_ATTRIBUTION_LINKS=true を設定すると、各結果に、そのプロバイダーに適した正しい形式の text と html をあらかじめ用意した attribution ブロックが追加されます。

download_image に関する注意。 Unsplash のバイト列をディスクに保存したり、base64 エンコードして返したりすることは、Unsplash のホットリンク要件と相反します。Stocky は Unsplash 画像をダウンロードするたびに必須のダウンロード報告エンドポイントを呼び出しますが、アプリケーションで画像を表示する場合は、ダウンロードするのではなく検索結果のホットリンク URL を使用してください。

完全な利用規約はこちら: Pexels · Unsplash

⬆️ 1.x からのアップグレード

バージョン 2.0 ではプロジェクトが再構成されました。既存の MCP クライアント設定はそのまま動作します — ルートの stocky_mcp.py はランチャーとして意図的に維持されています — が、インストール方法が変わり、いくつかの挙動も意図的に異なっています。

必要な作業

uvx またはインストール済みのコンソールスクリプト経由で実行している場合、何もする必要はありません。アップグレードしてそのまま続けてください。

ソースチェックアウトから実行している場合、再インストールしてください。requirements.txt、setup.py、setup.cfg は pyproject.toml に置き換えられました:

git pull
uv sync                     # or: pip install -e .

pip install -r requirements.txt は失敗するようになりました — そのファイルはもう存在しません。

Python のバージョンを確認してください。 2.0 は Python 3.10 以上を必要とします。古い setup.py は 3.8 対応を謳っていましたが、mcp SDK は常に 3.10 を必要としていたため、その主張は実際には決して満たせませんでした。

uvx への切り替えを検討してください。 何もインストールする必要がなく、「エディタがどのインタープリタを起動したのか?」という起動時の失敗を丸ごと回避できます:

{
  "mcpServers": {
    "stocky": {
      "command": "uvx",
      "args": ["stocky-mcp"],
      "env": { "PEXELS_API_KEY": "your_pexels_key" }
    }
  }
}

内部的に変わったこと

あなたのコードに影響する可能性がある唯一のこと

Stocky のレスポンスをプログラムで解析している場合に限ります。 失敗した検索は、以前は空の結果リストを返していましたが、今はプロバイダー名と理由を示す errors マップを返します:

{
  "query": "mountains",
  "results": { "pexels": [], "unsplash": [ /* ... */ ] },
  "errors": { "pexels": "pexels rejected the API key (HTTP 401)..." }
}

「空」を「一致なし」として扱っていた場合は、errors も確認してください — そうしないと、壊れたキーが結果なしのクエリのように見えてしまいます。これは修正であり、リグレッションではありませんが、目に見える変更です。

ツールの表面では他に何も変わっていません: search_stock_images、get_image_details、download_image はこれまでと同じ引数を受け取るため、既存のプロンプトやワークフローは影響を受けません。

🧑‍💻 開発

git clone https://github.com/joelio/stocky.git
cd stocky
uv sync --group dev

uv run pytest -m "not integration"   # unit tests, no network
uv run pytest -m integration         # needs real API keys
uv run ruff check . && uv run ruff format --check .
uv run mypy

詳細は CONTRIBUTING.md をご覧ください。

🐛 トラブルシューティング

クライアントが起動時にタイムアウトを報告する ほとんどの場合、Stocky のバグではなく起動の問題です。GUI から起動されたクライアントは 最小限の PATH しか持たないことが多く、uvx や virtualenv の python が見つからない 可能性があります。絶対パスを使用するか、uv をシステム全体にインストールしたうえで uvx を使用してください。ハンドシェイクはご自身で再現できます:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | stocky-mcp

JSON レスポンスが返れば、サーバーは正常です。stdout はプロトコルに使用されるため、 Stocky はすべてのログを stderr に出力します。そこに他のものが出力されるとストリームが 破損することに注意してください。

「No image providers are configured」 キーがサーバーに届いていません。キーはクライアント設定の env ブロックに記述する 必要があり、名前は大文字と小文字を区別します。

プロバイダーがエラーを返す レスポンスの errors を確認してください。認証の失敗、レート制限、タイムアウトは、 空の結果セットのように見えるのではなく、明示的に報告されるようになりました。

Pexels が無効なキーを受け入れるように見える 実際に受け入れます。Pexels は不正な形式のキーに対しても 200 を返すため、タイプミスが 正常に動作しているように見えることがあります。結果がおかしいと思われる場合は、 キーを直接検証してください。

レート制限

🤝 コントリビューション

コントリビューションを歓迎します — CONTRIBUTING.md をご覧ください。 大きな変更の場合は、まず issue を開いて方針について議論してください。

🙏 謝辞

• 無料 API を提供してくださっている Pexels と Unsplash に感謝します
• Model Context Protocol を使用して構築されています