ConsignCloud MCP Server

Instructions

Implementation Reference

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

  The primary handler implementing calculate_account_metrics tool logic. Fetches account info, paginates items and sales, computes inventory value, items available/sold, total sales revenue, and commission owed based on item splits. Applies optional date and inventory type filters client-side.
  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/types.ts:129-145 (schema)

  Type definition for the output of calculateAccountMetrics, specifying all metric fields with types and descriptions.
  export interface AccountMetricsResult { account_id: string; account_name: string; current_balance: number; // in cents current_balance_formatted: string; // locale-formatted inventory_value: number; // in cents (available items) inventory_value_formatted: string; // locale-formatted items_available: number; items_sold: number; total_sales_revenue: number; // in cents total_sales_revenue_formatted: string; // locale-formatted commission_owed: number; // in cents (calculated from splits) commission_owed_formatted: string; // locale-formatted filters_applied: string[]; currency: string; // ISO currency code locale: string; // BCP 47 locale }
• src/server.ts:381-398 (registration)

  MCP tool registration object defining name, description, and input schema for validation.
  { 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)

  Server-side dispatch handler for the tool, delegating execution to client.calculateAccountMetrics.
  case 'calculate_account_metrics': return { content: [{ type: 'text', text: JSON.stringify(await client.calculateAccountMetrics(args as any), null, 2) }] };