pexels-mcp 1.0.0__tar.gz

pexels_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aqiu
+
+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.

pexels_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: pexels-mcp
+Version: 1.0.0
+Summary: MCP + CLI toolkit to search and download free Pexels stock images/videos. No API key, no quota. Built-in relevance gate kills Pexels's junk hits; picks the right resolution tier for vertical shorts.
+Project-URL: Homepage, https://modelscope.cn/mcp/servers
+Author: aqiu
+License: MIT
+License-File: LICENSE
+Keywords: images,mcp,model-context-protocol,pexels,shorts,stock,video-assembly,videos
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pexels-mcp
+
+MCP + CLI toolkit to **search and download free Pexels stock images/videos**.
+
+- **Zero third-party dependencies** — pure Python standard library (urllib). Install, run, done.
+- **No API key, no quota** — talks to Pexels' own web front-end API v3 (the public `secret-key` constant Pexels hardcodes in its JS).
+- **Built-in relevance gate** — Pexels returns *something* for any query (even `zzzqqqxxx_not_exist_9999`). This tool validates every candidate against title/tags and drops 0-hit junk, so you never get unrelated footage.
+- **Right resolution tier, automatically** — picks the video_files tier closest to your target (default 1080×1920 portrait) and refuses to upscale postage-stamp clips.
+- **Chinese query rejected** — the English site can't search Chinese meaningfully. Translate to concrete English words (`office meeting` > `work`).
+
+Works as an [MCP](https://modelcontextprotocol.io) server (5 tools) or a plain CLI.
+
+---
+
+## Quick start
+
+```bash
+pip install pexels-mcp          # or: uvx pexels-mcp@latest
+```
+
+### As an MCP server
+
+```json
+{
+  "mcpServers": {
+    "pexels": {
+      "command": "uvx",
+      "args": ["pexels-mcp@latest"],
+      "env": { "PEXELS_OUT_DIR": "/tmp/pexels_download" }
+    }
+  }
+}
+```
+
+Any MCP client (Claude Desktop, CowAgent, …) sees 5 tools:
+
+| tool            | what it does |
+|-----------------|--------------|
+| `pexels_search` | search only, returns direct links + size/duration metadata; no junk hits |
+| `pexels_get`    | search **and download** N items to a local dir, returns paths + byte counts |
+| `pexels_download` | download a single direct link you already have |
+| `pexels_health` | channel self-check; includes a reverse probe (a nonsense query must return 0 hits) |
+| `pexels_info`   | capability boundary, no network |
+
+`PEXELS_OUT_DIR` sets the download folder (default: OS temp dir).
+
+### As a CLI
+
+```bash
+pexels-cli search "elderly woman face" --kind video --n 5
+pexels-cli search "office meeting" --json
+pexels-cli get "hands holding cash" -o ./out --n 2
+pexels-cli health
+pexels-cli info
+```
+
+All subcommands support `--json` for machine-readable output.
+
+---
+
+## Why it's reliable
+
+- **No fake hits**: Pexels fabricates total_results even for nonsense queries. We split your query into content tokens (with a stop-word list — `not` must not match `do not lean`), and require ≥1 token to actually appear in the item's title/tags/slug. A test with `zzzqqqxxx_not_exist_9999` returns 0 hits.
+- **No decompression trap**: we request `Accept-Encoding: identity` (avoid brotli unless you have it) and fall back to gunzip.
+- **Throttle-safe**: measured 100 sequential + 8-way parallel direct downloads at 100% success with no Cloudflare intervention.
+- **Bomb fuse**: downloads stream with size cap, and a `text/html` response is rejected as a Cloudflare block page masquerading as HTTP 200.
+
+## Notes
+
+- This package is just "give me a keyword → get good direct-link stock media". It does **not** assemble videos — pair it with an assembler MCP (e.g. `video-assembler-mcp`) for the full pipeline.
+- The endpoint is Pexels' own public web API and could change at any time. It's a third-party behavior, out of our control; `pexels_health` exists precisely to catch that the day it happens.
+
+## License
+
+MIT

pexels_mcp-1.0.0/README.md

@@ -0,0 +1,75 @@
+# pexels-mcp
+
+MCP + CLI toolkit to **search and download free Pexels stock images/videos**.
+
+- **Zero third-party dependencies** — pure Python standard library (urllib). Install, run, done.
+- **No API key, no quota** — talks to Pexels' own web front-end API v3 (the public `secret-key` constant Pexels hardcodes in its JS).
+- **Built-in relevance gate** — Pexels returns *something* for any query (even `zzzqqqxxx_not_exist_9999`). This tool validates every candidate against title/tags and drops 0-hit junk, so you never get unrelated footage.
+- **Right resolution tier, automatically** — picks the video_files tier closest to your target (default 1080×1920 portrait) and refuses to upscale postage-stamp clips.
+- **Chinese query rejected** — the English site can't search Chinese meaningfully. Translate to concrete English words (`office meeting` > `work`).
+
+Works as an [MCP](https://modelcontextprotocol.io) server (5 tools) or a plain CLI.
+
+---
+
+## Quick start
+
+```bash
+pip install pexels-mcp          # or: uvx pexels-mcp@latest
+```
+
+### As an MCP server
+
+```json
+{
+  "mcpServers": {
+    "pexels": {
+      "command": "uvx",
+      "args": ["pexels-mcp@latest"],
+      "env": { "PEXELS_OUT_DIR": "/tmp/pexels_download" }
+    }
+  }
+}
+```
+
+Any MCP client (Claude Desktop, CowAgent, …) sees 5 tools:
+
+| tool            | what it does |
+|-----------------|--------------|
+| `pexels_search` | search only, returns direct links + size/duration metadata; no junk hits |
+| `pexels_get`    | search **and download** N items to a local dir, returns paths + byte counts |
+| `pexels_download` | download a single direct link you already have |
+| `pexels_health` | channel self-check; includes a reverse probe (a nonsense query must return 0 hits) |
+| `pexels_info`   | capability boundary, no network |
+
+`PEXELS_OUT_DIR` sets the download folder (default: OS temp dir).
+
+### As a CLI
+
+```bash
+pexels-cli search "elderly woman face" --kind video --n 5
+pexels-cli search "office meeting" --json
+pexels-cli get "hands holding cash" -o ./out --n 2
+pexels-cli health
+pexels-cli info
+```
+
+All subcommands support `--json` for machine-readable output.
+
+---
+
+## Why it's reliable
+
+- **No fake hits**: Pexels fabricates total_results even for nonsense queries. We split your query into content tokens (with a stop-word list — `not` must not match `do not lean`), and require ≥1 token to actually appear in the item's title/tags/slug. A test with `zzzqqqxxx_not_exist_9999` returns 0 hits.
+- **No decompression trap**: we request `Accept-Encoding: identity` (avoid brotli unless you have it) and fall back to gunzip.
+- **Throttle-safe**: measured 100 sequential + 8-way parallel direct downloads at 100% success with no Cloudflare intervention.
+- **Bomb fuse**: downloads stream with size cap, and a `text/html` response is rejected as a Cloudflare block page masquerading as HTTP 200.
+
+## Notes
+
+- This package is just "give me a keyword → get good direct-link stock media". It does **not** assemble videos — pair it with an assembler MCP (e.g. `video-assembler-mcp`) for the full pipeline.
+- The endpoint is Pexels' own public web API and could change at any time. It's a third-party behavior, out of our control; `pexels_health` exists precisely to catch that the day it happens.
+
+## License
+
+MIT

pexels_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pexels-mcp"
+version = "1.0.0"
+description = "MCP + CLI toolkit to search and download free Pexels stock images/videos. No API key, no quota. Built-in relevance gate kills Pexels's junk hits; picks the right resolution tier for vertical shorts."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "aqiu" }]
+keywords = ["mcp", "pexels", "stock", "videos", "images", "shorts", "video-assembly", "model-context-protocol"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Multimedia :: Video",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = []
+
+[project.scripts]
+pexels-mcp = "pexels_mcp.server:main"
+pexels-cli = "pexels_mcp.cli:main"
+
+[project.urls]
+Homepage = "https://modelscope.cn/mcp/servers"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pexels_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/README.md",
+  "/LICENSE",
+]

