/**
* Optimized GraphQL Queries and Response Formatters for MCP Context Management
*
* This module provides the core optimization functionality for reducing context usage.
*/
export type VerbosityLevel = 'ultra-light' | 'light' | 'standard';
// =============================================================================
// ULTRA-LIGHT QUERIES (99% reduction - < 100 chars per item)
// =============================================================================
export const GET_ACCOUNTS_ULTRA_LIGHT = `
query GetAccountsUltraLight {
accounts {
id
displayName
currentBalance
type {
name
}
}
}
`;
export const GET_TRANSACTIONS_ULTRA_LIGHT = `
query GetTransactionsUltraLight(
$offset: Int,
$limit: Int,
$filters: TransactionFilterInput,
$orderBy: TransactionOrdering
) {
allTransactions(filters: $filters) {
results(offset: $offset, limit: $limit, orderBy: $orderBy) {
id
amount
date
merchant {
name
}
account {
displayName
}
}
}
}
`;
// =============================================================================
// LIGHT QUERIES (85% reduction - < 500 chars per item)
// =============================================================================
export const GET_ACCOUNTS_LIGHT = `
query GetAccountsLight {
accounts {
id
displayName
currentBalance
mask
isHidden
includeInNetWorth
updatedAt
type {
name
display
}
institution {
name
}
}
}
`;
export const GET_TRANSACTIONS_LIGHT = `
query GetTransactionsLight(
$offset: Int,
$limit: Int,
$filters: TransactionFilterInput,
$orderBy: TransactionOrdering
) {
allTransactions(filters: $filters) {
results(offset: $offset, limit: $limit, orderBy: $orderBy) {
id
amount
date
pending
needsReview
category {
id
name
}
merchant {
name
}
account {
id
displayName
mask
}
}
}
}
`;
// =============================================================================
// PRE-AGGREGATED SUMMARY QUERIES (Ultra-compact responses)
// =============================================================================
export const GET_QUICK_FINANCIAL_OVERVIEW = `
query GetQuickFinancialOverview {
accounts {
currentBalance
includeInNetWorth
}
}
`;
export const SMART_TRANSACTION_SEARCH = `
query SmartTransactionSearch(
$search: String,
$limit: Int = 10,
$startDate: String,
$endDate: String,
$minAmount: Float,
$maxAmount: Float,
$accountIds: [ID!],
$categoryIds: [ID!]
) {
allTransactions(filters: {
search: $search,
startDate: $startDate,
endDate: $endDate,
minAmount: $minAmount,
maxAmount: $maxAmount,
accountIds: $accountIds,
categoryIds: $categoryIds,
transactionVisibility: non_hidden_transactions_only
}) {
totalCount
results(limit: $limit, orderBy: DATE_DESC) {
id
amount
date
merchant {
name
}
category {
name
}
account {
displayName
mask
}
}
}
}
`;
// =============================================================================
// QUERY SELECTOR UTILITY
// =============================================================================
export interface OptimizedQuerySet {
accounts: string;
transactions: string;
categories: string;
budgets: string;
}
/**
* Select appropriate queries based on verbosity level
*/
export function getOptimizedQueries(verbosity: VerbosityLevel): OptimizedQuerySet {
switch (verbosity) {
case 'ultra-light':
return {
accounts: GET_ACCOUNTS_ULTRA_LIGHT,
transactions: GET_TRANSACTIONS_ULTRA_LIGHT,
categories: 'GET_CATEGORIES_LIGHT',
budgets: 'GET_BUDGETS_LIGHT'
};
case 'light':
return {
accounts: GET_ACCOUNTS_LIGHT,
transactions: GET_TRANSACTIONS_LIGHT,
categories: 'GET_CATEGORIES_LIGHT',
budgets: 'GET_BUDGETS_LIGHT'
};
default: // 'standard'
return {
accounts: 'GET_ACCOUNTS',
transactions: 'GET_TRANSACTIONS',
categories: 'GET_TRANSACTION_CATEGORIES',
budgets: 'GET_BUDGETS'
};
}
}
/**
* Response size estimates for different verbosity levels
*/
export const RESPONSE_SIZE_ESTIMATES = {
'ultra-light': {
accounts: 60, // ~60 chars per account
transactions: 80, // ~80 chars per transaction
categories: 40, // ~40 chars per category
budgets: 50 // ~50 chars per budget item
},
'light': {
accounts: 180, // ~180 chars per account
transactions: 220, // ~220 chars per transaction
categories: 80, // ~80 chars per category
budgets: 120 // ~120 chars per budget item
},
'standard': {
accounts: 800, // ~800 chars per account (original)
transactions: 600, // ~600 chars per transaction (original)
categories: 200, // ~200 chars per category (original)
budgets: 300 // ~300 chars per budget item (original)
}
} as const;
/**
* Calculate optimal verbosity level based on item count and max response size
*/
export function calculateOptimalVerbosity(
dataType: keyof typeof RESPONSE_SIZE_ESTIMATES['ultra-light'],
itemCount: number,
maxResponseSize: number = 5000
): VerbosityLevel {
const estimates = RESPONSE_SIZE_ESTIMATES;
// Calculate estimated sizes for each verbosity level
const ultraLightSize = estimates['ultra-light'][dataType] * itemCount;
const lightSize = estimates['light'][dataType] * itemCount;
const standardSize = estimates['standard'][dataType] * itemCount;
// Select the highest verbosity that fits within size limit
if (standardSize <= maxResponseSize) return 'standard';
if (lightSize <= maxResponseSize) return 'light';
return 'ultra-light';
}
/**
* Response formatters for different verbosity levels
*/
export class OptimizedResponseFormatter {
/**
* Format accounts based on verbosity level
*/
static formatAccounts(accounts: any[], verbosity: VerbosityLevel): string {
switch (verbosity) {
case 'ultra-light':
const total = accounts.reduce((sum, acc) => sum + (acc.currentBalance || 0), 0);
return `💰 ${accounts.length} accounts, Total: $${total.toLocaleString()}`;
case 'light':
return accounts.map(acc => {
const balance = acc.currentBalance || 0;
const hiddenFlag = acc.isHidden ? ' (hidden)' : '';
return `• ${acc.displayName}: $${balance.toLocaleString()}${hiddenFlag}`;
}).join('\n') +
`\n\nTotal: $${accounts.reduce((s, a) => s + (a.currentBalance || 0), 0).toLocaleString()}`;
default: // standard
return accounts.map(acc => {
const balance = acc.currentBalance || 0;
const institution = acc.institution?.name || 'Manual';
const lastUpdated = acc.updatedAt ? new Date(acc.updatedAt).toLocaleDateString() : 'Unknown';
return `• **${acc.displayName}**\n` +
` Type: ${acc.type?.display || acc.type?.name}\n` +
` Balance: $${balance.toLocaleString()}\n` +
` Institution: ${institution}\n` +
` Updated: ${lastUpdated}`;
}).join('\n\n') +
`\n\n**Total Balance: $${accounts.reduce((s, a) => s + (a.currentBalance || 0), 0).toLocaleString()}**`;
}
}
/**
* Format transactions based on verbosity level
*/
static formatTransactions(transactions: any[], verbosity: VerbosityLevel, originalQuery?: string): string {
if (!transactions.length) return '';
const header = originalQuery ? `🧠 **Smart Query**: "${originalQuery}"\n\n` : '';
switch (verbosity) {
case 'ultra-light':
const total = transactions.reduce((sum, txn) => sum + Math.abs(txn.amount), 0);
return `${header}💳 ${transactions.length} transactions, Volume: $${total.toLocaleString()}`;
case 'light':
return header + transactions.map(txn => {
const date = new Date(txn.date).toLocaleDateString();
const amount = Math.abs(txn.amount).toLocaleString();
const merchant = txn.merchant?.name || 'Unknown merchant';
const category = txn.category?.name || 'Uncategorized';
return `• ${date} - ${merchant}\n ${txn.amount < 0 ? '-' : ''}$${amount} • ${category}`;
}).join('\n');
default: // standard
return header + `💳 **Transaction Summary** (${transactions.length} transactions)\n\n` +
transactions.map(txn => {
const date = new Date(txn.date).toLocaleDateString();
const amount = Math.abs(txn.amount).toLocaleString();
const merchant = txn.merchant?.name || 'Unknown merchant';
const category = txn.category?.name || 'Uncategorized';
const account = txn.account?.displayName;
const mask = txn.account?.mask;
return `• ${date} - **${merchant}**\n` +
` Amount: ${txn.amount < 0 ? '-' : ''}$${amount}\n` +
` Category: ${category}\n` +
` Account: ${account}${mask ? ` (...${mask})` : ''}`;
}).join('\n\n') +
`\n\n**Total Transaction Volume: $${transactions.reduce((s, t) => s + Math.abs(t.amount), 0).toLocaleString()}**`;
}
}
/**
* Format quick financial overview (ultra-compact)
*/
static formatQuickStats(accounts: any[], recentTransactions?: any[]): string {
const totalBalance = accounts
.filter(acc => acc.includeInNetWorth)
.reduce((sum, acc) => sum + (acc.currentBalance || 0), 0);
const accountCount = accounts.length;
const transactionCount = recentTransactions?.length || 0;
// Calculate month-over-month change (simplified)
const thisMonth = recentTransactions?.filter(t => {
const txnDate = new Date(t.date);
const now = new Date();
return txnDate.getMonth() === now.getMonth() && txnDate.getFullYear() === now.getFullYear();
}) || [];
const monthlyChange = thisMonth.reduce((sum, t) => sum + t.amount, 0);
const changeSymbol = monthlyChange >= 0 ? '⬆️' : '⬇️';
return `💰 $${totalBalance.toLocaleString()} • ${changeSymbol} ${monthlyChange >= 0 ? '+' : ''}$${Math.abs(monthlyChange).toLocaleString()} • 📊 ${accountCount} accounts`;
}
/**
* Format spending by category summary (ultra-compact)
*/
static formatSpendingSummary(transactions: any[], topN: number = 5): string {
// Group by category and sum amounts
const categoryTotals = new Map<string, number>();
transactions.forEach(txn => {
if (txn.amount < 0) { // Only expenses
const category = txn.category?.name || 'Uncategorized';
categoryTotals.set(category, (categoryTotals.get(category) || 0) + Math.abs(txn.amount));
}
});
// Sort and take top N
const sortedCategories = Array.from(categoryTotals.entries())
.sort((a, b) => b[1] - a[1])
.slice(0, topN);
if (sortedCategories.length === 0) {
return '💸 No expenses found';
}
// Create ultra-compact summary
const topCategoriesStr = sortedCategories
.slice(0, 3)
.map(([category, amount]) => {
const icon = this.getCategoryIcon(category);
return `${icon} $${Math.round(amount).toLocaleString()}`;
})
.join(' • ');
return topCategoriesStr + ` (top ${Math.min(3, sortedCategories.length)} this month)`;
}
/**
* Get emoji icon for category
*/
private static getCategoryIcon(category: string): string {
const categoryIcons: Record<string, string> = {
'dining': '🍽️',
'restaurants': '🍽️',
'food': '🍽️',
'groceries': '🛒',
'gas': '⛽',
'fuel': '⛽',
'transportation': '🚗',
'shopping': '🛍️',
'entertainment': '🎬',
'utilities': '⚡',
'rent': '🏠',
'mortgage': '🏠',
'insurance': '🛡️',
'healthcare': '🏥',
'medical': '🏥',
'travel': '✈️',
'education': '📚',
'fitness': '💪',
'subscriptions': '📱',
'income': '💰',
'salary': '💰'
};
const lowerCategory = category.toLowerCase();
for (const [key, icon] of Object.entries(categoryIcons)) {
if (lowerCategory.includes(key)) {
return icon;
}
}
return '💸'; // Default expense icon
}
}
