Summary MCP

Instructions

Implementation Reference

• src/tools/compare-periods.js:15-102 (handler)

  The core handler function for the 'compare_periods' tool. It validates input periods, calculates date ranges, generates instructions for data collection, processes comparison data if provided, computes changes between periods, and handles file saving for HTML/Markdown outputs.
  export async function comparePeriods(args) { try { if (!args.period1 || !args.period2) { throw { code: 'MISSING_PARAMETER', message: 'Both period1 and period2 must be provided', details: 'Each period should have start_date and end_date', }; } // Calculate date ranges for both periods const period1Range = calculateDateRange({ start_date: args.period1.start_date, end_date: args.period1.end_date, }); const period2Range = calculateDateRange({ start_date: args.period2.start_date, end_date: args.period2.end_date, }); const metrics = args.metrics || ['all']; const outputFormat = args.output_format || config.defaults.outputFormat || 'both'; const saveToFile = args.save_to_file !== false; // Generate comparison instructions const instructions = generateComparisonInstructions(period1Range, period2Range, metrics); const result = { success: true, message: 'Period comparison initiated. Follow instructions to collect data for both periods.', period1: period1Range, period2: period2Range, metrics_to_compare: metrics, output_format: outputFormat, save_to_file: saveToFile, instructions, note: 'This tool helps identify trends by comparing two time periods. Collect the same metrics for both periods, then calculate differences.', }; // If comparison data is provided, process it if (args.comparison_data) { result.comparison = processComparisonData( args.comparison_data, period1Range, period2Range, metrics ); // Save comparison files if requested if (saveToFile && args.comparison_data.html && args.comparison_data.markdown) { const files = []; const filenameBase = `period-comparison-${period1Range.startDate}-vs-${period2Range.startDate}`; if (outputFormat === 'both' || outputFormat === 'html') { const htmlPath = await saveSummary( args.comparison_data.html, `${filenameBase}.html` ); files.push(htmlPath); } if (outputFormat === 'both' || outputFormat === 'markdown') { const mdPath = await saveSummary( args.comparison_data.markdown, `${filenameBase}.md` ); files.push(mdPath); } result.files_saved = files; result.message = `Period comparison completed and saved to ${files.length} file(s).`; } } return result; } catch (error) { if (error.code) { throw error; } throw { code: 'COMPARISON_FAILED', message: 'Failed to compare periods', details: error.message, }; } }
• src/tools/index.js:179-237 (schema)

  JSON Schema defining the input parameters for the compare_periods tool, including required period1 and period2 objects with dates, optional metrics, output_format, and save_to_file.
  name: 'compare_periods', description: 'Compare productivity statistics between two time periods. Generates comparison reports in HTML and Markdown formats showing trends and changes.', inputSchema: { type: 'object', properties: { period1: { type: 'object', description: 'First period to compare', properties: { start_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', }, end_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', }, }, required: ['start_date', 'end_date'], }, period2: { type: 'object', description: 'Second period to compare', properties: { start_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', }, end_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$', }, }, required: ['start_date', 'end_date'], }, metrics: { type: 'array', items: { type: 'string', enum: ['meetings', 'slack', 'email', 'focus_time', 'all'], }, description: 'Metrics to compare (default: all)', default: ['all'], }, output_format: { type: 'string', enum: ['both', 'html', 'markdown'], description: 'Output format(s) to generate (default: both)', default: 'both', }, save_to_file: { type: 'boolean', description: 'Whether to save comparison to summaries directory (default: true)', default: true, }, }, required: ['period1', 'period2'], }, },
• src/tools/handler.js:43-45 (registration)

  Registration of the compare_periods tool in the central handleToolCall switch statement, which dispatches calls to the comparePeriods implementation.
  case 'compare_periods': result = await comparePeriods(args); break;
• src/tools/compare-periods.js:194-231 (helper)

  Helper function that calculates absolute and percentage changes between two sets of statistics for various metrics like meeting hours, slack messages, emails, and focus time.
  function calculateChanges(stats1, stats2) { const changes = {}; // Helper to calculate change const calcChange = (val1, val2, unit = '') => { const diff = val2 - val1; const percentage = val1 !== 0 ? ((diff / val1) * 100).toFixed(1) : 0; const direction = diff > 0 ? 'increase' : diff < 0 ? 'decrease' : 'no change'; return { value: `${diff > 0 ? '+' : ''}${diff}${unit}`, percentage: `${percentage > 0 ? '+' : ''}${percentage}%`, direction, }; }; // Meeting hours if (stats1.meeting_hours !== undefined && stats2.meeting_hours !== undefined) { changes.meeting_hours = calcChange(stats1.meeting_hours, stats2.meeting_hours, ' hours'); } // Slack messages if (stats1.slack_messages !== undefined && stats2.slack_messages !== undefined) { changes.slack_messages = calcChange(stats1.slack_messages, stats2.slack_messages, ' messages'); } // Emails if (stats1.emails_sent !== undefined && stats2.emails_sent !== undefined) { changes.emails_sent = calcChange(stats1.emails_sent, stats2.emails_sent, ' emails'); } // Focus time if (stats1.focus_time_hours !== undefined && stats2.focus_time_hours !== undefined) { changes.focus_time_hours = calcChange(stats1.focus_time_hours, stats2.focus_time_hours, ' hours'); } return changes; }