pcade-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PPC Ad Editor
+
+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,255 @@
+# pcade-mcp
+
+Create professional Google, Meta & LinkedIn ad previews from any AI assistant.
+
+`pcade-mcp` is an [MCP](https://modelcontextprotocol.io) server for
+[PPC Ad Editor](https://www.ppcadeditor.com). It connects Claude, Cursor,
+Windsurf, and other MCP clients to the PPC Ad Editor preview engine.
+
+**Works out of the box — no account needed.** Guest mode gives you 3 previews
+per day. Add an API key for higher limits.
+
+---
+
+## Quick Setup (guest mode — no account needed)
+
+### Claude Desktop
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pcade": {
+      "command": "npx",
+      "args": ["-y", "pcade-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop (Windows)
+
+```json
+{
+  "mcpServers": {
+    "pcade": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "pcade-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "pcade": {
+      "command": "npx",
+      "args": ["-y", "pcade-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pcade": {
+      "command": "npx",
+      "args": ["-y", "pcade-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add pcade -- npx -y pcade-mcp
+```
+
+### Any client (via add-mcp)
+
+```bash
+npx add-mcp pcade-mcp
+```
+
+After adding the config, **fully quit and reopen your editor**. MCP servers
+load at startup.
+
+---
+
+## Authenticated Setup (higher limits)
+
+Get an API key at <https://studio.ppcadeditor.com/dashboard/settings>, then
+pass it via the `PCADE_API_KEY` environment variable.
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "pcade": {
+      "command": "npx",
+      "args": ["-y", "pcade-mcp"],
+      "env": { "PCADE_API_KEY": "pcade_live_xxx" }
+    }
+  }
+}
+```
+
+### Claude Desktop (Windows)
+
+```json
+{
+  "mcpServers": {
+    "pcade": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "pcade-mcp"],
+      "env": { "PCADE_API_KEY": "pcade_live_xxx" }
+    }
+  }
+}
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "pcade": {
+      "command": "npx",
+      "args": ["-y", "pcade-mcp"],
+      "env": { "PCADE_API_KEY": "pcade_live_xxx" }
+    }
+  }
+}
+```
+
+### Windsurf
+
+```json
+{
+  "mcpServers": {
+    "pcade": {
+      "command": "npx",
+      "args": ["-y", "pcade-mcp"],
+      "env": { "PCADE_API_KEY": "pcade_live_xxx" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add pcade --env PCADE_API_KEY=pcade_live_xxx -- npx -y pcade-mcp
+```
+
+### Any client (via add-mcp)
+
+```bash
+npx add-mcp pcade-mcp --env PCADE_API_KEY=pcade_live_xxx
+```
+
+---
+
+## Faster startup (optional)
+
+`npx` downloads the package on first use. For faster startup on repeated
+launches, install globally:
+
+```bash
+npm i -g pcade-mcp
+```
+
+Then use `pcade-mcp` directly in your config instead of `npx -y pcade-mcp`.
+
+---
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `get_ad_formats` | Returns ad format specs — field counts, character limits, supported media. Call this first. |
+| `create_and_share` | Creates ad previews from structured content and returns a shareable link. |
+
+### Example conversation
+
+> **You:** Create Google Search ads for a Portland bakery at portlandsourdough.com
+>
+> **AI:** _(calls `get_ad_formats` to learn RSA constraints, then `create_and_share`)_
+>
+> Here's your ad preview: https://studio.ppcadeditor.com/shared/abc123
+> You can edit it in the dashboard: https://studio.ppcadeditor.com/dashboard/...
+
+---
+
+## Rate limits
+
+| Mode | Previews | Share link expiry |
+|------|----------|-------------------|
+| Guest (no API key) | 3 per day | 24 hours |
+| Free account | 20 total | 7 days |
+| Paid account | Plan-based | Permanent |
+
+---
+
+## CLI options
+
+```
+--api-key <key>     API key (prefer PCADE_API_KEY env var)
+--endpoint <url>    Override server URL
+--debug             Log requests/responses to stderr
+--help              Show help
+--version           Show version
+```
+
+---
+
+## Troubleshooting
+
+**Tools not showing up?**
+Fully quit and reopen your editor (not just close the tab). MCP servers only
+load at startup.
+
+**Claude Desktop: "npx: command not found"?**
+Install [Node.js](https://nodejs.org) (v18.13+), then fully quit and reopen
+Claude Desktop.
+
+**Timeout or WAF errors?**
+The server may be temporarily behind a security checkpoint. Wait a minute and
+retry. If persistent, run with `--debug` for diagnostics.
+
+**Slow startup?**
+`npx` downloads on first run. Install globally with `npm i -g pcade-mcp` for
+instant startup.
+
+---
+
+## Security
+
+- **Use env vars for API keys** — the `PCADE_API_KEY` environment variable is
+  not visible in process listings, unlike CLI flags.
+- **Zero dependencies** — no supply chain risk from third-party packages.
+- **Credentials stay safe** — API keys are never sent to custom endpoints
+  (only to the default PPC Ad Editor server).
+- **No data stored locally** — the proxy is stateless; nothing is written to
+  disk.
+
+---
+
+## Links
+
+- [PPC Ad Editor](https://www.ppcadeditor.com)
+- [Get an API key](https://studio.ppcadeditor.com/dashboard/settings)
+- [MCP Protocol](https://modelcontextprotocol.io)

package/bin/cli.mjs

@@ -0,0 +1,441 @@
+#!/usr/bin/env node
+import { createInterface } from "readline";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_ENDPOINT = "https://studio.ppcadeditor.com/api/mcp";
+const FETCH_TIMEOUT_MS = 15_000;
+const MAX_LINE_BYTES = 262_144; // 256 KB — server caps at 32 KB anyway
+const MAX_CONCURRENT = 5;
+const SECRET_PATTERN = /pcade_(live|test)_[A-Za-z0-9_\-+/=]+/g;
+
+// ---------------------------------------------------------------------------
+// Argument parsing (zero-dep)
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+
+function flag(name) {
+  return args.includes(`--${name}`);
+}
+
+function flagValue(name) {
+  const idx = args.indexOf(`--${name}`);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+const showHelp = flag("help") || flag("h");
+const showVersion = flag("version") || flag("v");
+const debug = flag("debug");
+const cliApiKey = flagValue("api-key");
+const cliEndpoint = flagValue("endpoint");
+
+// ---------------------------------------------------------------------------
+// --help / --version → print and exit
+// ---------------------------------------------------------------------------
+
+if (showVersion) {
+  process.stdout.write(`${version}\n`);
+  process.exit(0);
+}
+
+if (showHelp) {
+  process.stdout.write(`pcade-mcp v${version} — MCP server for PPC Ad Editor
+
+Create professional Google, Meta & LinkedIn ad previews from any AI assistant.
+
+Usage:
+  npx pcade-mcp [options]
+
+Options:
+  --api-key <key>     API key (or set PCADE_API_KEY env var — recommended)
+  --endpoint <url>    Override server URL (default: ${DEFAULT_ENDPOINT})
+  --debug             Log all requests/responses to stderr
+  --help              Show this help message
+  --version           Show version number
+
+Setup — Claude Desktop (~/.claude/claude_desktop_config.json):
+  {
+    "mcpServers": {
+      "pcade": {
+        "command": "npx",
+        "args": ["-y", "pcade-mcp"],
+        "env": { "PCADE_API_KEY": "pcade_live_xxx" }
+      }
+    }
+  }
+
+Setup — Claude Desktop on Windows:
+  {
+    "mcpServers": {
+      "pcade": {
+        "command": "cmd",
+        "args": ["/c", "npx", "-y", "pcade-mcp"],
+        "env": { "PCADE_API_KEY": "pcade_live_xxx" }
+      }
+    }
+  }
+
+Setup — Cursor (.cursor/mcp.json):
+  {
+    "mcpServers": {
+      "pcade": {
+        "command": "npx",
+        "args": ["-y", "pcade-mcp"],
+        "env": { "PCADE_API_KEY": "pcade_live_xxx" }
+      }
+    }
+  }
+
+Setup — Windsurf (~/.codeium/windsurf/mcp_config.json):
+  {
+    "mcpServers": {
+      "pcade": {
+        "command": "npx",
+        "args": ["-y", "pcade-mcp"],
+        "env": { "PCADE_API_KEY": "pcade_live_xxx" }
+      }
+    }
+  }
+
+Setup — Claude Code:
+  claude mcp add pcade -- npx -y pcade-mcp
+  claude mcp add pcade --env PCADE_API_KEY=pcade_live_xxx -- npx -y pcade-mcp
+
+Setup — Universal (via add-mcp, any client):
+  npx add-mcp pcade-mcp
+  npx add-mcp pcade-mcp --env PCADE_API_KEY=pcade_live_xxx
+
+Guest mode (no API key — 3 previews/day):
+  {
+    "mcpServers": {
+      "pcade": {
+        "command": "npx",
+        "args": ["-y", "pcade-mcp"]
+      }
+    }
+  }
+
+Get an API key: https://studio.ppcadeditor.com/dashboard/settings
+`);
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Resolve auth + endpoint
+// ---------------------------------------------------------------------------
+
+const apiKey =
+  cliApiKey ||
+  process.env.PCADE_API_KEY ||
+  process.env.MCP_PROXY_API_KEY ||
+  null;
+
+const endpoint =
+  cliEndpoint ||
+  process.env.MCP_PROXY_URL ||
+  DEFAULT_ENDPOINT;
+
+const isCustomEndpoint = endpoint !== DEFAULT_ENDPOINT;
+
+// S1: Strip auth on custom endpoints to prevent credential exfiltration
+const sendAuth = apiKey && !isCustomEndpoint;
+
+// Vercel WAF bypass (internal use only — not documented publicly)
+const vercelBypass = process.env.VERCEL_PROTECTION_BYPASS || null;
+
+// ---------------------------------------------------------------------------
+// Logging helpers
+// ---------------------------------------------------------------------------
+
+function redact(str) {
+  return String(str).replace(SECRET_PATTERN, (m) => m.slice(0, 11) + "***REDACTED***");
+}
+
+function log(msg) {
+  process.stderr.write(`[pcade-mcp] ${redact(msg)}\n`);
+}
+
+function debugLog(msg) {
+  if (debug) log(`[debug] ${msg}`);
+}
+
+// ---------------------------------------------------------------------------
+// Startup banner
+// ---------------------------------------------------------------------------
+
+log(`v${version}`);
+log(`Endpoint: ${endpoint}`);
+
+if (sendAuth) {
+  log(`Auth: API key (${apiKey.slice(0, 11)}...)`);
+} else if (apiKey && isCustomEndpoint) {
+  log("Auth: withheld (custom endpoint)");
+} else {
+  log("Running in guest mode (3 previews/day). Set PCADE_API_KEY for higher limits.");
+}
+
+// S5: Warn when API key passed via CLI flag (visible in process listings)
+if (cliApiKey) {
+  log("WARNING: API key passed via --api-key flag is visible in process listings. Use PCADE_API_KEY env var instead.");
+}
+
+// S1: Warn if custom endpoint is used with an API key
+if (apiKey && isCustomEndpoint) {
+  log(`WARNING: Custom endpoint detected. API key will NOT be sent to ${endpoint}. Use the default endpoint or set PCADE_API_KEY on the target server.`);
+}
+
+log("Ready — waiting for MCP client requests on stdin");
+
+// ---------------------------------------------------------------------------
+// Session tracking
+// ---------------------------------------------------------------------------
+
+let mcpSessionId = null;
+
+// ---------------------------------------------------------------------------
+// Concurrency limiter
+// ---------------------------------------------------------------------------
+
+let inFlight = 0;
+const waiting = [];
+
+function acquireSlot() {
+  if (inFlight < MAX_CONCURRENT) {
+    inFlight++;
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => waiting.push(resolve));
+}
+
+function releaseSlot() {
+  inFlight--;
+  if (waiting.length > 0) {
+    inFlight++;
+    waiting.shift()();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC helpers
+// ---------------------------------------------------------------------------
+
+function jsonRpcError(id, code, message, data) {
+  const err = { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+  if (data !== undefined) err.error.data = data;
+  return err;
+}
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Core proxy loop
+// ---------------------------------------------------------------------------
+
+const rl = createInterface({ input: process.stdin });
+
+rl.on("line", async (line) => {
+  // S3: Reject oversized input
+  if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
+    log(`Rejected oversized input (${Buffer.byteLength(line)} bytes, max ${MAX_LINE_BYTES})`);
+    send(jsonRpcError(null, -32600, `Request too large (max ${MAX_LINE_BYTES / 1024}KB)`));
+    return;
+  }
+
+  let request;
+  try {
+    request = JSON.parse(line);
+  } catch {
+    log(`Invalid JSON received`);
+    debugLog(`Parse error on: ${line.slice(0, 200)}`);
+    return;
+  }
+
+  // Skip notifications (no id = no response expected)
+  if (
+    request.method?.startsWith("notifications/") ||
+    request.id === undefined ||
+    request.id === null
+  ) {
+    debugLog(`Skipping notification: ${request.method}`);
+    return;
+  }
+
+  debugLog(`→ ${request.method} (id: ${request.id})`);
+
+  await acquireSlot();
+
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+
+  const headers = {
+    "Content-Type": "application/json",
+  };
+
+  if (sendAuth) {
+    headers["Authorization"] = `Bearer ${apiKey}`;
+  }
+
+  if (vercelBypass) {
+    headers["x-vercel-protection-bypass"] = vercelBypass;
+  }
+
+  if (mcpSessionId) {
+    headers["Mcp-Session-Id"] = mcpSessionId;
+  }
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(request),
+      signal: ac.signal,
+    });
+
+    clearTimeout(timer);
+
+    if (response.status === 204) {
+      debugLog(`← 204 No Content`);
+      return;
+    }
+
+    const contentType = response.headers.get("content-type") || "";
+
+    // WAF / non-JSON detection
+    if (!contentType.includes("application/json")) {
+      const snippet = (await response.text()).slice(0, 200);
+      const isWaf =
+        response.status === 429 ||
+        response.status === 403 ||
+        snippet.includes("Vercel Security");
+
+      log(
+        `Non-JSON response ${response.status} (${contentType}): ${snippet.slice(0, 100)}`,
+      );
+
+      send(
+        jsonRpcError(
+          request.id,
+          -32603,
+          isWaf
+            ? `WAF blocked (HTTP ${response.status}). The Vercel security checkpoint is active. Wait a moment and retry.`
+            : `Upstream returned HTTP ${response.status} with non-JSON body`,
+          { http_status: response.status, content_type: contentType },
+        ),
+      );
+      return;
+    }
+
+    // HTTP error with JSON body
+    if (response.status >= 400) {
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        body = null;
+      }
+      log(`HTTP ${response.status}: ${redact(JSON.stringify(body)).slice(0, 200)}`);
+      send(
+        jsonRpcError(
+          request.id,
+          -32603,
+          `Upstream HTTP ${response.status}: ${body?.message || body?.error || "Unknown error"}`,
+          { http_status: response.status, upstream: body },
+        ),
+      );
+      return;
+    }
+
+    // Track session
+    const newSessionId = response.headers.get("mcp-session-id");
+    if (newSessionId) {
+      mcpSessionId = newSessionId;
+      debugLog(`Session: ${mcpSessionId}`);
+    }
+
+    const result = await response.json();
+
+    // Fix null id from server when client sent a real id
+    if (
+      result.id === null &&
+      request.id !== undefined &&
+      request.id !== null
+    ) {
+      result.id = request.id;
+    }
+
+    debugLog(`← ${request.method} (${response.status})`);
+
+    // Surface guest rate limit hits to stderr for visibility
+    if (result?.result?.isError && result?.result?.content?.[0]?.text) {
+      const text = result.result.content[0].text;
+      if (text.includes("guest_limit_reached") || text.includes("3 previews")) {
+        log("Guest limit reached (3/3 today). Get an API key: https://studio.ppcadeditor.com/dashboard/settings");
+      }
+    }
+
+    send(result);
+  } catch (err) {
+    clearTimeout(timer);
+    const isTimeout = err.name === "AbortError";
+    log(
+      `${isTimeout ? "Timeout" : "Fetch error"}: ${redact(String(err))}`,
+    );
+    send(
+      jsonRpcError(
+        request.id,
+        isTimeout ? -32001 : -32603,
+        isTimeout
+          ? `Request timed out after ${FETCH_TIMEOUT_MS / 1000}s — endpoint may be down or WAF is blocking`
+          : `Network error: ${err.message}`,
+        { error_type: isTimeout ? "timeout" : "network" },
+      ),
+    );
+  } finally {
+    releaseSlot();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Graceful shutdown
+// ---------------------------------------------------------------------------
+
+let stdinClosed = false;
+
+function exitWhenIdle() {
+  if (inFlight === 0) {
+    process.exit(0);
+  }
+  // In-flight requests pending — they will call releaseSlot → re-check
+}
+
+const origRelease = releaseSlot;
+releaseSlot = function () {
+  origRelease();
+  if (stdinClosed) exitWhenIdle();
+};
+
+rl.on("close", () => {
+  stdinClosed = true;
+  debugLog("stdin closed — draining in-flight requests");
+  exitWhenIdle();
+});
+
+process.on("SIGINT", () => {
+  debugLog("SIGINT received — exiting");
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  debugLog("SIGTERM received — exiting");
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "pcade-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for PPC Ad Editor — create Google, Meta & LinkedIn ad previews from AI assistants",
+  "bin": {
+    "pcade-mcp": "bin/cli.mjs"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.13"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ppc",
+    "google-ads",
+    "meta-ads",
+    "linkedin-ads",
+    "ad-preview",
+    "claude",
+    "cursor",
+    "ai-tools"
+  ],
+  "license": "MIT",
+  "homepage": "https://www.ppcadeditor.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ppcadeditor/pcade2-sip.git",
+    "directory": "packages/mcp-proxy"
+  }
+}