pexels_mcp-1.0.0/src/pexels_mcp/__init__.py

@@ -0,0 +1,15 @@
+"""pexels-mcp —— Pexels 素材检索与下载的 MCP 工具集（零第三方依赖）。
+
+两个入口：
+    pexels-mcp          MCP server（stdio JSON-RPC）
+    pexels-cli          命令行：search / get / health / info
+
+模块：
+    core     检索/选档/下载/自检（纯标准库）
+    server   MCP server，5 个工具
+    cli      命令行入口
+"""
+from __future__ import annotations
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

pexels_mcp-1.0.0/src/pexels_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+raise SystemExit(main())

pexels_mcp-1.0.0/src/pexels_mcp/cli.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""pexels-cli —— Pexels 图片/视频检索与下载（零依赖）
+
+    python pexels_cli.py search "elderly woman face" --kind video --n 5
+    python pexels_cli.py search "office meeting" --json
+    python pexels_cli.py get "hands holding cash" -o ./out --n 2
+    python pexels_cli.py health
+
+所有子命令都支持 --json，输出机器可读结构（便于被 Agent / 脚本消费）。
+中文 query 会被拒绝并给出提示——英文站不支持中文检索。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import core
+
+
+# --------------------------------------------------------------------- 输出
+
+def _fmt_size(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.1f}{unit}" if unit != "B" else f"{n}B"
+        n /= 1024.0
+    return f"{n:.1f}GB"
+
+
+def print_clips(clips: list[dict], query: str) -> None:
+    if not clips:
+        print(f"  0 条命中  (query={query!r})")
+        print("  提示：Pexels 是英文站，请用具体可视的英文词，如 'office meeting' 而非 'work'")
+        return
+    print(f"  命中 {len(clips)} 条  (query={query!r})\n")
+    for i, c in enumerate(clips, 1):
+        dur = f"{c['duration']:.0f}s" if c.get("duration") else "—"
+        star = "★" if c.get("exact_dim") else " "
+        print(f"  {i:2d}.{star} [{c['id']}] {c.get('width')}x{c.get('height')}  "
+              f"时长={dur:>5}  score={c.get('score', 0):.2f}")
+        title = (c.get("title") or "").strip()
+        if title:
+            print(f"      {title[:70]}")
+        tags = c.get("tags") or []
+        if tags:
+            print(f"      tags: {', '.join(tags[:6])}")
+        print(f"      {c['url']}")
+
+
+# --------------------------------------------------------------------- 子命令
+
+def cmd_search(a) -> int:
+    clips = core.search(
+        a.query,
+        kind=a.kind,
+        limit=a.num,
+        orientation=a.orientation,
+        target=None if a.any_size else tuple(a.target),
+        pages=a.pages,
+        need_sec=a.need_sec,
+        min_duration=a.min_duration,
+        max_duration=a.max_duration,
+        strict=a.strict,
+    )
+    if a.json:
+        print(json.dumps({"query": a.query, "kind": a.kind,
+                          "count": len(clips), "clips": clips},
+                         ensure_ascii=False, indent=2))
+    else:
+        print_clips(clips, a.query)
+    return 0 if clips else 3
+
+
+def cmd_get(a) -> int:
+    res = core.fetch(
+        a.query,
+        out_dir=a.out,
+        kind=a.kind,
+        n=a.num,
+        orientation=a.orientation,
+        target=None if a.any_size else tuple(a.target),
+        need_sec=a.need_sec,
+    )
+    if not a.json:
+        print_clips(res["clips"], a.query)
+        print()
+        for f in res["files"]:
+            if f["ok"]:
+                print(f"  ✓ {f['path']}  ({_fmt_size(f['bytes'])})")
+            else:
+                print(f"  ✗ id={f.get('id')}  {f['err']}")
+    if a.json:
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+    return 0 if res["downloaded"] else 3
+
+
+def cmd_health(a) -> int:
+    h = core.health()
+    if a.json:
+        print(json.dumps(h, ensure_ascii=False, indent=2))
+    else:
+        print(f"通道 {'✓ 可用' if h['ok'] else '✗ 不可用'}   "
+              f"耗时 {h['elapsed_sec']}s   端点 {h['endpoint']}")
+        for k, v in h["checks"].items():
+            mark = "✓" if v.get("ok") else "✗"
+            detail = v.get("err") or f"hits={v.get('hits')}"
+            print(f"  {mark} {k:<12} {detail}")
+        if h.get("warning"):
+            print(f"  ⚠ {h['warning']}")
+    return 0 if h["ok"] else 1
+
+
+def cmd_info(a) -> int:
+    """不联网，打印能力边界与用法要点。"""
+    print(json.dumps({
+        "endpoint": core.API_BASE,
+        "kinds": ["video", "image"],
+        "orientations": list(core.ORIENTATIONS),
+        "per_page_max": core.PER_PAGE_MAX,
+        "needs_api_key": False,
+        "needs_browser": False,
+        "notes": [
+            "内部 API v3，无需注册、无配额",
+            "中文 query 会被拒绝，必须先翻成英文具体词",
+            "内置相关性门槛：有效词 0 命中的候选直接丢弃",
+            "video_files 直接给多档直链，可按目标分辨率挑档",
+        ],
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+# --------------------------------------------------------------------- 入口
+
+def build_parser() -> argparse.ArgumentParser:
+    # allow_abbrev=False：否则 `--n 3` 会被当成 `--need-sec 3` 的前缀缩写，
+    # 条数静默回落到默认值——这类「参数写错却不报错」的坑必须在发布版里堵死。
+    p = argparse.ArgumentParser(
+        prog="pexels-cli",
+        description="Pexels 图片/视频检索与下载（内部 API v3，零依赖）",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+        allow_abbrev=False,
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def common(sp):
+        sp.add_argument("--kind", choices=["video", "image"], default="video",
+                        help="素材类型，默认 video")
+        sp.add_argument("-n", "--num", type=int, default=5,
+                        help="条数，默认 5（上限 24）")
+        sp.add_argument("--orientation", choices=list(core.ORIENTATIONS),
+                        default="portrait", help="画面方向，默认竖屏")
+        sp.add_argument("--target", nargs=2, type=int, default=[1080, 1920],
+                        metavar=("W", "H"), help="目标分辨率，默认 1080 1920")
+        sp.add_argument("--any-size", action="store_true",
+                        help="不按目标分辨率挑档，改为挑最大档")
+        sp.add_argument("--need-sec", type=float, default=0.0,
+                        help="场景需要的最短秒数，不够的会扣分排后")
+        sp.add_argument("--json", action="store_true", help="输出 JSON")
+
+    s = sub.add_parser("search", help="只检索，不下载", allow_abbrev=False)
+    s.add_argument("query")
+    s.add_argument("--pages", type=int, default=1, help="翻几页（每页最多 24）")
+    s.add_argument("--min-duration", type=float, default=0.0)
+    s.add_argument("--max-duration", type=float, default=0.0)
+    s.add_argument("--strict", action="store_true", help="网络失败时抛异常而非返回空")
+    common(s)
+    s.set_defaults(fn=cmd_search)
+
+    g = sub.add_parser("get", help="检索 + 下载", allow_abbrev=False)
+    g.add_argument("query")
+    g.add_argument("-o", "--out", default="./pexels_download", help="下载目录")
+    common(g)
+    g.set_defaults(fn=cmd_get)
+
+    h = sub.add_parser("health", help="通道自检（含假词反向校验）", allow_abbrev=False)
+    h.add_argument("--json", action="store_true")
+    h.set_defaults(fn=cmd_health)
+
+    i = sub.add_parser("info", help="打印能力边界（不联网）", allow_abbrev=False)
+    i.set_defaults(fn=cmd_info)
+
+    return p
+
+
+def main(argv=None) -> int:
+    a = build_parser().parse_args(argv)
+    try:
+        return a.fn(a)
+    except core.SearchError as e:
+        print(f"检索失败: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())