pubweb-ads-mcp 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# pubweb-ads-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that gives **Claude** a knowledge base of
+your scraped competitor ads — **semantic search**, ad copy, **images/videos**, and the
+landing→destination **funnels** — so Claude can reason over them like a RAG.
+
+It's a thin, secure wrapper over the pubweb external API (`/api/v1`): one **bearer API key**,
+every call scoped server-side to your account, read-only.
+
+## Setup (2 steps)
+
+**1. Create an API key** — in pubweb → **Settings → API Keys** → "Create key for Claude/MCP".
+Pick the abilities `v1:ads:read` and `v1:ads:search`. Copy the key (shown once).
+
+**2. Add the server to your MCP client.**
+
+Claude Desktop (`claude_desktop_config.json`) or Claude Code (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pubweb-ads": {
+      "command": "npx",
+      "args": ["-y", "pubweb-ads-mcp"],
+      "env": { "PUBWEB_API_KEY": "PASTE_YOUR_KEY_HERE" }
+    }
+  }
+}
+```
+
+That's it — restart the client and ask Claude things like *"search the ad knowledge base for
+job-offer ads"* or *"show me the funnel of ad <id>"*.
+
+> Self-hosted / staging? add `"PUBWEB_API_URL": "https://your-domain"` to `env`
+> (default `https://app.pubweb.ai`).
+
+### Run without npx (local checkout)
+
+```bash
+cd mcp/ads-mcp && npm install
+PUBWEB_API_KEY=... node src/index.js          # stdio server
+PUBWEB_API_KEY=... npm run smoke               # lists the tools (sanity check)
+```
+…and point the MCP client's `command`/`args` at `node /abs/path/mcp/ads-mcp/src/index.js`.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `ads_search(query, network?, funnel_type?)` | **Semantic** (vector) search — multilingual; ranked ads with copy + thumbnail + funnel summary |
+| `ads_browse(q?, network?, funnel_type?, format?, from?, to?, per_page?)` | Keyword/filter browse, paginated |
+| `ad_get(id)` | One ad — full copy, media list, funnel summary |
+| `ad_media(id)` | Presigned image/video URLs (30-min TTL) |
+| `ad_funnel(id)` | The ad's landing→destination funnel |
+| `targets_list()` | Competitor domains you track, with ad counts |
+| `whoami()` | Verify the key + see its abilities (setup/debug) |
+
+## Security
+
+- **Bearer key only** — never your password/session. The key is `v1:ads:read[/search]` scoped;
+  it can't touch anything else. Stored only in your local MCP config.
+- The server **never** sees more than your own ads (scoped server-side by the key owner).
+- Read-only: no tool can create, modify, or delete anything.
+- Rate-limited per key (HTTP 429 + `Retry-After` surfaces as a normal tool error).
+
+## Releasing (maintainers)
+
+Publishing is automated by `.github/workflows/publish-mcp.yml` — it fires only on changes
+under `mcp/ads-mcp/**` and publishes to npm **only when `version` here is bumped** (an
+unbumped change runs but skips publish). So a release is just:
+
+```bash
+npm version patch    # or minor / major — bumps package.json
+git commit -am "release(ads-mcp): vX.Y.Z" && git push   # → workflow publishes
+```
+
+The package is **unscoped** — it publishes to the personal npm account that owns the token.
+One-time setup by the repo owner: create an automation token on npmjs.com, then add it as
+the GitHub repo secret `NPM_TOKEN`.
+

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "pubweb-ads-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing the pubweb Ads knowledge base (semantic search over scraped competitor ads, with media + funnels) to Claude and other MCP clients.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/f1sc4ll/pubweb-saas.git",
+    "directory": "mcp/ads-mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "pubweb-ads-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "smoke": "node test/smoke.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * pubweb-ads-mcp — MCP server that gives Claude a RAG-style knowledge base of scraped
+ * competitor ads (semantic search + media + funnels), backed by the pubweb external API
+ * (/api/v1). Auth is a single bearer API key; every call is scoped server-side to the
+ * key owner's targets. Transport is stdio (run locally by the MCP client).
+ *
+ * Env:
+ *   PUBWEB_API_KEY  (required)  the v1 API key, abilities v1:ads:read [+ v1:ads:search]
+ *   PUBWEB_API_URL  (optional)  default https://app.pubweb.ai
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const VERSION = '0.1.0';
+const API_URL = (process.env.PUBWEB_API_URL || 'https://app.pubweb.ai').replace(/\/+$/, '');
+const API_KEY = process.env.PUBWEB_API_KEY;
+
+if (!API_KEY) {
+  console.error('[pubweb-ads-mcp] PUBWEB_API_KEY is required (create one in pubweb → Settings → API Keys).');
+  process.exit(1);
+}
+
+/** GET /api/v1{path} with the bearer key; throws a readable error on non-2xx / network fail. */
+async function apiGet(path, params = {}) {
+  const url = new URL(`${API_URL}/api/v1${path}`);
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, String(v));
+  }
+
+  let res;
+  try {
+    res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${API_KEY}`,
+        Accept: 'application/json',
+        // A named UA is REQUIRED — the edge (Cloudflare) 520s requests with an empty
+        // User-Agent. Any non-empty value passes; this identifies the client cleanly.
+        'User-Agent': `pubweb-ads-mcp/${VERSION}`,
+      },
+      signal: AbortSignal.timeout(20000),
+    });
+  } catch (e) {
+    throw new Error(`network error calling ${path}: ${e.message}`);
+  }
+
+  const body = await res.text();
+  if (!res.ok) {
+    throw new Error(`API ${res.status} on ${path}: ${body.slice(0, 400)}`);
+  }
+  try {
+    return JSON.parse(body);
+  } catch {
+    return body;
+  }
+}
+
+const okText = (data) => ({
+  content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }],
+});
+const errText = (e) => ({ content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true });
+const run = async (fn) => {
+  try {
+    return okText(await fn());
+  } catch (e) {
+    return errText(e);
+  }
+};
+
+const server = new McpServer({ name: 'pubweb-ads', version: VERSION });
+
+server.tool(
+  'ads_search',
+  'Semantic (vector) search over the ad knowledge base. Pass a natural-language query — it is multilingual, so "emprego" / "job" / "empleo" all match the same concept. Returns ads ranked by relevance with copy, advertiser, a thumbnail URL and a funnel summary. Use this for "find ads about X".',
+  {
+    query: z.string().describe('Natural-language search query'),
+    network: z.string().optional().describe('Filter by ad network (e.g. "meta")'),
+    funnel_type: z.string().optional().describe('Filter by funnel type'),
+  },
+  async (args) => run(() => apiGet('/ads/search', { q: args.query, network: args.network, funnel_type: args.funnel_type })),
+);
+
+server.tool(
+  'ads_browse',
+  'Keyword + filter browse of ads (no embeddings), paginated. Use ads_search for relevance; use this for exact filters, date ranges, or paging through results.',
+  {
+    q: z.string().optional().describe('Keyword (advertiser/headline/link/funnel)'),
+    network: z.string().optional(),
+    funnel_type: z.string().optional(),
+    format: z.string().optional().describe('display_format, e.g. "image" | "video"'),
+    from: z.string().optional().describe('ISO date — ads last seen on/after'),
+    to: z.string().optional().describe('ISO date — ads last seen on/before'),
+    per_page: z.number().int().min(1).max(50).optional(),
+  },
+  async (args) => run(() => apiGet('/ads', args)),
+);
+
+server.tool(
+  'ad_get',
+  'Fetch one ad by id: full copy (headline/body/cta), advertiser, media list and funnel summary.',
+  { id: z.string().describe('Ad id (uuid)') },
+  async ({ id }) => run(() => apiGet(`/ads/${encodeURIComponent(id)}`)),
+);
+
+server.tool(
+  'ad_media',
+  'Presigned image/video URLs for an ad (30-minute TTL). Use to view or download the creatives.',
+  { id: z.string().describe('Ad id (uuid)') },
+  async ({ id }) => run(() => apiGet(`/ads/${encodeURIComponent(id)}/media`)),
+);
+
+server.tool(
+  'ad_funnel',
+  'The mapped landing → destination funnel for an ad (gateway, steps with URLs, destination).',
+  { id: z.string().describe('Ad id (uuid)') },
+  async ({ id }) => run(() => apiGet(`/ads/${encodeURIComponent(id)}/funnel`)),
+);
+
+server.tool(
+  'targets_list',
+  'List the competitor targets (advertiser domains) tracked in your account, with ad counts.',
+  {},
+  async () => run(() => apiGet('/targets')),
+);
+
+server.tool(
+  'whoami',
+  'Verify the API key works and show its abilities. Use for setup/debugging.',
+  {},
+  async () => run(() => apiGet('/me')),
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[pubweb-ads-mcp] ready → ${API_URL}/api/v1`);