ConsignCloud MCP Server

Instructions

Implementation Reference

• src/server.ts:381-398 (registration)

  Tool registration in createTools() function, defining name, description, and input schema for calculate_account_metrics.

  {
    name: 'calculate_account_metrics',
    description: 'Calculate comprehensive metrics for a specific vendor/consignor account including current balance, inventory value, items available/sold, total sales revenue, and commission owed.',
    inputSchema: {
      type: 'object',
      properties: {
        account_id: { type: 'string', description: 'Account ID (required)' },
        date_from: { type: 'string', description: 'Filter by items/sales created on or after this date (ISO 8601: YYYY-MM-DD)' },
        date_to: { type: 'string', description: 'Filter by items/sales created on or before this date (ISO 8601: YYYY-MM-DD)' },
        inventory_type: {
          type: 'string',
          enum: ['consignment', 'buy_outright', 'retail'],
          description: 'Filter by inventory type'
        },
      },
      required: ['account_id'],
    },
  },

• src/server.ts:515-516 (handler)

  MCP server dispatch handler case that invokes the client-side calculateAccountMetrics implementation.

  case 'calculate_account_metrics':
    return { content: [{ type: 'text', text: JSON.stringify(await client.calculateAccountMetrics(args as any), null, 2) }] };

• src/client.ts:724-829 (handler)

  Primary handler function in ConsignCloudClient that executes the core logic: fetches data via API calls, performs client-side filtering/aggregation, calculates metrics, and formats output.

  async calculateAccountMetrics(params: {
    account_id: string;
    date_from?: string;
    date_to?: string;
    inventory_type?: string;
  }): Promise<AccountMetricsResult> {
    const { account_id, date_from, date_to, inventory_type } = params;
    const filters: string[] = [`account_id=${account_id}`];
  
    if (date_from) filters.push(`date_from=${date_from}`);
    if (date_to) filters.push(`date_to=${date_to}`);
    if (inventory_type) filters.push(`inventory_type=${inventory_type}`);
  
    // Fetch account details
    const account = await this.getAccount(account_id);
  
    // Fetch all items for this account
    let allItems: Item[] = [];
    let cursor: string | null = null;
    const itemQueryParams: Record<string, any> = { limit: 100, account: account_id };
    if (inventory_type) itemQueryParams.inventory_type = inventory_type;
  
    do {
      if (cursor) itemQueryParams.cursor = cursor;
      const response = await this.listItems(itemQueryParams);
      allItems = allItems.concat(response.data);
      cursor = response.next_cursor;
    } while (cursor);
  
    // Calculate inventory metrics
    let inventoryValue = 0;
    let itemsAvailable = 0;
    let itemsSold = 0;
  
    for (const item of allItems) {
      const quantity = item.quantity || 1;
      if (item.status === 'sold') {
        itemsSold += quantity;
      } else if (item.status === 'available') {
        inventoryValue += item.tag_price * quantity;
        itemsAvailable += quantity;
      }
    }
  
    // Fetch sales for this account (items sold by this consignor)
    let totalSalesRevenue = 0;
    let commissionOwed = 0;
  
    // Fetch all sales (no date filter - API doesn't support it)
    let allSales: Sale[] = [];
    cursor = null;
    const salesQueryParams: Record<string, any> = { limit: 100 };
    // NOTE: date_from/date_to NOT sent to API (not supported) - will filter client-side
  
    do {
      if (cursor) salesQueryParams.cursor = cursor;
      const response = await this.listSales(salesQueryParams);
      allSales = allSales.concat(response.data);
      cursor = response.next_cursor;
    } while (cursor);
  
    // Apply client-side date filtering (API doesn't support this)
    if (date_from || date_to) {
      allSales = allSales.filter(sale => {
        if (!sale.created) return false;
        const saleDate = new Date(sale.created);
        if (date_from && saleDate < new Date(date_from)) return false;
        if (date_to && saleDate > new Date(date_to)) return false;
        return true;
      });
    }
  
    // Calculate sales revenue for items from this account
    for (const sale of allSales) {
      if (sale.status === 'completed' && sale.items) {
        for (const saleItem of sale.items) {
          // Check if this sale item belongs to our account
          const matchingItem = allItems.find(i => i.id === saleItem.item);
          if (matchingItem) {
            const itemRevenue = saleItem.price || 0;
            totalSalesRevenue += itemRevenue;
            // Calculate commission based on split
            commissionOwed += Math.round(itemRevenue * matchingItem.split);
          }
        }
      }
    }
  
    return {
      account_id: account.id,
      account_name: [account.first_name, account.last_name].filter(Boolean).join(' ') || account.company || account.number,
      current_balance: account.balance,
      current_balance_formatted: this.formatAmount(account.balance),
      inventory_value: inventoryValue,
      inventory_value_formatted: this.formatAmount(inventoryValue),
      items_available: itemsAvailable,
      items_sold: itemsSold,
      total_sales_revenue: totalSalesRevenue,
      total_sales_revenue_formatted: this.formatAmount(totalSalesRevenue),
      commission_owed: commissionOwed,
      commission_owed_formatted: this.formatAmount(commissionOwed),
      filters_applied: filters,
      currency: this.currency,
      locale: this.locale,
    };
  }

• src/server.ts:384-396 (schema)

  Input schema/parameter validation definition for the tool.

  inputSchema: {
    type: 'object',
    properties: {
      account_id: { type: 'string', description: 'Account ID (required)' },
      date_from: { type: 'string', description: 'Filter by items/sales created on or after this date (ISO 8601: YYYY-MM-DD)' },
      date_to: { type: 'string', description: 'Filter by items/sales created on or before this date (ISO 8601: YYYY-MM-DD)' },
      inventory_type: {
        type: 'string',
        enum: ['consignment', 'buy_outright', 'retail'],
        description: 'Filter by inventory type'
      },
    },
    required: ['account_id'],