syndicate-links-mcp

Instructions

Implementation Reference

• mcp/src/tools/commission.ts:34-36 (handler)

  Handler function that executes get_commission_status tool logic - makes API call to /affiliate/me/balance with agent auth

  export async function runGetCommissionStatus(config: ApiConfig): Promise<unknown> {
    return apiFetch(config, '/affiliate/me/balance', { authType: 'agent' });
  }

• mcp/src/tools/commission.ts:21-32 (schema)

  Tool definition including name, description and input schema for get_commission_status (empty properties object since no inputs required)

  export const getCommissionStatusTool: Tool = {
    name: 'get_commission_status',
    description:
      'Return the commission balance for the authenticated affiliate (identified by ' +
      'SYNDICATE_AGENT_KEY). Returns available (approved and ready to pay out), ' +
      'pending (not yet approved), and lifetime totals in USD.',
    inputSchema: {
      type: 'object' as const,
      properties: {},
      required: [],
    },
  };

• mcp/src/server.ts:48-54 (registration)

  Import of getCommissionStatusTool and runGetCommissionStatus from commission module

  import {
    getCommissionStatusTool,
    runGetCommissionStatus,
    runPayoutCycleTool,
    runPayoutCycle,
  } from './tools/commission.js';
  import { listMerchantProgramsTool, runListMerchantPrograms } from './tools/programs.js';

• mcp/src/server.ts:106-108 (registration)

  Tool dispatch case in the switch statement that routes get_commission_status calls to runGetCommissionStatus handler

  case 'get_commission_status':
    result = await runGetCommissionStatus(cfg);
    break;

• mcp/src/api-client.ts:52-107 (helper)

  Helper function apiFetch used by the handler to make authenticated HTTP requests to the API

  export async function apiFetch(
    config: ApiConfig,
    path: string,
    opts: RequestOptions,
  ): Promise<unknown> {
    const headers: Record<string, string> = {
      'Content-Type': 'application/json',
      Accept: 'application/json',
    };
  
    switch (opts.authType) {
      case 'agent':
        if (!config.agentKey) throw new ApiError(401, 'SYNDICATE_AGENT_KEY not configured');
        headers['Authorization'] = `Bearer ${config.agentKey}`;
        break;
      case 'merchant':
        if (!config.merchantKey) throw new ApiError(401, 'SYNDICATE_MERCHANT_KEY not configured');
        headers['Authorization'] = `Bearer ${config.merchantKey}`;
        break;
      case 'admin':
        if (!config.adminSecret) throw new ApiError(401, 'SYNDICATE_ADMIN_SECRET not configured');
        headers['x-admin-secret'] = config.adminSecret;
        break;
      case 'none':
        break;
    }
  
    const res = await fetch(`${config.baseUrl}${path}`, {
      method: opts.method ?? 'GET',
      headers,
      body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
      signal: AbortSignal.timeout(30_000),
    });
  
    let data: unknown;
    try {
      data = await res.json();
    } catch {
      data = { message: res.statusText };
    }
  
    if (!res.ok) {
      const d = data as Record<string, unknown> | null;
      const msg =
        d != null && typeof d === 'object'
          ? typeof d['error'] === 'string'
            ? d['error']
            : typeof d['message'] === 'string'
              ? d['message']
              : `HTTP ${res.status}`
          : `HTTP ${res.status}`;
      throw new ApiError(res.status, msg);
    }
  
    return data;
  }