adtest-mcp 1.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,102 @@
+# AdTest.AI MCP server
+
+[![npm](https://img.shields.io/npm/v/adtest-mcp)](https://www.npmjs.com/package/adtest-mcp) · Registry name: `ai.adtest/adtest-mcp` · License: MIT
+
+Adds a single **`analyze_advert`** tool to Claude (Desktop, Code, or any MCP client) that
+runs AdTest.AI's **AI-only** 13-dimension analysis of an advert — **image, video, or text** —
+and returns a detailed scoring report. (Human-panel validation is available in the
+[web app](https://app.adtest.ai) only, not through this server.)
+
+Quick add for Claude Code:
+
+```bash
+claude mcp add adtest -e ADTEST_API_KEY=adk_your_key_here -- npx -y adtest-mcp
+```
+
+## Setup
+
+1. **Get an API key:** sign in at <https://app.adtest.ai> → the **Developer** (gear)
+   icon → **Generate key**. Make sure your wallet has funds — each successful
+   analysis costs **$1**.
+
+2. **Add the server to your Claude config** (Claude Desktop:
+   `claude_desktop_config.json`; Claude Code: `.mcp.json`):
+
+   ```json
+   {
+     "mcpServers": {
+       "adtest": {
+         "command": "npx",
+         "args": ["-y", "adtest-mcp"],
+         "env": { "ADTEST_API_KEY": "adk_your_key_here" }
+       }
+     }
+   }
+   ```
+
+   Or run it from a local checkout (after `npm install` in this folder):
+
+   ```json
+   {
+     "mcpServers": {
+       "adtest": {
+         "command": "node",
+         "args": ["/absolute/path/to/mcp-server/index.js"],
+         "env": { "ADTEST_API_KEY": "adk_your_key_here" }
+       }
+     }
+   }
+   ```
+
+3. **Restart Claude**, then just ask:
+   - *“Analyze this advert: https://example.com/ad.jpg”*
+   - *“Analyze this ad video file: /Users/me/promo.mp4”*
+   - *“Score this ad copy: 50% off all shoes this weekend — shop now.”*
+
+## The tool
+
+`analyze_advert` — provide **one** of:
+
+| arg | meaning |
+|-----|---------|
+| `url` | public URL of an image or video advert (we download it) |
+| `file_path` | local image/video file to upload |
+| `text` | ad copy to analyze |
+| `brand_url` *(optional)* | advertiser website — improves brand/logo detection |
+
+Returns the AI analysis text plus the amount charged and your remaining balance.
+
+## How it works (async — so video works)
+
+The server submits the job to `POST /developer/ai-analysis/jobs`, gets a
+`job_id` back immediately, then polls `GET /developer/ai-analysis/jobs/{job_id}`
+every few seconds until it's `complete` or `failed`. This is why **video works**:
+a single synchronous request would be cut off by the CDN edge timeout (~100s),
+but video analysis can take several minutes. You're charged **once, on success**,
+when the job completes — a failed job is never billed.
+
+## Notes
+
+- Registered in the official MCP Registry as `ai.adtest/adtest-mcp`.
+
+- Auth is the `x-api-key` header, set from `ADTEST_API_KEY`.
+- Endpoint defaults to `https://app.adtest.ai/adtest-api`; override with
+  `ADTEST_API_BASE` for staging.
+- Poll ceiling defaults to 15 min; override with `ADTEST_POLL_TIMEOUT_MS`
+  (milliseconds) for very long video.
+- Rate limits: 30 submits/min and 2000/day per key (60/min per IP); polling is
+  generous (240/min) and handled for you.
+- Errors come back as readable text: `invalid_api_key`, `insufficient_funds`,
+  `no_creative`, `invalid_url`, `unsupported_media_type`, `too_many_requests`,
+  `analysis_failed` (the last is **not** charged).
+- Requires Node ≥ 18.
+
+## Links
+
+- Product: <https://adtest.ai>
+- App and API keys: <https://app.adtest.ai>
+- Issues: <https://github.com/menaker/adtest-mcp/issues>
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/index.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * AdTest MCP server — exposes the AI-only ad-analysis API as a Claude tool.
+ *
+ * Auth: set ADTEST_API_KEY to your AdTest developer API key
+ * (https://app.adtest.ai → Developer settings). Override the endpoint with
+ * ADTEST_API_BASE if needed (default https://app.adtest.ai/adtest-api).
+ *
+ * Tool: analyze_advert(url | file_path | text, brand_url?) → AI analysis text.
+ *
+ * Uses the ASYNC job flow (submit → poll) so VIDEO works: a long synchronous
+ * request would be cut off by the CDN edge timeout (~100s), but video analysis
+ * can take several minutes. Each successful analysis costs 1 credit from the
+ * wallet tied to the API key.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+
+const API_KEY = process.env.ADTEST_API_KEY || "";
+const API_BASE = (process.env.ADTEST_API_BASE || "https://app.adtest.ai/adtest-api").replace(/\/+$/, "");
+
+// Poll cadence + ceiling. Video (analyzeVideo + TwelveLabs) can take minutes.
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = Number(process.env.ADTEST_POLL_TIMEOUT_MS || 15 * 60 * 1000);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const TOOL = {
+  name: "analyze_advert",
+  description:
+    "Run an AI-only analysis of an advert and get a detailed scoring report. " +
+    "Provide exactly ONE of: `url` (a public image or video URL), `file_path` " +
+    "(a local image/video file to upload), or `text` (ad copy). Optionally pass " +
+    "`brand_url` to improve brand/logo detection. Video is supported and may take " +
+    "a few minutes. Each successful analysis costs 1 credit from your AdTest wallet.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "Public URL of an image or video advert" },
+      file_path: { type: "string", description: "Local path to an image or video file to upload" },
+      text: { type: "string", description: "Ad copy text to analyze" },
+      brand_url: { type: "string", description: "Advertiser brand/website URL (optional)" },
+    },
+  },
+};
+
+const server = new Server(
+  { name: "adtest-ai-analysis", version: "1.1.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [TOOL] }));
+
+const errorResult = (text) => ({ content: [{ type: "text", text }], isError: true });
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  if (req.params.name !== TOOL.name) {
+    return errorResult(`Unknown tool: ${req.params.name}`);
+  }
+  if (!API_KEY) {
+    return errorResult(
+      "Missing ADTEST_API_KEY. Set it to your AdTest developer API key (app.adtest.ai → Developer settings).",
+    );
+  }
+  const { url, file_path, text, brand_url } = req.params.arguments || {};
+  if (!url && !file_path && !text) {
+    return errorResult("Provide one of: url, file_path, or text.");
+  }
+
+  const submitEndpoint = `${API_BASE}/developer/ai-analysis/jobs`;
+
+  // 1) Submit the job → expect 202 { job_id }.
+  let resp;
+  try {
+    if (file_path) {
+      const buf = readFileSync(file_path);
+      const form = new FormData();
+      form.append("file", new Blob([buf]), basename(file_path));
+      if (brand_url) form.append("brand_url", brand_url);
+      resp = await fetch(submitEndpoint, { method: "POST", headers: { "x-api-key": API_KEY }, body: form });
+    } else {
+      resp = await fetch(submitEndpoint, {
+        method: "POST",
+        headers: { "x-api-key": API_KEY, "content-type": "application/json" },
+        body: JSON.stringify({ url, text, brand_url }),
+      });
+    }
+  } catch (e) {
+    return errorResult(`Request error: ${e.message}`);
+  }
+
+  let sub = {};
+  try { sub = await resp.json(); } catch { /* non-JSON body */ }
+  if (!resp.ok || !sub.job_id) {
+    const err = sub.error || `HTTP ${resp.status}`;
+    const hint = err === "insufficient_funds" ? " — top up your AdTest wallet." : "";
+    const detail = sub.detail ? ` (${sub.detail})` : "";
+    return errorResult(`Analysis failed: ${err}${detail}${hint}`);
+  }
+
+  // 2) Poll until the job is complete or failed.
+  const pollUrl = `${submitEndpoint}/${sub.job_id}`;
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  let data = null;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    let pr;
+    try {
+      pr = await fetch(pollUrl, { headers: { "x-api-key": API_KEY } });
+    } catch {
+      continue; // transient network blip — keep polling
+    }
+    if (pr.status === 429) continue; // rate-limited poll — back off one interval
+    let pj = {};
+    try { pj = await pr.json(); } catch { continue; }
+    if (pj.status === "complete") { data = pj; break; }
+    if (pj.status === "failed") {
+      return errorResult(`Analysis failed: ${pj.error || "analysis_failed"}`);
+    }
+    // status === "processing" → keep polling
+  }
+
+  if (!data) {
+    return errorResult(
+      `Analysis is still processing after ${Math.round(POLL_TIMEOUT_MS / 60000)} min ` +
+      `(job ${sub.job_id}). It may still finish — try again shortly.`,
+    );
+  }
+
+  const a = data.analysis || {};
+  const c = data.charge || {};
+  const sym = c.symbol || "$";
+  const footer = `\n\n— charged ${sym}${c.amount ?? 1} ${c.currency || ""} (balance: ${sym}${c.balance_after ?? "?"}), model: ${a.model || "?"}`.replace(/\s+\)/, ")");
+  return { content: [{ type: "text", text: (a.text || "(no analysis returned)") + footer }] };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("adtest-ai-analysis MCP server running on stdio");

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "adtest-mcp",
+  "version": "1.1.0",
+  "description": "AI-only ad scoring for Claude: score image, video or text ads on 13 dimensions before you spend.",
+  "mcpName": "ai.adtest/adtest-mcp",
+  "type": "module",
+  "bin": {
+    "adtest-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ad-testing",
+    "creative-testing",
+    "advertising",
+    "marketing",
+    "ai"
+  ],
+  "homepage": "https://adtest.ai/",
+  "bugs": {
+    "url": "https://github.com/menaker/adtest-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/menaker/adtest-mcp.git"
+  },
+  "author": "AdTest.AI <support@adtest.ai> (https://adtest.ai)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}