free-image-library 0.1.0__tar.gz

free_image_library-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Surendran B
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

free_image_library-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: free-image-library
+Version: 0.1.0
+Summary: Free images for AI agents: search millions of openly-licensed, royalty-free Creative Commons images and audio (Flickr, Wikimedia, museums) — every result with ready-to-paste attribution. Zero API keys.
+Author-email: Surendran B <reachsuren@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://free-image-library.builditwithai.xyz
+Project-URL: Repository, https://github.com/surendranb/free-image-library
+Project-URL: Issues, https://github.com/surendranb/free-image-library/issues
+Keywords: free-images,free-image-library,royalty-free-images,creative-commons-images,stock-images,openverse,image-search,mcp,mcp-server,model-context-protocol,ai-agent,claude,llm,agentic-workflows
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2.0.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Dynamic: license-file
+
+# Free Image Library — Free CC Images & Audio MCP 🖼️
+
+[![CI](https://github.com/surendranb/free-image-library/actions/workflows/package-checks.yml/badge.svg)](https://github.com/surendranb/free-image-library/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/free-image-library.svg)](https://pypi.org/project/free-image-library/)
+
+> **Free images for any project: millions of openly-licensed, royalty-free Creative Commons images and audio (Flickr, Wikimedia, museums) — every result with ready-to-paste attribution. Zero API keys, zero configuration.**
+
+The visual sibling of the [Free Music Library](https://github.com/surendranb/music-mcp)
+for the same content-creator audience: the agent finds the image AND the credit
+line in one call, so the attribution never gets lost between copy and paste.
+
+## Why this exists
+
+- Models suggest random stock images (license unknown, credit never written).
+  This returns license-safe images with the credit the user MUST paste — built
+  into the same result.
+- **License intelligence, not just labels**: every row carries a `credit_note`
+  stating the actual obligation — CC BY-NC rows are loudly flagged
+  non-commercial-only before your client ships them into a paid campaign.
+- **Serendipity**: `image_roulette` picks from deep in the result set, not the
+  first hit everyone has seen.
+- Built on [Openverse](https://api.openverse.org) — keyless (anonymous limits:
+  20 requests/min, 200/day, verified; a free registered key raises them via
+  `OPENVERSE_API_KEY`). A 5-minute TTL cache makes repeat searches free.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `find_images` | Free CC image search with filters (license, aspect_ratio, size, extension) + attribution on every row |
+| `image_roulette` | One random license-safe pick, honest about how it was chosen |
+| `find_audio` | Free CC music / sound effects / field recordings from Openverse's audio index |
+| `skills_list` / `skill_read` | Updatable playbooks: CC license briefs in plain language, error recovery |
+
+Plus prompts: `hero-image`, `license-safe-images`.
+
+## Quickstart
+
+```bash
+# 1-Line Universal Installer (auto-configures Claude Desktop, Cursor, Claude Code, VS Code, ...)
+curl -fsSL "https://free-image-library.builditwithai.xyz/install" | bash
+
+# Or run directly via your preferred runtime:
+uvx free-image-library
+npx -y free-image-library
+```
+
+## Example
+
+```
+User:  I need a hero image for my climate blog post
+
+find_images(query="melting glacier", aspect_ratio="wide", count=3,
+            intent="hero image for a climate blog post")
+→ images: [{
+     title: "Glacier calving", creator: "…", license: "CC BY 2.0",
+     image_url: "https://…", width: 2048, height: 1152,
+     attribution: "\"Glacier calving\" image by … (flickr), licensed CC BY 2.0 (…)",
+     credit_note: "Credit REQUIRED — paste the attribution verbatim." }]
+```
+
+## Telemetry & privacy
+
+Anonymous usage telemetry (no PII, no queries, no paths) via the fleet
+standard (schema v2, dual-endpoint fallback). Opt out any time:
+`FREE_IMAGE_LIBRARY_TELEMETRY=false` or `DO_NOT_TRACK=1`.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+DO_NOT_TRACK=1 .venv/bin/python -m pytest tests/ -q   # unit + live + e2e
+```
+
+Live tests hit the real Openverse API; they skip themselves when offline or
+rate-limited.
+
+## License
+
+MIT

free_image_library-0.1.0/README.md

@@ -0,0 +1,81 @@
+# Free Image Library — Free CC Images & Audio MCP 🖼️
+
+[![CI](https://github.com/surendranb/free-image-library/actions/workflows/package-checks.yml/badge.svg)](https://github.com/surendranb/free-image-library/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/free-image-library.svg)](https://pypi.org/project/free-image-library/)
+
+> **Free images for any project: millions of openly-licensed, royalty-free Creative Commons images and audio (Flickr, Wikimedia, museums) — every result with ready-to-paste attribution. Zero API keys, zero configuration.**
+
+The visual sibling of the [Free Music Library](https://github.com/surendranb/music-mcp)
+for the same content-creator audience: the agent finds the image AND the credit
+line in one call, so the attribution never gets lost between copy and paste.
+
+## Why this exists
+
+- Models suggest random stock images (license unknown, credit never written).
+  This returns license-safe images with the credit the user MUST paste — built
+  into the same result.
+- **License intelligence, not just labels**: every row carries a `credit_note`
+  stating the actual obligation — CC BY-NC rows are loudly flagged
+  non-commercial-only before your client ships them into a paid campaign.
+- **Serendipity**: `image_roulette` picks from deep in the result set, not the
+  first hit everyone has seen.
+- Built on [Openverse](https://api.openverse.org) — keyless (anonymous limits:
+  20 requests/min, 200/day, verified; a free registered key raises them via
+  `OPENVERSE_API_KEY`). A 5-minute TTL cache makes repeat searches free.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `find_images` | Free CC image search with filters (license, aspect_ratio, size, extension) + attribution on every row |
+| `image_roulette` | One random license-safe pick, honest about how it was chosen |
+| `find_audio` | Free CC music / sound effects / field recordings from Openverse's audio index |
+| `skills_list` / `skill_read` | Updatable playbooks: CC license briefs in plain language, error recovery |
+
+Plus prompts: `hero-image`, `license-safe-images`.
+
+## Quickstart
+
+```bash
+# 1-Line Universal Installer (auto-configures Claude Desktop, Cursor, Claude Code, VS Code, ...)
+curl -fsSL "https://free-image-library.builditwithai.xyz/install" | bash
+
+# Or run directly via your preferred runtime:
+uvx free-image-library
+npx -y free-image-library
+```
+
+## Example
+
+```
+User:  I need a hero image for my climate blog post
+
+find_images(query="melting glacier", aspect_ratio="wide", count=3,
+            intent="hero image for a climate blog post")
+→ images: [{
+     title: "Glacier calving", creator: "…", license: "CC BY 2.0",
+     image_url: "https://…", width: 2048, height: 1152,
+     attribution: "\"Glacier calving\" image by … (flickr), licensed CC BY 2.0 (…)",
+     credit_note: "Credit REQUIRED — paste the attribution verbatim." }]
+```
+
+## Telemetry & privacy
+
+Anonymous usage telemetry (no PII, no queries, no paths) via the fleet
+standard (schema v2, dual-endpoint fallback). Opt out any time:
+`FREE_IMAGE_LIBRARY_TELEMETRY=false` or `DO_NOT_TRACK=1`.
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+DO_NOT_TRACK=1 .venv/bin/python -m pytest tests/ -q   # unit + live + e2e
+```
+
+Live tests hit the real Openverse API; they skip themselves when offline or
+rate-limited.
+
+## License
+
+MIT

free_image_library-0.1.0/free_image_library/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: MIT
+
+__version__ = "0.1.0"

free_image_library-0.1.0/free_image_library/__main__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MIT
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

free_image_library-0.1.0/free_image_library/credits.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MIT
+
+"""Attribution builders — the instant-credit pattern from music-mcp.
+
+Every result row can be turned into ready-to-paste credit lines in three
+formats. CC BY / BY-SA require credit; CC0/PDM don't (but crediting is good
+practice and we say so rather than silently dropping it).
+"""
+
+_LICENSE_NAMES = {
+    "CC0": "CC0 1.0 (public domain)",
+    "PDM": "Public Domain Mark",
+    "BY": "CC BY",
+    "BY-SA": "CC BY-SA",
+    "BY-NC": "CC BY-NC",
+    "BY-NC-SA": "CC BY-NC-SA",
+    "BY-ND": "CC BY-ND",
+    "BY-NC-ND": "CC BY-NC-ND",
+}
+
+
+def _license_label(row):
+    lic = (row.get("license") or "").upper()
+    version = row.get("license_version")
+    name = _LICENSE_NAMES.get(lic, lic or "unknown license")
+    return f"{name} {version}".strip() if version else name
+
+
+def _creator(row):
+    creator = (row.get("creator") or "").strip()
+    if not creator:
+        return None, None
+    source = row.get("source") or "the source"
+    url = row.get("foreign_landing_url")
+    return creator, f'by <a href="{url}">{creator}</a> ({source})' if url \
+        else f"by {creator} ({source})"
+
+
+def credit_lines(row, media_noun="image"):
+    """(plaintext, markdown, html) attribution for one result row."""
+    title = row.get("title") or "(untitled)"
+    creator, creator_html = _creator(row)
+    creator_plain = creator or "unknown creator"
+    source = row.get("source") or "the source"
+    license_label = _license_label(row)
+    license_url = row.get("license_url")
+    landing = row.get("foreign_landing_url") or row.get("image_url") \
+        or row.get("audio_url") or ""
+
+    lic_plain = f"{license_label} ({license_url})" if license_url else license_label
+    lic_md = f"[{license_label}]({license_url})" if license_url else license_label
+    lic_html = (f'<a href="{license_url}">{license_label}</a>'
+                if license_url else license_label)
+
+    title_md = f"[{title}]({landing})" if landing else title
+    title_html = f'<a href="{landing}">{title}</a>' if landing else title
+
+    plain = (f'"{title}" {media_noun} by {creator_plain} ({source}), '
+             f"licensed {lic_plain}")
+    if creator:
+        markdown = (f'*"{title}"* {media_noun} '
+                    f"{creator_md(creator, landing, source)} — {lic_md}")
+    else:
+        markdown = f'*"{title}"* {media_noun} from {source} — {lic_md}'
+    html = (f"{title_html} {media_noun} {creator_html} — {lic_html}")
+
+    return plain, markdown, html
+
+
+def creator_md(creator, landing, source):
+    if not creator:
+        return f"from {source}"
+    return f"by [{creator}]({landing}) ({source})" if landing else \
+        f"by {creator} ({source})"
+
+
+def credit_note(row):
+    """One-line obligation note: what credit this license actually requires."""
+    lic = (row.get("license") or "").upper()
+    if lic in ("CC0", "PDM"):
+        return ("No credit required — but including one is good practice "
+                "and helps the creator.")
+    if lic in ("BY-NC", "BY-NC-SA", "BY-NC-ND"):
+        return ("Credit REQUIRED and commercial use NOT allowed — verify the "
+                "use is non-commercial before shipping.")
+    if lic:
+        return "Credit REQUIRED — paste the attribution verbatim."
+    return "License unknown — do not use without checking the source page."

free_image_library-0.1.0/free_image_library/openverse.py

@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: MIT
+
+"""Openverse API client — CC-licensed images and audio for AI agents.
+
+Openverse (WordPress) is keyless: anonymous use is rate-limited to 20/min
+burst and 200/day sustained (verified 2026-08-22), which is plenty for a
+discovery tool with the TTL cache below. A registered key can be supplied
+later via OPENVERSE_API_KEY for higher limits.
+"""
+
+import os
+import time
+import threading
+
+import requests
+
+BASE = "https://api.openverse.org/v1"
+USER_AGENT = "free-image-library/0.1.0 (MCP server; +https://github.com/surendranb/free-image-library)"
+TIMEOUT = 10.0
+CACHE_TTL = 300  # 5 min: identical searches within a session cost nothing
+
+LICENSES = ("all", "cc", "cc0", "pdm", "by", "by-sa", "by-nc", "by-nc-sa",
+            "by-nd", "by-nc-nd")
+ASPECTS = ("wide", "square", "tall")
+SIZES = ("small", "medium", "large")
+
+
+class OpenverseError(Exception):
+    """Upstream failure with a model-facing tag."""
+
+    def __init__(self, message, rate_limited=False):
+        super().__init__(message)
+        self.rate_limited = rate_limited
+
+
+_cache_lock = threading.Lock()
+_cache = {}
+
+
+def _cached(key):
+    now = time.time()
+    with _cache_lock:
+        hit = _cache.get(key)
+        if hit and hit[0] > now:
+            return hit[1]
+    return None
+
+
+def _store(key, value):
+    with _cache_lock:
+        if len(_cache) > 128:  # bounded: discovery tool, not a mirror
+            _cache.clear()
+        _cache[key] = (time.time() + CACHE_TTL, value)
+
+
+def _headers():
+    headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+    key = os.getenv("OPENVERSE_API_KEY")  # optional: higher rate limits
+    if key:
+        headers["Authorization"] = f"Bearer {key}"
+    return headers
+
+
+def _get(path, params):
+    cache_key = f"{path}?{sorted((params or {}).items())}"
+    hit = _cached(cache_key)
+    if hit is not None:
+        return hit
+    try:
+        resp = requests.get(f"{BASE}{path}", params=params or {},
+                            headers=_headers(), timeout=TIMEOUT)
+    except requests.Timeout as e:
+        raise OpenverseError("Openverse request timed out "
+                             "[TRANSIENT: retry once]") from e
+    except requests.RequestException as e:
+        raise OpenverseError(f"Openverse request failed: {e} "
+                             "[TRANSIENT: retry once]") from e
+    if resp.status_code == 429:
+        raise OpenverseError(
+            "Openverse anonymous rate limit hit (20/min, 200/day). Wait a "
+            "minute before the next call; set OPENVERSE_API_KEY for higher "
+            "limits [ENVIRONMENT_FIXABLE: wait or register a key at "
+            "api.openverse.org]", rate_limited=True)
+    if resp.status_code == 401:
+        raise OpenverseError("Openverse rejected OPENVERSE_API_KEY "
+                             "[ENVIRONMENT_FIXABLE: unset it to use anonymous "
+                             "access, or fix the key]")
+    if resp.status_code >= 400:
+        raise OpenverseError(f"Openverse returned HTTP {resp.status_code} "
+                             "[INPUT_FIXABLE: check the arguments, e.g. an "
+                             "unknown license or aspect value]")
+    try:
+        data = resp.json()
+    except ValueError as e:
+        raise OpenverseError("Openverse returned a non-JSON body "
+                             "[TRANSIENT]") from e
+    _store(cache_key, data)
+    return data
+
+
+def _validate(license, aspect_ratio, size, extension):
+    if license not in LICENSES:
+        raise ValueError(f"Unknown license {license!r}. Candidates: "
+                         f"{', '.join(LICENSES)}. [INPUT_FIXABLE]")
+    if aspect_ratio is not None and aspect_ratio not in ASPECTS:
+        raise ValueError(f"Unknown aspect_ratio {aspect_ratio!r}. Candidates: "
+                         f"{', '.join(ASPECTS)}. [INPUT_FIXABLE]")
+    if size is not None and size not in SIZES:
+        raise ValueError(f"Unknown size {size!r}. Candidates: "
+                         f"{', '.join(SIZES)}. [INPUT_FIXABLE]")
+    if extension is not None and extension not in ("jpg", "png", "gif", "svg"):
+        raise ValueError(f"Unknown extension {extension!r}. Candidates: "
+                         "jpg, png, gif, svg. [INPUT_FIXABLE]")
+
+
+def _params(query, license, aspect_ratio, size, extension, page, page_size):
+    params = {"q": query, "page_size": page_size, "page": page,
+              "mature": "false"}
+    if license == "cc":
+        params["license_type"] = "all-cc"
+    elif license not in ("all", None):
+        params["license"] = license
+    if aspect_ratio:
+        params["aspect_ratio"] = aspect_ratio
+    if size:
+        params["size"] = size
+    if extension:
+        params["extension"] = extension
+    return params
+
+
+def _thumb(url):
+    """Openverse thumbnails are proxied and reliably hotlinkable."""
+    if not url:
+        return None
+    return f"https://api.openverse.org/v1/images/{url}" if not str(url).startswith("http") else url
+
+
+def _image_row(result):
+    return {
+        "id": result.get("id"),
+        "title": result.get("title") or "(untitled)",
+        "creator": result.get("creator"),
+        "license": (result.get("license") or "").upper() or None,
+        "license_version": result.get("license_version"),
+        "license_url": result.get("license_url"),
+        "source": result.get("source"),
+        "image_url": result.get("url"),
+        "thumbnail": result.get("thumbnail"),
+        "foreign_landing_url": result.get("foreign_landing_url"),
+        "width": result.get("width"),
+        "height": result.get("height"),
+        "tags": [t.get("name") for t in (result.get("tags") or [])
+                 if t.get("name")][:8],
+    }
+
+
+def _audio_row(result):
+    return {
+        "id": result.get("id"),
+        "title": result.get("title") or "(untitled)",
+        "creator": result.get("creator"),
+        "license": (result.get("license") or "").upper() or None,
+        "license_version": result.get("license_version"),
+        "license_url": result.get("license_url"),
+        "source": result.get("source"),
+        "audio_url": (result.get("url")
+                      or ((result.get("audio_files") or [{}])[0].get("url"))),
+        "duration_s": result.get("duration"),
+        "foreign_landing_url": result.get("foreign_landing_url"),
+    }
+
+
+def search_images(query, license="cc", aspect_ratio=None, size=None,
+                  extension=None, page=1, page_size=10):
+    """CC image search. Returns (rows, result_count)."""
+    _validate(license, aspect_ratio, size, extension)
+    data = _get("/images/", _params(query, license, aspect_ratio, size,
+                                    extension, page, page_size))
+    return ([_image_row(r) for r in data.get("results", [])],
+            data.get("result_count", 0))
+
+
+def get_image(image_id):
+    """One image record by id (for attribution formatting)."""
+    data = _get(f"/images/{image_id}/", {})
+    return _image_row(data)
+
+
+def search_audio(query, license="cc", page=1, page_size=8):
+    """CC audio search (music, sound effects, field recordings)."""
+    if license not in LICENSES:
+        raise ValueError(f"Unknown license {license!r}. Candidates: "
+                         f"{', '.join(LICENSES)}. [INPUT_FIXABLE]")
+    params = {"q": query, "page_size": page_size, "page": page, "mature": "false"}
+    if license == "cc":
+        params["license_type"] = "all-cc"
+    elif license not in ("all", None):
+        params["license"] = license
+    data = _get("/audio/", params)
+    return ([_audio_row(r) for r in data.get("results", [])],
+            data.get("result_count", 0))