Agentic Stock Contributor

Not technical? Paste this to your AI agent (Claude Code, Codex, Cursor or Antigravity, running on your own computer; OpenCode also works):

Install and use this toolkit for me: https://github.com/Grunte12/agentic-stock-contributor. Read INSTALL.md and follow it. Explain each step in simple words and ask me before you change any settings.

The only thing you do yourself is load one Chrome extension (about 2 minutes); your agent walks you through it.

An end-to-end toolkit for working on Adobe Stock as a contributor with an AI agent: measure the market, plan sets, check and package your images, stage a verified upload for your final click, and read the outcomes. It has four parts that install together:

Conceptual walkthrough. The labeled diagrams below define the exact stages and boundaries; the contributor remains the only person who clicks Submit.

You work inside this folder. Clone it once; your research, batches, packages and results go in workspace/ (never pushed, see workspace/README.md), and every folder there has a guide the agent follows. Setup creates three files in it (STATE.md, LOG.md, PLAYBOOK.md) as the shared memory of every agent you use, so Claude, Codex or Cursor can pick up where another left off, and lessons from Adobe's results carry over. git pull updates the toolkit without touching your work.

Plus local commands (stdlib only) for the steps between "images exist" and "ready to stage": lint-registry, check-images, qc-tiles, check-qc, build-csv, prepare-plan. You bring your own image generator and choose a resize or upscaler after a canary comparison; the setup guide covers ChatGPT Free, no GPT Bridge, Colab Free and fully local fallbacks.

Start: docs/SETUP.md (about 10 minutes) · Safety, limits, terms: docs/SAFETY.md · Workflow: knowledge/production-workflow.md · Architecture: docs/architecture/ · Agents: AGENTS.md · Templates: examples/. Unofficial; not affiliated with Adobe. MIT licensed.

Details

