@channel47/linkedin-ads-mcp 0.1.0

package/server/utils/mutate-operations.js

@@ -0,0 +1,211 @@
+import { getApiVersion, RESTLI_PROTOCOL_VERSION } from '../http.js';
+import { encodeRestliValue } from './restli.js';
+import { fromEntityUrn, toEntityUrn, validateArray } from './validation.js';
+
+/**
+ * Supported mutate entity identifiers.
+ */
+export const SUPPORTED_MUTATE_ENTITIES = ['campaign', 'campaign_group', 'creative'];
+/**
+ * Supported mutate action identifiers.
+ */
+export const SUPPORTED_MUTATE_ACTIONS = ['create', 'update', 'pause', 'enable', 'archive'];
+
+/**
+ * Default status applied to created entities. LinkedIn documents DRAFT as the
+ * safe non-serving state for newly created campaigns, campaign groups, and
+ * creatives; pass an explicit status (intendedStatus for creatives) to override.
+ */
+export const DEFAULT_CREATE_STATUS = 'DRAFT';
+
+const ENTITY_COLLECTIONS = {
+  campaign: 'adCampaigns',
+  campaign_group: 'adCampaignGroups',
+  creative: 'creatives'
+};
+
+const STATUS_FIELD_BY_ENTITY = {
+  campaign: 'status',
+  campaign_group: 'status',
+  creative: 'intendedStatus'
+};
+
+const STATUS_BY_ACTION = {
+  pause: 'PAUSED',
+  enable: 'ACTIVE',
+  archive: 'ARCHIVED'
+};
+
+function validateOperationShape(op, index) {
+  if (!op || typeof op !== 'object' || Array.isArray(op)) {
+    return { index, message: 'Operation must be an object' };
+  }
+
+  if (!op.entity) {
+    return { index, message: 'Missing required field: entity' };
+  }
+
+  if (!SUPPORTED_MUTATE_ENTITIES.includes(op.entity)) {
+    return {
+      index,
+      message: `Unsupported entity: ${op.entity}. Supported: ${SUPPORTED_MUTATE_ENTITIES.join(', ')}`
+    };
+  }
+
+  if (!op.action) {
+    return { index, message: 'Missing required field: action' };
+  }
+
+  if (!SUPPORTED_MUTATE_ACTIONS.includes(op.action)) {
+    return {
+      index,
+      message: `Unsupported action: ${op.action}. Supported: ${SUPPORTED_MUTATE_ACTIONS.join(', ')}`
+    };
+  }
+
+  if ((op.action === 'create' || op.action === 'update') && (!op.params || typeof op.params !== 'object' || Array.isArray(op.params))) {
+    return {
+      index,
+      message: `${op.action} requires params object`
+    };
+  }
+
+  if (op.action !== 'create' && !op.id) {
+    return {
+      index,
+      message: `${op.action} requires id`
+    };
+  }
+
+  if (op.entity === 'creative' && op.action === 'create' && !op.params?.campaign) {
+    return {
+      index,
+      message: 'creative create requires params.campaign (campaign ID or urn:li:sponsoredCampaign URN)'
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Validate mutate operation array shape and action/entity compatibility.
+ * @param {unknown} operations
+ * @returns {Array<{ index: number, message: string }>}
+ */
+export function validateOperations(operations) {
+  validateArray(operations, 'operations');
+
+  const errors = [];
+  for (let index = 0; index < operations.length; index += 1) {
+    const issue = validateOperationShape(operations[index], index);
+    if (issue) {
+      errors.push(issue);
+    }
+  }
+
+  return errors;
+}
+
+// Creatives are keyed by URN in resource paths and must be percent-encoded;
+// campaigns and campaign groups are keyed by their numeric ID.
+function encodeEntityKey(entity, id) {
+  if (entity === 'creative') {
+    return encodeRestliValue(toEntityUrn('creative', id));
+  }
+
+  return encodeRestliValue(fromEntityUrn(id));
+}
+
+function buildCreateBody(operation, accountId) {
+  const statusField = STATUS_FIELD_BY_ENTITY[operation.entity];
+  const body = {
+    [statusField]: DEFAULT_CREATE_STATUS,
+    ...operation.params
+  };
+
+  if (operation.entity === 'creative') {
+    body.campaign = toEntityUrn('campaign', operation.params.campaign);
+    return body;
+  }
+
+  if (!body.account) {
+    body.account = toEntityUrn('account', accountId);
+  }
+
+  return body;
+}
+
+/**
+ * Build a LinkedIn Marketing API request from a single mutate operation.
+ * Creates POST to the entity collection under the account; update and status
+ * changes POST to the entity item with X-RestLi-Method: PARTIAL_UPDATE and a
+ * { patch: { $set: {...} } } body.
+ * @param {{ entity: string, action: string, id?: string, params?: Record<string, unknown> }} operation
+ * @param {string} accountId
+ * @returns {{ method: string, path: string, headers: Record<string, string>, body: Record<string, unknown> }}
+ */
+export function buildApiRequest(operation, accountId) {
+  const collection = ENTITY_COLLECTIONS[operation.entity];
+
+  if (operation.action === 'create') {
+    return {
+      method: 'POST',
+      path: `/adAccounts/${accountId}/${collection}`,
+      headers: {},
+      body: buildCreateBody(operation, accountId)
+    };
+  }
+
+  const statusField = STATUS_FIELD_BY_ENTITY[operation.entity];
+  const actionStatus = STATUS_BY_ACTION[operation.action];
+  const setPayload = actionStatus
+    ? { [statusField]: actionStatus, ...(operation.params || {}) }
+    : { ...(operation.params || {}) };
+
+  return {
+    method: 'POST',
+    path: `/adAccounts/${accountId}/${collection}/${encodeEntityKey(operation.entity, operation.id)}`,
+    headers: {
+      'X-RestLi-Method': 'PARTIAL_UPDATE'
+    },
+    body: {
+      patch: {
+        $set: setPayload
+      }
+    }
+  };
+}
+
+/**
+ * Build a human-readable preview of the exact API requests derived from
+ * operations, including the versioned headers that would be sent
+ * (Authorization is omitted).
+ * @param {Array<{ entity: string, action: string, id?: string, params?: Record<string, unknown> }>} operations
+ * @param {string} accountId
+ * @returns {{ requests: Array<Record<string, unknown>> }}
+ */
+export function buildRequestPreview(operations, accountId) {
+  const sharedHeaders = {
+    'LinkedIn-Version': getApiVersion(),
+    'X-Restli-Protocol-Version': RESTLI_PROTOCOL_VERSION,
+    'Content-Type': 'application/json'
+  };
+
+  return {
+    requests: operations.map((operation, index) => {
+      const request = buildApiRequest(operation, accountId);
+      return {
+        index,
+        entity: operation.entity,
+        action: operation.action,
+        method: request.method,
+        path: request.path,
+        headers: {
+          ...sharedHeaders,
+          ...request.headers
+        },
+        body: request.body
+      };
+    })
+  };
+}

package/server/utils/response-format.js

@@ -0,0 +1,63 @@
+let SdkMcpError = null;
+let SdkErrorCode = null;
+
+try {
+  const sdkTypes = await import('@modelcontextprotocol/sdk/types.js');
+  SdkMcpError = sdkTypes.McpError;
+  SdkErrorCode = sdkTypes.ErrorCode;
+} catch {
+  // SDK may be absent in minimal test environments.
+}
+
+/**
+ * Format a successful tool result payload in MCP text content structure.
+ * @param {{ summary: string, data: any, metadata?: Record<string, unknown> }} payload
+ * @returns {import('@modelcontextprotocol/sdk/types.js').CallToolResult}
+ */
+export function formatSuccess({ summary, data, metadata = {} }) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        success: true,
+        summary,
+        data,
+        metadata: {
+          rowCount: Array.isArray(data) ? data.length : undefined,
+          warnings: [],
+          ...metadata
+        }
+      }, null, 2)
+    }]
+  };
+}
+
+function createMcpStyleError(code, message) {
+  if (SdkMcpError && SdkErrorCode && SdkErrorCode[code]) {
+    return new SdkMcpError(SdkErrorCode[code], message);
+  }
+
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * Convert thrown errors into MCP-compatible typed errors.
+ * @param {unknown} error
+ * @throws {Error}
+ */
+export function formatError(error) {
+  const message = error?.message || String(error) || 'Unknown error';
+  const explicitCode = error?.mcpCode === 'InvalidParams' || error?.code === 'InvalidParams'
+    ? 'InvalidParams'
+    : error?.mcpCode === 'InternalError' || error?.code === 'InternalError'
+      ? 'InternalError'
+      : null;
+
+  if (explicitCode) {
+    throw createMcpStyleError(explicitCode, message);
+  }
+
+  throw createMcpStyleError('InternalError', message);
+}

package/server/utils/restli.js

@@ -0,0 +1,153 @@
+import { invalidParamsError } from './errors.js';
+
+class RestliRaw {
+  constructor(value) {
+    this.value = String(value);
+    this.__restliRaw = true;
+  }
+}
+
+/**
+ * Wrap a pre-built Rest.li expression so buildQueryString inserts it verbatim.
+ * Use for structured params like dateRange/search whose parens, colons, and
+ * commas must stay literal in the query string.
+ * @param {string} value
+ * @returns {RestliRaw}
+ */
+export function rawParam(value) {
+  return new RestliRaw(value);
+}
+
+/**
+ * Check whether a value was produced by rawParam(). Duck-typed rather than
+ * instanceof so values survive module re-imports (e.g. cache-busted test loads).
+ */
+export function isRawParam(value) {
+  return Boolean(value)
+    && typeof value === 'object'
+    && value.__restliRaw === true
+    && typeof value.value === 'string';
+}
+
+/**
+ * Percent-encode a single Rest.li value. Extends encodeURIComponent to also
+ * encode characters Rest.li treats as structural but JS leaves bare: ! ' ( ) *
+ * URNs become e.g. urn%3Ali%3AsponsoredCampaign%3A123.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function encodeRestliValue(value) {
+  return encodeURIComponent(String(value)).replace(
+    /[!'()*]/g,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
+
+/**
+ * Build a Rest.li List(...) expression with each item percent-encoded and
+ * item separators kept as literal commas.
+ * @param {unknown[] | unknown} values
+ * @returns {string}
+ */
+export function restliList(values) {
+  const items = Array.isArray(values) ? values : [values];
+  return `List(${items.map(encodeRestliValue).join(',')})`;
+}
+
+function parseIsoDate(value, label) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(value ?? '').trim());
+  if (!match) {
+    throw invalidParamsError(`Invalid ${label} date format: ${value}. Expected YYYY-MM-DD`);
+  }
+
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+
+  if (month < 1 || month > 12 || day < 1 || day > 31) {
+    throw invalidParamsError(`Invalid ${label} date value: ${value}`);
+  }
+
+  return { year, month, day };
+}
+
+/**
+ * Convert YYYY-MM-DD to a Rest.li date expression: (year:2026,month:6,day:1).
+ * Month and day are emitted without leading zeros as LinkedIn expects.
+ * @param {string} value
+ * @param {string} [label]
+ * @returns {string}
+ */
+export function restliDate(value, label = 'date') {
+  const { year, month, day } = parseIsoDate(value, label);
+  return `(year:${year},month:${month},day:${day})`;
+}
+
+/**
+ * Build the adAnalytics dateRange expression from ISO dates. End is optional
+ * (LinkedIn treats a missing end as "through today").
+ * @param {string} start
+ * @param {string} [end]
+ * @returns {string}
+ */
+export function restliDateRange(start, end) {
+  const parts = [`start:${restliDate(start, 'start')}`];
+  if (end !== undefined && end !== null && end !== '') {
+    parts.push(`end:${restliDate(end, 'end')}`);
+  }
+  return `(${parts.join(',')})`;
+}
+
+/**
+ * Build a finder search expression: (status:(values:List(ACTIVE,PAUSED)),...).
+ * Fields with empty value arrays are omitted; returns null when no clause
+ * remains so callers can skip the param entirely.
+ * @param {Record<string, unknown[]>} filters
+ * @returns {string | null}
+ */
+export function restliSearchFilter(filters = {}) {
+  const clauses = Object.entries(filters)
+    .filter(([, values]) => Array.isArray(values) && values.length > 0)
+    .map(([field, values]) => `${field}:(values:${restliList(values)})`);
+
+  if (clauses.length === 0) {
+    return null;
+  }
+
+  return `(${clauses.join(',')})`;
+}
+
+/**
+ * Build a Rest.li 2.0-safe query string. Never uses URLSearchParams because
+ * that would percent-encode the structural parens/colons/commas of List(...)
+ * and dateRange expressions. Handling by value type:
+ * - rawParam(...) values are inserted verbatim
+ * - arrays become List(...) with percent-encoded items
+ * - everything else is percent-encoded as a single value
+ * Null/undefined/empty-string values are skipped.
+ * @param {Record<string, unknown>} [params]
+ * @returns {string}
+ */
+export function buildQueryString(params = {}) {
+  const parts = [];
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+
+    if (isRawParam(value)) {
+      parts.push(`${key}=${value.value}`);
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      parts.push(`${key}=${restliList(value)}`);
+      continue;
+    }
+
+    parts.push(`${key}=${encodeRestliValue(value)}`);
+  }
+
+  return parts.join('&');
+}

