@ppcassist/amazon-ads-mcp 1.0.0

package/README.md

@@ -0,0 +1,67 @@
+# @ppcassist/amazon-ads-mcp
+
+Local MCP proxy for the Amazon Ads API. Sits between Claude Desktop and Amazon's official Advertising MCP server, handling OAuth authentication and token refresh automatically.
+
+## How it works
+
+1. On startup, exchanges your refresh token for an access token via Amazon OAuth
+2. Auto-refreshes the token every 50 minutes
+3. Proxies all MCP requests from Claude Desktop to the Amazon Ads MCP server
+4. Injects required authentication headers on every request
+5. Streams SSE responses back to Claude without buffering
+
+## Prerequisites
+
+You need Amazon Ads API credentials:
+
+- **CLIENT_ID** - Your Amazon Ads API client ID (Login with Amazon)
+- **CLIENT_SECRET** - Your Amazon Ads API client secret
+- **REFRESH_TOKEN** - OAuth refresh token for your Amazon Ads account
+- **PROFILE_ID** - Your Amazon Advertising profile ID
+- **REGION** - One of `EU`, `NA`, or `FE`
+
+## Setup with Claude Desktop
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "amazon-ads": {
+      "command": "npx",
+      "args": ["-y", "@ppcassist/amazon-ads-mcp"],
+      "env": {
+        "CLIENT_ID": "amzn1.application-oa2-client.xxxxx",
+        "CLIENT_SECRET": "your-client-secret",
+        "REFRESH_TOKEN": "Atzr|your-refresh-token",
+        "PROFILE_ID": "your-profile-id",
+        "REGION": "EU"
+      }
+    }
+  }
+}
+```
+
+## Supported regions
+
+| Region | Endpoint |
+|--------|----------|
+| NA | `https://advertising-ai.amazon.com/mcp` |
+| EU | `https://advertising-ai-eu.amazon.com/mcp` |
+| FE | `https://advertising-ai-fe.amazon.com/mcp` |
+
+## How it proxies
+
+All MCP JSON-RPC messages (`initialize`, `tools/list`, `tools/call`, etc.) are forwarded to Amazon's MCP server with these headers injected:
+
+- `Authorization: Bearer <access_token>`
+- `Amazon-Ads-ClientId: <CLIENT_ID>`
+- `Amazon-Advertising-API-Scope: <PROFILE_ID>`
+- `Amazon-Ads-AI-Account-Selection-Mode: FIXED`
+- `Accept: application/json, text/event-stream`
+
+Responses (including SSE streams) are forwarded back to Claude as-is.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+const { TokenManager } = require("./lib/auth");
+const { McpProxy } = require("./lib/proxy");
+
+const log = (msg) => process.stderr.write(`[amazon-ads-mcp] ${msg}\n`);
+
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    log(`ERROR: Missing required environment variable: ${name}`);
+    process.exit(1);
+  }
+  return value;
+}
+
+async function main() {
+  const clientId = requireEnv("CLIENT_ID");
+  const clientSecret = requireEnv("CLIENT_SECRET");
+  const refreshToken = requireEnv("REFRESH_TOKEN");
+  const profileId = requireEnv("PROFILE_ID");
+  const region = requireEnv("REGION");
+
+  // Initialize OAuth token manager
+  const tokenManager = new TokenManager({ clientId, clientSecret, refreshToken });
+  try {
+    await tokenManager.init();
+  } catch (err) {
+    log(`Failed to obtain access token: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Initialize MCP proxy
+  const proxy = new McpProxy({ tokenManager, clientId, profileId, region });
+
+  log(`Started (region=${region})`);
+
+  // Read JSON-RPC messages from stdin (newline-delimited)
+  let buffer = "";
+
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+
+    // Process all complete lines in the buffer
+    let newlineIdx;
+    while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newlineIdx).trim();
+      buffer = buffer.slice(newlineIdx + 1);
+
+      if (!line) continue;
+
+      let request;
+      try {
+        request = JSON.parse(line);
+      } catch (err) {
+        log(`Failed to parse JSON-RPC message: ${err.message}`);
+        continue;
+      }
+
+      handleRequest(proxy, request);
+    }
+  });
+
+  process.stdin.on("end", () => {
+    log("stdin closed, shutting down");
+    tokenManager.destroy();
+    process.exit(0);
+  });
+}
+
+async function handleRequest(proxy, request) {
+  const { id, method } = request;
+
+  try {
+    const result = await proxy.forward(request);
+
+    if (result.type === "stream") {
+      // SSE stream: pipe each event line directly to stdout
+      result.stream.on("data", (chunk) => {
+        process.stdout.write(chunk);
+      });
+
+      result.stream.on("end", () => {
+        // SSE streams end naturally; nothing extra needed
+      });
+
+      result.stream.on("error", (err) => {
+        log(`SSE stream error (id=${id}): ${err.message}`);
+        writeJsonRpc({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32000, message: `Stream error: ${err.message}` },
+        });
+      });
+    } else if (result.type === "json") {
+      writeJsonRpc(result.data);
+    } else {
+      // Raw / unexpected response
+      log(`Unexpected response (status=${result.statusCode}): ${result.data}`);
+      writeJsonRpc({
+        jsonrpc: "2.0",
+        id,
+        error: {
+          code: -32000,
+          message: `Upstream error (HTTP ${result.statusCode})`,
+        },
+      });
+    }
+  } catch (err) {
+    log(`Proxy error (method=${method}, id=${id}): ${err.message}`);
+    writeJsonRpc({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32000, message: err.message },
+    });
+  }
+}
+
+function writeJsonRpc(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+main().catch((err) => {
+  log(`Fatal: ${err.message}`);
+  process.exit(1);
+});

package/lib/auth.js

@@ -0,0 +1,85 @@
+const https = require("https");
+
+const TOKEN_URL = "https://api.amazon.com/auth/o2/token";
+const REFRESH_INTERVAL_MS = 50 * 60 * 1000; // 50 minutes
+
+class TokenManager {
+  constructor({ clientId, clientSecret, refreshToken }) {
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+    this.refreshToken = refreshToken;
+    this.accessToken = null;
+    this.timer = null;
+  }
+
+  async init() {
+    await this.refresh();
+    this.timer = setInterval(() => this.refresh(), REFRESH_INTERVAL_MS);
+    this.timer.unref(); // don't keep process alive just for refresh
+  }
+
+  async refresh() {
+    const body = new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      refresh_token: this.refreshToken,
+    }).toString();
+
+    const data = await this._post(TOKEN_URL, body);
+
+    if (data.error) {
+      throw new Error(`OAuth error: ${data.error} - ${data.error_description || ""}`);
+    }
+
+    this.accessToken = data.access_token;
+    process.stderr.write(`[auth] Token refreshed successfully\n`);
+  }
+
+  getToken() {
+    if (!this.accessToken) {
+      throw new Error("Access token not available - call init() first");
+    }
+    return this.accessToken;
+  }
+
+  destroy() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  _post(urlStr, body) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(urlStr);
+      const options = {
+        hostname: url.hostname,
+        path: url.pathname,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          "Content-Length": Buffer.byteLength(body),
+        },
+      };
+
+      const req = https.request(options, (res) => {
+        let chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => {
+          try {
+            resolve(JSON.parse(Buffer.concat(chunks).toString()));
+          } catch (e) {
+            reject(new Error(`Failed to parse token response: ${e.message}`));
+          }
+        });
+      });
+
+      req.on("error", reject);
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+module.exports = { TokenManager };

package/lib/proxy.js

@@ -0,0 +1,70 @@
+const https = require("https");
+
+const ENDPOINTS = {
+  EU: "https://advertising-ai-eu.amazon.com/mcp",
+  NA: "https://advertising-ai.amazon.com/mcp",
+  FE: "https://advertising-ai-fe.amazon.com/mcp",
+};
+
+class McpProxy {
+  constructor({ tokenManager, clientId, profileId, region }) {
+    this.tokenManager = tokenManager;
+    this.clientId = clientId;
+    this.profileId = profileId;
+
+    const endpoint = ENDPOINTS[region.toUpperCase()];
+    if (!endpoint) {
+      throw new Error(`Invalid REGION "${region}". Must be EU, NA, or FE.`);
+    }
+    this.endpoint = new URL(endpoint);
+  }
+
+  async forward(jsonRpcRequest) {
+    const body = JSON.stringify(jsonRpcRequest);
+    const token = this.tokenManager.getToken();
+
+    const options = {
+      hostname: this.endpoint.hostname,
+      path: this.endpoint.pathname,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+        Authorization: `Bearer ${token}`,
+        "Amazon-Ads-ClientId": this.clientId,
+        "Amazon-Advertising-API-Scope": this.profileId,
+        "Amazon-Ads-AI-Account-Selection-Mode": "FIXED",
+        Accept: "application/json, text/event-stream",
+      },
+    };
+
+    return new Promise((resolve, reject) => {
+      const req = https.request(options, (res) => {
+        const contentType = res.headers["content-type"] || "";
+        const isSSE = contentType.includes("text/event-stream");
+
+        if (isSSE) {
+          resolve({ type: "stream", stream: res });
+        } else {
+          let chunks = [];
+          res.on("data", (chunk) => chunks.push(chunk));
+          res.on("end", () => {
+            const raw = Buffer.concat(chunks).toString();
+            try {
+              resolve({ type: "json", data: JSON.parse(raw) });
+            } catch {
+              // Return raw text if not valid JSON (error pages, etc.)
+              resolve({ type: "raw", data: raw, statusCode: res.statusCode });
+            }
+          });
+        }
+      });
+
+      req.on("error", reject);
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+module.exports = { McpProxy };

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ppcassist/amazon-ads-mcp",
+  "version": "1.0.0",
+  "description": "Local MCP proxy for Amazon Ads API - authenticates and forwards requests to Amazon's official MCP server",
+  "main": "index.js",
+  "bin": {
+    "amazon-ads-mcp": "./index.js"
+  },
+  "keywords": [
+    "amazon-ads",
+    "mcp",
+    "model-context-protocol",
+    "ppc",
+    "advertising",
+    "proxy"
+  ],
+  "author": "PPCAssist",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "README.md"
+  ]
+}