Tools for AI agents that work on Adobe Stock. A Chrome extension reads Adobe Stock search pages and your own contributor dashboard; an MCP server turns what it reads into deterministic, traceable numbers: how crowded a keyword is, how your portfolio sells, and which uploads Adobe accepted or rejected (with Adobe's own cause).

The server gives an AI agent numbers about Adobe Stock supply. Code makes every number; the agent chooses keywords, reads tables and decides.

Mostly read-only. Its writes are upload staging and upload metadata, both off by default and only for a verified plan: staging drops files on the page's own drop zone (no clicks) to fill the portal's New list; metadata uses a short allow list of guarded clicks (Upload CSV, generative-AI box, include box, Save work, Select All, the People/Property answer 'No') and the portfolio read clicks plain page-number controls. It never clicks Submit or Delete (anything so named is refused in code), reads no cookies, automates no login and bypasses no CAPTCHA. Stdlib only (Python 3.11+, no dependencies).

Related MCP server: photocop

What it measures (and what it cannot)

Public Adobe Stock pages show: result count, AI flag (is_gentech), creator, category, size, and (asset page) keywords. They do not show download counts, views or upload dates (checked 2026-10-10). So there is no D/MO, no "new vs old" share and no gap score. Metrics (all in src/adobe_stock_analytics/metrics.py):

supply_rating is about supply only. Demand comes from Trends and your own sales.

Upload staging, know-how and skill

• stock_upload_stage(plan_path, with_metadata=true) / CLI upload-ready: preflights both operations, requires empty New, stages a complete wave and applies its metadata. Subset recovery uses separate upload-stage --only. Both upload switches must be on; never submits.

• stock_upload_metadata(plan_path) / CLI upload-metadata: applies the plan's CSV through the portal's own Upload CSV dialog, then sets generative AI, people/property and include-in-submission for all staged files and saves; never clicks Submit. Needs upload_metadata.enabled (user's switch) and refuses when the New list does not hold exactly the plan's files. Verified by reading All (N), Submit N, per-tile keywords and the two checkboxes back.

• stock_upload_stage(plan_path, only?) / CLI upload-stage: plan = the JSON written by prepare-plan (ready_for_upload: true, no failures, fresh). Every file is re-hashed; the extension fetches each file from the bridge (/v1/file, dispatched job only), re-checks sha256, drops them on the Uploads page's own drop zone, and reads the portal's "File types: All (N)" count back. Success = the count rose by exactly the number staged. A failed or partial stage stops the queue (never retried blindly). Protected folders can never be staged. upload_stage.enabled in config/local.json is the user's switch, read on every use. Details: knowledge/upload-and-portal.md.

• stock_knowledge(topic): index returns short topic names; a full topic is saved as an evidence artifact for a fresh-context worker. Large MCP results follow the same rule so the lead receives only status, counts, provenance and the next action. The MCP initialize reply carries the core rules as instructions.

• skills/adobe-stock/SKILL.md + knowledge/: python3 stock.py install-skill --confirm-write copies them to ~/.claude/skills/adobe-stock/ (dry run without the flag).

• Live-verified locally: staging and metadata have completed with count, keyword and flag verification while Submit remained untouched. Adobe can change its portal at any time, so first use on another account should still be a one-file canary.

Rules

1. Every number has provenance (obs_id or metric_id). Missing = null + reason, never 0.

2. Tables are rendered by stock_report into an evidence artifact; a fresh-context worker copies them unchanged. stock_verify_doc fails a doc with edited tables or numbers that are not cited as [m:<metric_id>].

3. No MCP tool accepts a URL, a number, a pacing value or a threshold. Pacing (25 s + jitter, 150 pages/day) and thresholds live in config/stock_analytics.json.

4. The queue stops on CAPTCHA, restriction, sign-in wall, HTTP 403/429, unknown page shape, or repeated filter failures. It never retries or bypasses. Only the user resumes: python3 stock.py resume.

The verifier checks digits only. A number spelled as a word is not checked, so it is a guard, not proof; the tables stay the source of truth.

Setup

1. Add the MCP server (print-mcp-config prints the JSON; .mcp.json.example is a template).

2. Write the pairing token into the extension folder: python3 stock.py write-extension-token (creates the git-ignored extension/token.js).

3. Chrome → chrome://extensions → Developer mode → Load unpacked → extension/. No token typing needed. A Chrome profile signed out of Adobe is recommended for market scans (not required).

4. In an agent session call stock_status; bridge_connected should be true. Then stock_scan, stock_wait, stock_report.

Without the extension, scripts/live_via_opencli.py <scans.json> runs the same queue through OpenCLI in your Chrome (dev/fallback).

Dashboard

Charts (opportunity ranking, niche map, attention over time, your downloads by sub-niche, posting windows) rendered from stored metrics as inline SVG. No scripts, no network.

• Agent: call stock_dashboard. It recomputes metrics from stored observations and returns a http://127.0.0.1:<port>/dashboard?t=<token> link for the user to open. The page reloads itself every minute.

• User: click the extension's toolbar button (0.5.0 or later). It asks the bridge for the same link and opens it in a tab.

• Offline copy: adobe-stock-analytics dashboard --out file.html.

The link token is derived from the pairing token but opens the dashboard only; it cannot pair an extension or post results. The route rejects a foreign Host header and any request with an Origin header, and sends no-store, no-referrer and a CSP that forbids scripts. Treat the link as private: the page shows your own downloads and earnings.

Tests

cd tests && PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -p 'test_*.py'

Local MCP fixture benchmark: python3 scripts/eval_mcp_workflow.py --repeats 3. It measures local latency and response size, without opening a browser or uploading. Tokens are character-based estimates; model cost and live portal speed are unmeasured. --score-plans checks case plans in workspace/evals/luna_low_*.json against tool schemas and expected actions; it does not execute those plans or prove live success.

Docs

docs/ has the setup, safety and toolkit architecture guides. CHANGELOG.md tracks extension changes.