{"_id":"@577-tools/ad-lab-mcp","_rev":"5-87ed999117529368c77b1f83b5af19ba","name":"@577-tools/ad-lab-mcp","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@577-tools/ad-lab-mcp","version":"0.1.0","license":"UNLICENSED","_id":"@577-tools/ad-lab-mcp@0.1.0","maintainers":[{"name":"moolbneid","email":"dien@ksrgroup.id"}],"bin":{"ad-lab":"src/cli.js","ad-lab-mcp":"src/server.js"},"dist":{"shasum":"0c49b3be8da8d92b32f9bf483549f24599faa57f","tarball":"https://registry.npmjs.org/@577-tools/ad-lab-mcp/-/ad-lab-mcp-0.1.0.tgz","fileCount":6,"integrity":"sha512-Mv0cVortMFnL3KWrjO4nReS2hWaF2CFF4/oxz8iRywRpraqJbiH9GEAGkPwG1FnqoqyKXdpN8JSZkdSwdvy9Jg==","signatures":[{"sig":"MEYCIQDVMqEBiZfpKwjua+2gwYUYkGCWgmD6aSOI3LLE9LLnLwIhAJqBN3mmKP/TUm/sxBEXWXyfe/gkJxRarD37Fowr+tb7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":17723},"type":"module","engines":{"node":">=18"},"gitHead":"e6afab2d72b303a61644bfe6bc7ebbf05f3bb1e9","_npmUser":{"name":"moolbneid","email":"dien@ksrgroup.id"},"_npmVersion":"11.16.0","description":"Local MCP server and CLI for Ad Lab creative generation workflows.","directories":{},"_nodeVersion":"26.3.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ad-lab-mcp_0.1.0_1783312904023_0.0023594924514795945","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@577-tools/ad-lab-mcp","version":"0.1.1","license":"UNLICENSED","_id":"@577-tools/ad-lab-mcp@0.1.1","maintainers":[{"name":"moolbneid","email":"dien@ksrgroup.id"}],"bin":{"ad-lab":"src/cli.js","ad-lab-mcp":"src/server.js"},"dist":{"shasum":"c514be786a673284c9fa82fb55c3288db91fe3c2","tarball":"https://registry.npmjs.org/@577-tools/ad-lab-mcp/-/ad-lab-mcp-0.1.1.tgz","fileCount":6,"integrity":"sha512-p7CHRVMjPKmDh5s+09KUwY119dHTtPkEh3NMUsJeay98Cu6e53e6sspXrAMZaevLp/tyuHIEEP2XwRKBaU5/dA==","signatures":[{"sig":"MEYCIQDXmnP3TLlbhw+y9GjuXI89/UeWN6xaX0sEN/lhrhmv4wIhALHMRI4ZcJy6J6FJ8MwuW5tCFId4v4VxbqOrB6n8vudC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18010},"type":"module","engines":{"node":">=18"},"gitHead":"c14173ee883b13a4788ba9f03039cf22921d2b09","_npmUser":{"name":"moolbneid","email":"dien@ksrgroup.id"},"_npmVersion":"11.16.0","description":"Local MCP server and CLI for Ad Lab creative generation workflows.","directories":{},"_nodeVersion":"26.3.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ad-lab-mcp_0.1.1_1783332658998_0.29075636663880045","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@577-tools/ad-lab-mcp","version":"0.1.2","license":"UNLICENSED","_id":"@577-tools/ad-lab-mcp@0.1.2","maintainers":[{"name":"moolbneid","email":"dien@ksrgroup.id"}],"bin":{"ad-lab":"src/cli.js","ad-lab-mcp":"src/server.js"},"dist":{"shasum":"92bab77f17cb6b7aed1ecbe77f95555fc2e61e49","tarball":"https://registry.npmjs.org/@577-tools/ad-lab-mcp/-/ad-lab-mcp-0.1.2.tgz","fileCount":6,"integrity":"sha512-715CtfZ4bwpEnUrMa9faJQycKT5OYoyIr03wjgzzOIgor6C/WiVqLVgVPCMay0U6NbXMmMfMhVeatOVKNt7Djw==","signatures":[{"sig":"MEUCIFYG7oh+SzAGqmXGoYhu5YzyVKYcmDlHARQ7vvvC0Z+AAiEAs2b52oDqfKV21fTaYN6gXnsvrh8YRzzboBEBx3WBrBo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18456},"type":"module","engines":{"node":">=18"},"gitHead":"fc40e190495b4644d1b52b012194e308ba265c8f","_npmUser":{"name":"moolbneid","email":"dien@ksrgroup.id"},"_npmVersion":"11.16.0","description":"Local MCP server and CLI for Ad Lab creative generation workflows.","directories":{},"_nodeVersion":"26.3.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ad-lab-mcp_0.1.2_1783336158718_0.9850524310007807","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@577-tools/ad-lab-mcp","version":"0.1.3","license":"UNLICENSED","_id":"@577-tools/ad-lab-mcp@0.1.3","maintainers":[{"name":"moolbneid","email":"dien@ksrgroup.id"}],"bin":{"ad-lab":"src/cli.js","ad-lab-mcp":"src/server.js"},"dist":{"shasum":"d20c964c8808ed7822e08f62ef684a60767203d9","tarball":"https://registry.npmjs.org/@577-tools/ad-lab-mcp/-/ad-lab-mcp-0.1.3.tgz","fileCount":6,"integrity":"sha512-P1z1/RP14fcu/dt09t1DrFl4l+s+2fcJToZGuwD3l0ZAL/WQswnHiPTjD4eotSC5sAiFfs9jMYdFqbPUh8Lzxw==","signatures":[{"sig":"MEQCIH58o8/uiOuytJ90i4B5UXxCpmKxOVPDjz5DiFVGprG4AiAqbJksugKHZChPrE2DFJGL7VJVHGHngJMtJodR65FTDA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18205},"type":"module","engines":{"node":">=18"},"gitHead":"274cd47fa9ee31fb71116c161de9b763d217faf5","_npmUser":{"name":"moolbneid","email":"dien@ksrgroup.id"},"_npmVersion":"11.16.0","description":"Local MCP server and CLI for Ad Lab creative generation workflows.","directories":{},"_nodeVersion":"26.3.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ad-lab-mcp_0.1.3_1783339928797_0.938424386868375","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"@577-tools/ad-lab-mcp@0.2.0","bin":{"ad-lab":"src/cli.js","ad-lab-mcp":"src/server.js"},"dist":{"shasum":"2fd3020537b3011f57b5172dde4ded7f506da5ed","tarball":"https://registry.npmjs.org/@577-tools/ad-lab-mcp/-/ad-lab-mcp-0.2.0.tgz","fileCount":6,"integrity":"sha512-GIvWuYPm3+Anlh4Lo1T2g8mLvRlySg4NqfGzrrPipDGGUv2KwnMaL7G/oRsI0cDmjGqBDuaVgfMoPnvJhJPy5Q==","signatures":[{"sig":"MEYCIQDZE6k34kjeedmicQYB6m1OzPVBmIL9kH5yPBawh2kicgIhAI2aVAJn61uyRXOh7JzvH2lrrpZBL/NckLhLefSv74us","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICAAj2HSzsxa5oiLsJzM4LqYL9rwbzsYnvwPVymMXJP0AiEAxPXaW65L2nWfDDxwGZvYBF6GDaCRvNFOjzF38/P33nk="}],"unpackedSize":32125},"name":"@577-tools/ad-lab-mcp","type":"module","engines":{"node":">=18"},"gitHead":"86214e3a2d43e3f9ef1928881b06f90c4c804b42","license":"UNLICENSED","version":"0.2.0","_npmUser":{"name":"moolbneid","email":"dien@ksrgroup.id"},"_npmVersion":"11.16.0","description":"Local MCP server and CLI for Ad Lab creative generation workflows.","directories":{},"maintainers":[{"name":"moolbneid","email":"dien@ksrgroup.id"}],"_nodeVersion":"26.3.0","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ad-lab-mcp_0.2.0_1787405334410_0.8819864463019729"}}},"time":{"created":"2026-07-06T04:41:43.907Z","modified":"2026-08-22T13:28:54.738Z","0.1.0":"2026-07-06T04:41:44.149Z","0.1.1":"2026-07-06T10:10:59.133Z","0.1.2":"2026-07-06T11:09:18.867Z","0.1.3":"2026-07-06T12:12:08.957Z","0.2.0":"2026-08-22T13:28:54.492Z"},"license":"UNLICENSED","description":"Local MCP server and CLI for Ad Lab creative generation workflows.","maintainers":[{"name":"moolbneid","email":"dien@ksrgroup.id"}],"readme":"# Ad Lab MCP\n\nLocal MCP server and CLI for staff agents working with a private Ad Lab creative generation app. This package is a thin remote client over the deployed edge functions:\n\n- `ad-lab-context`\n- `ad-lab-render`\n- `ad-lab-ingest`\n\nIt does not contain database logic, image generation logic, or dependencies on the BLCRM root package.\n\n## Setup\n\nRequired environment:\n\n- `AD_LAB_TOKEN`: required. Use an owner-minted Ad Lab token.\n- `AD_LAB_FUNCTIONS_URL`: required. Use the private BLCRM Ad Lab proxy URL from the internal \"Connect your agent\" panel.\n\nOptional environment:\n\n- `AD_LAB_SUPABASE_ANON`: optional anon key fallback if the platform route requires an `apikey` header.\n\nThis public README intentionally uses placeholders. Do not publish real tokens or private project routing values; copy the working staff config from the internal Ad Lab app.\n\nClaude Code:\n\n```bash\nclaude mcp add ad-lab --env AD_LAB_TOKEN=adlab_XXXX --env AD_LAB_FUNCTIONS_URL=https://your_blcrm_domain/api/ad-lab-mcp -- npx -y @577-tools/ad-lab-mcp\n```\n\nCodex CLI (`~/.codex/config.toml`):\n\n```toml\n[mcp_servers.ad-lab]\ncommand = \"npx\"\nargs = [\"-y\", \"@577-tools/ad-lab-mcp\"]\nenv = { AD_LAB_TOKEN = \"adlab_XXXX\", AD_LAB_FUNCTIONS_URL = \"https://your_blcrm_domain/api/ad-lab-mcp\" }\n```\n\nLocal checkout variant:\n\n```toml\n[mcp_servers.ad-lab]\ncommand = \"node\"\nargs = [\"<abs path>/ad-lab-mcp/src/server.js\"]\nenv = { AD_LAB_TOKEN = \"adlab_XXXX\", AD_LAB_FUNCTIONS_URL = \"https://your_blcrm_domain/api/ad-lab-mcp\" }\n```\n\n## MCP Configuration\n\nCopy this stdio block into the MCP config used by your agent:\n\n```json\n{\n  \"mcpServers\": {\n    \"ad-lab\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@577-tools/ad-lab-mcp\"],\n      \"env\": {\n        \"AD_LAB_TOKEN\": \"adlab_XXXX\",\n        \"AD_LAB_FUNCTIONS_URL\": \"https://your_blcrm_domain/api/ad-lab-mcp\"\n      }\n    }\n  }\n}\n```\n\nFor a globally installed or locally linked package, use the binary directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"ad-lab\": {\n      \"command\": \"ad-lab-mcp\",\n      \"env\": {\n        \"AD_LAB_TOKEN\": \"adlab_XXXX\",\n        \"AD_LAB_FUNCTIONS_URL\": \"https://your_blcrm_domain/api/ad-lab-mcp\"\n      }\n    }\n  }\n}\n```\n\n## CLI Usage\n\nThe CLI is intended for headless agent runs such as `codex exec`:\n\n```bash\ncodex exec \"Use the Ad Lab CLI to fetch TummyZen context\" -- ad-lab get_product_context --json '{\"product\":\"tummyzen\"}'\n```\n\nDirect examples:\n\n```bash\nad-lab get_product_context --json '{\"product\":\"tummyzen\"}'\nad-lab get_knowledge_index --json '{}'\nad-lab render --json '{\"product\":\"tummyzen\",\"aspect_ratio\":\"4:5\",\"prompt\":\"A clean 4:5 paid social ad concept for TummyZen.\"}'\nad-lab add_idea --json '{\"spec\":{\"product\":\"tummyzen\",\"language\":\"id\",\"description\":\"Generated concept\",\"copy\":{\"headline\":\"Perut kembung setelah makan?\",\"primary_text\":\"Jaga kenyamanan perut setiap hari bersama TummyZen. Pesan sekarang melalui WhatsApp.\"}},\"render_object_key\":\"PROJECT_ID/renders/JOB_ID.png\"}'\n```\n\nRun help without a token:\n\n```bash\nad-lab --help\n```\n\n## Tools\n\n- `get_product_context`: returns the product context bundle: `knowledge.product_md`, `knowledge.carousel_profile`, `knowledge.deep_profile`, `brand_voice`, `claim_safety`, `brand_docs`, `testimonials`, `testimonials_mapping`, `packshots`, `winners`, `losers`, and `rejected_lessons`. Read `brand_docs[\"ad-lab-agent-playbook\"]`, `brand_docs[\"winning-copy-formulas\"]`, `brand_docs[\"winning-ad-styles\"]`, and `brand_docs[\"adgenius-playbook\"]` before drafting.\n- `get_knowledge_index`: returns the full distilled adgenius knowledge index: large JSON with global Meta signals, per-product learnings, and style clusters.\n- `list_winners`: returns winning Creative Specs for a product. **Incomplete on its own** — the scorer only walks Ad Lab's own table, so ads built directly in Meta can never appear here however well they sell, and the stored set skews toward stopped ads. Always pair it with `list_external_winners`. `performance.*` are best-rolling-window values, not lifetime totals; the array is capped (default 50, max 200) so its length is not a count.\n- `list_losers`: returns losing Creative Specs — the negative lesson set. `loser` means no canonical evidence the creative ever sold, judged against a **zero** impression floor, so it does not imply the creative was meaningfully tested. Rows with recorded purchases are filtered out defensively.\n- `list_external_winners`: returns LIVE Meta ads that clear the same winner bar but have no Ad Lab creative behind them — the half of \"what actually sells\" that `list_winners` structurally cannot see. Read-only context: no Ad Lab source assets, so these images cannot be used as render references.\n- `get_flow_status`: exact per-stage counts for a product from a real SQL count, plus which stages an agent may set, which commits spend, and which the system owns.\n- `get_lab_capacity`: free Ad Lab ad-set slots per product. A product at zero free slots has nowhere to place a new ad. `free_slots: null` means unknown, not zero.\n- `list_revision_requests`: creatives sitting in Revision with the staff instructions explaining what was wrong, the parent creative, copy, angle, and current image.\n- `get_creative`: reads one creative by id — full spec, current stage, `short_code`, status, lineage, signed image URL, and `published_at` / `stopped_at` / `scored_at`.\n- `get_scoring_rules`: the live winner/loser bar the scorer enforces, served from the scoring module so it stays correct when the owner moves a dial.\n- `render`: calls the central render edge function with a prompt and optional product, up to 3 reference images (`reference_object_keys`; `reference_packshot` is a back-compat alias for the first), and aspect ratio. Each call is a billable image generation and consumes a daily-cap slot even when it fails.\n- `add_idea`: required final handoff for every finished product ad; sends the Creative Spec plus an optional render object key or base64 PNG into the Ad Lab Ideas tab.\n- `advance_stage`: moves a creative between staff stages through the ingest edge function. `ideas`, `revision`, `rejected` and `archived` are draft moves that cost nothing. **`queue` commits ad spend** — see below.\n\n### `queue` commits ad spend\n\n`advance_stage` accepts `queue`, and queueing is not a draft move. Queued creatives are picked\nup by the Ad Lab automation run and published into a live, spending Meta ad set as ACTIVE ads\nwith **no further human step**. Use `queue` only when a human has asked for that specific\ncreative to go live; everything else an agent does lands in Ideas for staff review.\n\n`advance_stage` also does not check which stage the creative is currently in, so it will move a\nrunning ad out of the scorer's reach. Call `get_creative` first.\n\n## Choosing Reference Images\n\n1. Call `get_product_context` for the product.\n2. From `packshots`, pick a PHOTOGRAPHIC packshot and use its `object_key`; do NOT use the g4/gold-standard packshots for photoreal renders (hand-drawn G4 style anchors; only for deliberate G4-style work).\n3. Optionally add one winner image or asset `object_key` from `winners[]` as a style reference.\n4. Use at most 3 references, with the packshot first; pass `object_key`s, not signed URLs, because signed URLs expire after 1h.\n\n`ad-lab-revise` remains single-image; multi-reference support is currently limited to `ad-lab-render`.\n\n## Generate To Add Idea Loop\n\n1. Call `get_lab_capacity`. A product with zero free slots has nowhere to place a new ad — raise it with the owner rather than generating into it.\n2. Call `get_flow_status` for the product to see what is already in flight. A large revision or queue backlog usually means fixing existing cards beats adding new ones.\n3. Call `get_product_context` for the product.\n4. Read `brand_docs[\"ad-lab-agent-playbook\"]`, `brand_docs[\"winning-copy-formulas\"]`, `brand_docs[\"winning-ad-styles\"]`, `brand_docs[\"adgenius-playbook\"]`, claim-safety, and `knowledge.deep_profile`.\n5. Study **both** winner sets — `list_winners` (Ad Lab's own, skewed toward stopped ads) and `list_external_winners` (live ads selling right now) — then `losers` and `rejected_lessons`.\n6. Call `get_scoring_rules` so you know the bar a creative actually has to clear.\n7. Draft copy from the proven formulas: short symptom-hook headline, primary text ending with the WhatsApp order line, and soft claims only in body copy.\n8. Call `render` with the final prompt and `reference_object_keys: [<packshot object_key>, <optional winner image object_key>]`.\n9. Do not stop in chat or at render. For every finished product ad, call `add_idea` with the Creative Spec and the returned `render.object_key` so the work appears in the Ad Lab Ideas tab.\n10. Confirm `add_idea` returns `stage: \"ideas\"`, then `get_creative` to verify the card.\n11. To work the revision backlog: `list_revision_requests`, read the staff instructions, render a fix, and `add_idea` it — the fix lands in Ideas for review.\n12. `advance_stage` moves drafts between `ideas` / `revision` / `rejected` / `archived`. Do not use `queue` on your own initiative — it commits ad spend.\n","readmeFilename":"README.md"}