@channel47/linkedin-ads-mcp 0.1.0

package/server/tools/analytics.js

@@ -0,0 +1,145 @@
+import { linkedinRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+import { rawParam, restliDateRange } from '../utils/restli.js';
+import { getAccountId, toEntityUrn, validateEnum, validateRequired } from '../utils/validation.js';
+
+export const SUPPORTED_PIVOTS = ['ACCOUNT', 'CAMPAIGN_GROUP', 'CAMPAIGN', 'CREATIVE'];
+export const SUPPORTED_TIME_GRANULARITIES = ['ALL', 'DAILY', 'MONTHLY'];
+export const SUPPORTED_ANALYTICS_ENTITY_TYPES = ['account', 'campaign_group', 'campaign', 'creative'];
+
+/**
+ * Default adAnalytics fields projection. dateRange and pivotValues are
+ * dimensional fields; the rest are metrics.
+ */
+export const DEFAULT_ANALYTICS_FIELDS = [
+  'impressions',
+  'clicks',
+  'costInLocalCurrency',
+  'externalWebsiteConversions',
+  'dateRange',
+  'pivotValues'
+];
+
+const NON_METRIC_FIELDS = new Set(['dateRange', 'pivotValues']);
+const MAX_METRIC_FIELDS = 20;
+const MAX_ELEMENTS_NOTE = 'adAnalytics does not support pagination; LinkedIn caps responses at 15,000 elements';
+
+const FACET_PARAM_BY_ENTITY_TYPE = {
+  account: 'accounts',
+  campaign_group: 'campaignGroups',
+  campaign: 'campaigns',
+  creative: 'creatives'
+};
+
+function resolveFields(fieldsValue) {
+  if (fieldsValue === undefined || fieldsValue === null || fieldsValue === '') {
+    return [...DEFAULT_ANALYTICS_FIELDS];
+  }
+
+  const fields = (Array.isArray(fieldsValue) ? fieldsValue : String(fieldsValue).split(','))
+    .map((field) => String(field).trim())
+    .filter(Boolean);
+
+  if (fields.length === 0) {
+    return [...DEFAULT_ANALYTICS_FIELDS];
+  }
+
+  for (const field of fields) {
+    if (!/^[A-Za-z][A-Za-z0-9]*$/.test(field)) {
+      throw invalidParamsError(`Invalid analytics field name: ${field}`);
+    }
+  }
+
+  const metricCount = fields.filter((field) => !NON_METRIC_FIELDS.has(field)).length;
+  if (metricCount > MAX_METRIC_FIELDS) {
+    throw invalidParamsError(`Too many metric fields: ${metricCount}. LinkedIn adAnalytics allows at most ${MAX_METRIC_FIELDS} metrics per call`);
+  }
+
+  return fields;
+}
+
+function resolveEntityUrns(params) {
+  const entityType = params.entity_type ? String(params.entity_type).toLowerCase() : 'account';
+  validateEnum(entityType, SUPPORTED_ANALYTICS_ENTITY_TYPES, 'entity_type');
+
+  const facetParam = FACET_PARAM_BY_ENTITY_TYPE[entityType];
+
+  if (Array.isArray(params.entity_ids) && params.entity_ids.length > 0) {
+    return {
+      entityType,
+      facetParam,
+      urns: params.entity_ids.map((id) => toEntityUrn(entityType, id))
+    };
+  }
+
+  if (entityType !== 'account') {
+    throw invalidParamsError(`entity_ids is required when entity_type is ${entityType}`);
+  }
+
+  const accountId = getAccountId(params);
+  return {
+    entityType,
+    facetParam,
+    urns: [toEntityUrn('account', accountId)]
+  };
+}
+
+/**
+ * Fetch adAnalytics metrics with a pivot, date range, and time granularity.
+ * Entity scope is built from plain IDs plus entity_type (defaults to the
+ * configured account). The endpoint has no pagination.
+ * @param {Record<string, unknown>} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function analytics(params = {}, dependencies = {}) {
+  const request = dependencies.request || linkedinRequest;
+
+  try {
+    validateRequired(params, ['pivot', 'start']);
+
+    const pivot = String(params.pivot).toUpperCase();
+    validateEnum(pivot, SUPPORTED_PIVOTS, 'pivot');
+
+    const timeGranularity = params.time_granularity
+      ? String(params.time_granularity).toUpperCase()
+      : 'ALL';
+    validateEnum(timeGranularity, SUPPORTED_TIME_GRANULARITIES, 'time_granularity');
+
+    const dateRange = restliDateRange(params.start, params.end);
+    const fields = resolveFields(params.fields);
+    const { entityType, facetParam, urns } = resolveEntityUrns(params);
+
+    const queryParams = {
+      q: 'analytics',
+      pivot,
+      dateRange: rawParam(dateRange),
+      timeGranularity,
+      [facetParam]: urns,
+      fields: rawParam(fields.join(','))
+    };
+
+    const response = await request('/adAnalytics', queryParams);
+    const rows = Array.isArray(response?.elements) ? response.elements : [];
+
+    return formatSuccess({
+      summary: `Returned ${rows.length} analytics row${rows.length === 1 ? '' : 's'} pivoted by ${pivot} (${timeGranularity})`,
+      data: rows,
+      metadata: {
+        pivot,
+        timeGranularity,
+        dateRange: {
+          start: params.start,
+          end: params.end || null
+        },
+        entityType,
+        entityCount: urns.length,
+        fields,
+        paginationNote: MAX_ELEMENTS_NOTE
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/list-accounts.js

@@ -0,0 +1,117 @@
+import { linkedinRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { rawParam, restliSearchFilter } from '../utils/restli.js';
+import { validateEnum } from '../utils/validation.js';
+
+const ACCOUNT_STATUSES = ['ACTIVE', 'CANCELED', 'DRAFT', 'PENDING_DELETION', 'REMOVED'];
+const ACCOUNT_TYPES = ['BUSINESS', 'ENTERPRISE'];
+const MAX_PAGE_SIZE = 1000;
+const DEFAULT_LIMIT = 1000;
+
+function normalizeFilterValues(value, allowed, paramName) {
+  if (value === undefined || value === null || value === '') {
+    return [];
+  }
+
+  const values = (Array.isArray(value) ? value : String(value).split(','))
+    .map((entry) => String(entry).trim().toUpperCase())
+    .filter(Boolean);
+
+  for (const entry of values) {
+    validateEnum(entry, allowed, paramName);
+  }
+
+  return values;
+}
+
+function getRequestedLimit(limitValue) {
+  const parsed = Number(limitValue);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_LIMIT;
+  }
+
+  return Math.floor(parsed);
+}
+
+function mapAccount(account) {
+  return {
+    id: account?.id ?? null,
+    name: account?.name || '',
+    status: account?.status || 'UNKNOWN',
+    currency: account?.currency || null,
+    type: account?.type || null,
+    test: Boolean(account?.test),
+    reference: account?.reference || null,
+    serving_statuses: Array.isArray(account?.servingStatuses) ? account.servingStatuses : []
+  };
+}
+
+async function fetchAllPages(request, path, baseParams, requestedLimit) {
+  const rows = [];
+  let pageToken = null;
+
+  while (rows.length < requestedLimit) {
+    const pageParams = {
+      ...baseParams,
+      pageSize: Math.min(requestedLimit - rows.length, MAX_PAGE_SIZE)
+    };
+
+    if (pageToken) {
+      pageParams.pageToken = pageToken;
+    }
+
+    const response = await request(path, pageParams);
+    const elements = Array.isArray(response?.elements) ? response.elements : [];
+    rows.push(...elements);
+
+    pageToken = response?.metadata?.nextPageToken;
+    if (!pageToken || elements.length === 0) {
+      break;
+    }
+  }
+
+  return rows.slice(0, requestedLimit);
+}
+
+/**
+ * List accessible LinkedIn ad accounts via the adAccounts search finder with
+ * cursor (pageToken/pageSize) pagination.
+ * @param {{ status?: string | string[], type?: string | string[], limit?: number }} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function listAccounts(params = {}, dependencies = {}) {
+  const request = dependencies.request || linkedinRequest;
+
+  try {
+    const statusValues = normalizeFilterValues(params.status, ACCOUNT_STATUSES, 'status');
+    const typeValues = normalizeFilterValues(params.type, ACCOUNT_TYPES, 'type');
+    const requestedLimit = getRequestedLimit(params.limit);
+
+    const queryParams = {
+      q: 'search'
+    };
+
+    const searchFilter = restliSearchFilter({
+      status: statusValues,
+      type: typeValues
+    });
+    if (searchFilter) {
+      queryParams.search = rawParam(searchFilter);
+    }
+
+    const accounts = (await fetchAllPages(request, '/adAccounts', queryParams, requestedLimit)).map(mapAccount);
+
+    return formatSuccess({
+      summary: `Found ${accounts.length} accessible LinkedIn ad account${accounts.length === 1 ? '' : 's'}`,
+      data: accounts,
+      metadata: {
+        totalAccounts: accounts.length,
+        appliedStatusFilter: statusValues.length > 0 ? statusValues : null,
+        appliedTypeFilter: typeValues.length > 0 ? typeValues : null
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/mutate.js

@@ -0,0 +1,117 @@
+import { linkedinRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { invalidParamsError } from '../utils/errors.js';
+import { getAccountId } from '../utils/validation.js';
+import {
+  buildApiRequest,
+  buildRequestPreview,
+  validateOperations
+} from '../utils/mutate-operations.js';
+
+/**
+ * Validate and execute LinkedIn Ads mutation operations with dry-run safety
+ * defaults. LinkedIn has no server-side validate-only mode, so dry_run
+ * (default true) performs local validation and returns a preview of the exact
+ * requests (method, path, headers, body) without calling the API.
+ * @param {Record<string, unknown>} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>, options?: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function mutate(params = {}, dependencies = {}) {
+  const request = dependencies.request || linkedinRequest;
+
+  try {
+    const operations = params.operations;
+    const accountId = getAccountId(params);
+    const partialFailure = params.partial_failure === undefined ? true : Boolean(params.partial_failure);
+    const dryRun = params.dry_run === undefined ? true : Boolean(params.dry_run);
+
+    const validationErrors = validateOperations(operations);
+    if (validationErrors.length > 0) {
+      const errorMessage = validationErrors.map((issue) => `[${issue.index}] ${issue.message}`).join('; ');
+      throw invalidParamsError(`Invalid operations: ${errorMessage}`);
+    }
+
+    if (dryRun) {
+      const preview = buildRequestPreview(operations, accountId);
+
+      return formatSuccess({
+        summary: `Dry run: ${operations.length} operation(s) validated locally. ${preview.requests.length} request(s) would be sent — no API calls were made (LinkedIn has no server-side validate-only mode). Re-run with dry_run=false to execute.`,
+        data: preview.requests,
+        metadata: {
+          dryRun: true,
+          serverValidated: false,
+          operationCount: operations.length,
+          apiCallCount: preview.requests.length,
+          accountId
+        }
+      });
+    }
+
+    if (process.env.LINKEDIN_ADS_READ_ONLY === 'true') {
+      throw new Error('mutate is disabled in read-only mode (LINKEDIN_ADS_READ_ONLY=true)');
+    }
+
+    const results = [];
+    let succeeded = 0;
+    let failed = 0;
+
+    for (let index = 0; index < operations.length; index += 1) {
+      const operation = operations[index];
+      const apiRequest = buildApiRequest(operation, accountId);
+
+      try {
+        const response = await request(apiRequest.path, {}, {
+          method: apiRequest.method,
+          headers: apiRequest.headers,
+          body: apiRequest.body
+        });
+
+        const resolvedId = response?.restliId || operation.id || null;
+        results.push({
+          index,
+          entity: operation.entity,
+          action: operation.action,
+          success: true,
+          id: resolvedId,
+          response
+        });
+        succeeded += 1;
+      } catch (error) {
+        results.push({
+          index,
+          entity: operation.entity,
+          action: operation.action,
+          success: false,
+          error: {
+            message: error.message
+          }
+        });
+        failed += 1;
+
+        if (!partialFailure) {
+          break;
+        }
+      }
+    }
+
+    if (succeeded === 0 && failed > 0) {
+      const firstError = results.find((entry) => !entry.success)?.error?.message || 'Unknown';
+      throw new Error(`All ${failed} operation(s) failed. First error: ${firstError}`);
+    }
+
+    return formatSuccess({
+      summary: `Executed ${results.length} operation(s): ${succeeded} succeeded, ${failed} failed`,
+      data: results,
+      metadata: {
+        dryRun: false,
+        operationCount: results.length,
+        succeeded,
+        failed,
+        accountId
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/tools/query.js

@@ -0,0 +1,147 @@
+import { linkedinRequest } from '../http.js';
+import { formatError, formatSuccess } from '../utils/response-format.js';
+import { rawParam, restliSearchFilter } from '../utils/restli.js';
+import { getAccountId, toEntityUrn, validateEnum } from '../utils/validation.js';
+
+const ENTITY_CONFIG = {
+  campaigns: {
+    collection: 'adCampaigns',
+    finder: 'search',
+    maxPageSize: 1000,
+    statuses: ['ACTIVE', 'PAUSED', 'ARCHIVED', 'COMPLETED', 'CANCELED', 'DRAFT', 'PENDING_DELETION', 'REMOVED']
+  },
+  campaign_groups: {
+    collection: 'adCampaignGroups',
+    finder: 'search',
+    maxPageSize: 1000,
+    statuses: ['ACTIVE', 'PAUSED', 'ARCHIVED', 'CANCELED', 'DRAFT', 'PENDING_DELETION', 'REMOVED']
+  },
+  creatives: {
+    collection: 'creatives',
+    finder: 'criteria',
+    maxPageSize: 100,
+    statuses: ['ACTIVE', 'PAUSED', 'DRAFT', 'ARCHIVED', 'CANCELED', 'PENDING_DELETION', 'REMOVED']
+  }
+};
+
+export const SUPPORTED_QUERY_ENTITIES = Object.keys(ENTITY_CONFIG);
+
+const DEFAULT_LIMIT = 100;
+
+function normalizeStatusValues(value, config) {
+  if (value === undefined || value === null || value === '') {
+    return [];
+  }
+
+  const values = (Array.isArray(value) ? value : String(value).split(','))
+    .map((entry) => String(entry).trim().toUpperCase())
+    .filter(Boolean);
+
+  for (const entry of values) {
+    validateEnum(entry, config.statuses, 'status');
+  }
+
+  return values;
+}
+
+function getRequestedLimit(limitValue) {
+  const parsed = Number(limitValue);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_LIMIT;
+  }
+
+  return Math.floor(parsed);
+}
+
+function buildBaseParams(entity, statusValues, params) {
+  const config = ENTITY_CONFIG[entity];
+  const queryParams = {
+    q: config.finder
+  };
+
+  if (config.finder === 'search') {
+    const searchFilter = restliSearchFilter({ status: statusValues });
+    if (searchFilter) {
+      queryParams.search = rawParam(searchFilter);
+    }
+    return queryParams;
+  }
+
+  // creatives use the criteria finder with top-level List params
+  if (statusValues.length > 0) {
+    queryParams.intendedStatuses = statusValues;
+  }
+
+  if (Array.isArray(params.campaign_ids) && params.campaign_ids.length > 0) {
+    queryParams.campaigns = params.campaign_ids.map((id) => toEntityUrn('campaign', id));
+  }
+
+  return queryParams;
+}
+
+async function fetchAllPages(request, path, baseParams, requestedLimit, maxPageSize) {
+  const rows = [];
+  let pageToken = null;
+
+  while (rows.length < requestedLimit) {
+    const pageParams = {
+      ...baseParams,
+      pageSize: Math.min(requestedLimit - rows.length, maxPageSize)
+    };
+
+    if (pageToken) {
+      pageParams.pageToken = pageToken;
+    }
+
+    const response = await request(path, pageParams);
+    const elements = Array.isArray(response?.elements) ? response.elements : [];
+    rows.push(...elements);
+
+    pageToken = response?.metadata?.nextPageToken;
+    if (!pageToken || elements.length === 0) {
+      break;
+    }
+  }
+
+  return rows.slice(0, requestedLimit);
+}
+
+/**
+ * Query campaigns, campaign groups, or creatives for a LinkedIn ad account
+ * using the entity finder appropriate for each collection (q=search for
+ * campaigns/campaign groups, q=criteria for creatives) with cursor pagination.
+ * @param {Record<string, unknown>} [params]
+ * @param {{ request?: (path: string, params: Record<string, unknown>) => Promise<any> }} [dependencies]
+ * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+ */
+export async function query(params = {}, dependencies = {}) {
+  const request = dependencies.request || linkedinRequest;
+
+  try {
+    validateEnum(params.entity, SUPPORTED_QUERY_ENTITIES, 'entity');
+
+    const entity = params.entity;
+    const config = ENTITY_CONFIG[entity];
+    const accountId = getAccountId(params);
+    const statusValues = normalizeStatusValues(params.status, config);
+    const requestedLimit = getRequestedLimit(params.limit);
+    const path = `/adAccounts/${accountId}/${config.collection}`;
+
+    const baseParams = buildBaseParams(entity, statusValues, params);
+    const rows = await fetchAllPages(request, path, baseParams, requestedLimit, config.maxPageSize);
+
+    return formatSuccess({
+      summary: `Returned ${rows.length} ${entity} row${rows.length === 1 ? '' : 's'}`,
+      data: rows,
+      metadata: {
+        entity,
+        accountId,
+        limit: requestedLimit,
+        returned: rows.length,
+        appliedStatusFilter: statusValues.length > 0 ? statusValues : null
+      }
+    });
+  } catch (error) {
+    return formatError(error);
+  }
+}

package/server/utils/errors.js

@@ -0,0 +1,12 @@
+function createTypedError(code, message) {
+  const error = new Error(message);
+  error.mcpCode = code;
+  return error;
+}
+
+/**
+ * Create an InvalidParams typed error.
+ */
+export function invalidParamsError(message) {
+  return createTypedError('InvalidParams', message);
+}