package/server/utils/validation.js

@@ -0,0 +1,104 @@
+import { invalidParamsError } from './errors.js';
+
+/**
+ * Validate that required fields are present on the params object.
+ */
+export function validateRequired(params, fields) {
+  const missing = fields.filter((field) => {
+    const value = params[field];
+    return value === undefined || value === null || value === '';
+  });
+
+  if (missing.length > 0) {
+    throw invalidParamsError(`Missing required parameter${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`);
+  }
+}
+
+/**
+ * Validate an enum value against an allowed set.
+ */
+export function validateEnum(value, allowed, paramName = 'value') {
+  if (!allowed.includes(value)) {
+    throw invalidParamsError(`Invalid ${paramName}: ${value}. Allowed values: ${allowed.join(', ')}`);
+  }
+}
+
+/**
+ * Validate that a value is a non-empty array.
+ */
+export function validateArray(value, paramName = 'value') {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw invalidParamsError(`${paramName} must be a non-empty array`);
+  }
+}
+
+/**
+ * URN prefixes for the sponsored entity types this server works with.
+ */
+export const ENTITY_URN_PREFIXES = {
+  account: 'urn:li:sponsoredAccount:',
+  campaign: 'urn:li:sponsoredCampaign:',
+  campaign_group: 'urn:li:sponsoredCampaignGroup:',
+  creative: 'urn:li:sponsoredCreative:'
+};
+
+/**
+ * Normalize ad account IDs by stripping an optional sponsoredAccount URN prefix.
+ */
+export function normalizeAccountId(accountId) {
+  const raw = String(accountId || '').trim();
+  if (!raw) {
+    return '';
+  }
+
+  return raw.startsWith(ENTITY_URN_PREFIXES.account)
+    ? raw.slice(ENTITY_URN_PREFIXES.account.length)
+    : raw;
+}
+
+/**
+ * Resolve account ID from params or environment, normalized to the plain numeric form.
+ */
+export function getAccountId(params = {}) {
+  const accountId = params.account_id || process.env.LINKEDIN_ADS_ACCOUNT_ID;
+  if (!accountId) {
+    throw invalidParamsError('account_id parameter or LINKEDIN_ADS_ACCOUNT_ID environment variable required');
+  }
+
+  return normalizeAccountId(accountId);
+}
+
+/**
+ * Convert a plain ID to a fully-qualified sponsored entity URN.
+ * IDs that already look like URNs are passed through untouched.
+ * @param {'account' | 'campaign' | 'campaign_group' | 'creative'} entityType
+ * @param {string | number} id
+ * @returns {string}
+ */
+export function toEntityUrn(entityType, id) {
+  const prefix = ENTITY_URN_PREFIXES[entityType];
+  if (!prefix) {
+    throw invalidParamsError(`Unknown entity type for URN: ${entityType}. Allowed: ${Object.keys(ENTITY_URN_PREFIXES).join(', ')}`);
+  }
+
+  const raw = String(id ?? '').trim();
+  if (!raw) {
+    throw invalidParamsError(`Missing id for ${entityType} URN`);
+  }
+
+  return raw.startsWith('urn:li:') ? raw : `${prefix}${raw}`;
+}
+
+/**
+ * Extract the trailing entity ID from a URN, or return the value unchanged
+ * when it is already a plain ID.
+ */
+export function fromEntityUrn(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw.startsWith('urn:li:')) {
+    return raw;
+  }
+
+  const segments = raw.split(':');
+  return segments[segments.length - 1];
+}