Time Tracking MCP

Instructions

Implementation Reference

• src/tools/log-time.ts:76-167 (handler)

  The core handler function for the 'log_time' tool. It processes LogTimeInput arguments: resolves company, sanitizes task, parses duration/date/time/tags, creates a TimeEntry, saves it to the company's markdown file via MarkdownManager, loads weekly summary, checks parse issues, and constructs a detailed markdown response with totals, commitment progress, and warnings.
  handler: withErrorHandler('logging time', async (args: LogTimeInput) => { // Resolve company (single-company mode auto-selects, multi-company requires explicit) const userInput = `${args.task || ''} ${args.duration || ''}`.trim(); const company = getCompanyForOperation(args.company, userInput); // Sanitize and validate task description const sanitizedTask = sanitizeTaskDescription(args.task); // Parse inputs const duration = parseDuration(args.duration); const date = parseDate(args.date); const time = parseTime(args.time, date); const tags = args.tags || []; // Create time entry const entry: TimeEntry = { time: formatTime(time), task: sanitizedTask, duration: duration.hours, tags, date: formatDate(date) }; // Save to markdown await markdownManager.addEntry(company, entry); // Load weekly summary for confirmation const { year, week } = getISOWeek(date); const summary = await markdownManager.getWeeklySummary(company, year, week); // Check for parse issues const parseIssues = markdownManager.getParseIssues(); // Build response let response = `✓ Logged ${duration.formatted} for "${sanitizedTask}" at ${entry.time}`; if (args.date && args.date !== 'today') { response += ` on ${entry.date}`; } if (tags.length > 0) { response += ` [${tags.map(t => '#' + t).join(' ')}]`; } response += '\n\n'; if (summary) { response += `**Week ${week} Status:**\n`; response += `• Total: ${summary.totalHours.toFixed(1)}h`; const config = await markdownManager.loadConfig(company); if (config.commitments.total) { const limit = config.commitments.total.limit; const stats = summaryCalculator.getCommitmentStats(summary.totalHours, limit); response += ` / ${limit}h (${stats.percentage}%)`; if (stats.status === 'over') { response += ` ⚠️ OVER LIMIT`; } else if (stats.status === 'approaching') { response += ` ⚠️ Close to limit`; } } response += '\n'; // Show commitment breakdown for (const [commitment, hours] of Object.entries(summary.byCommitment)) { const limit = config.commitments[commitment]?.limit; if (limit) { const stats = summaryCalculator.getCommitmentStats(hours, limit); const warning = stats.status !== 'within' ? ` ${stats.indicator}` : ''; response += `• ${capitalizeName(commitment)}: ${hours.toFixed(1)}h / ${limit}h (${stats.percentage}%)${warning}\n`; } } } // Add parse warnings if any if (parseIssues.warnings.length > 0) { response += '\n\n⚠️ **Parse Warnings:**\n'; for (const warning of parseIssues.warnings) { response += `• ${warning}\n`; } if (parseIssues.unparsedLines.length > 0 && parseIssues.unparsedLines.length <= 3) { response += '\nUnparsed lines:\n'; for (const { lineNumber, content } of parseIssues.unparsedLines) { response += ` Line ${lineNumber}: ${content}\n`; } } } return createTextResponse(response); })
• src/tools/log-time.ts:38-68 (schema)

  JSON Schema definition for LogTimeInput used by the log_time tool, specifying properties for task, duration (required), time, date, tags, and optional company.
  inputSchema: { type: 'object', properties: { task: { type: 'string', description: 'Task description (e.g., "Conduit MCP: Security review")' }, duration: { type: 'string', description: 'Duration (e.g., "2h", "90m", "1.5h")' }, time: { type: 'string', description: 'Time when work was done (e.g., "14:30", "2 hours ago", omit for now)' }, date: { type: 'string', description: 'Date of work (e.g., "today", "yesterday", "2025-10-17", omit for today)' }, tags: { type: 'array', items: { type: 'string' }, description: 'Tags to categorize work (e.g., ["development", "security"])' }, company: { type: 'string', description: 'Company to log time for (optional, uses default if omitted)' } }, required: ['task', 'duration'] },
• src/tools/log-time.ts:16-168 (registration)

  Registration of the 'log_time' tool using registerTool from ./registry.js. Includes name, detailed description with parsing examples, inputSchema, annotations, and handler.
  registerTool({ name: 'log_time', description: `Log a completed time entry. This tool records work you've done. Natural language examples Claude should parse: - Single company mode: "2h on security review" → task: "security review", duration: "2h" - Multi company mode: "hm 2h on security review" → company: "HeliMods", duration: "2h", task: "security review" - Multi company mode: "2h debugging for stellantis" → duration: "2h", task: "debugging", company: "Stellantis" - "Client meeting yesterday 90 minutes" → task: "Client meeting", duration: "90m", date: "yesterday" Claude should extract: - task: What was worked on - duration: How long (2h, 90m, 1.5h, etc.) - time: When (optional, defaults to now) - date: Which day (optional, defaults to today) - tags: Inferred or explicit tags - company: CRITICAL - In multi-company mode, MUST extract from user input using: * Prefix pattern: "company/abbrev [duration] [task]" (e.g., "hm 2h debugging", "stellantis 1h meeting") * Suffix pattern: "[duration] [task] for company/abbrev" (e.g., "2h debugging for hm", "1h meeting for stellantis") * Full company names work (case-insensitive): "HeliMods", "Stellantis", etc. * Abbreviations work (case-insensitive): "HM", "STLA", etc. * In single-company mode, company is automatic (ignore any company in input)`, inputSchema: { type: 'object', properties: { task: { type: 'string', description: 'Task description (e.g., "Conduit MCP: Security review")' }, duration: { type: 'string', description: 'Duration (e.g., "2h", "90m", "1.5h")' }, time: { type: 'string', description: 'Time when work was done (e.g., "14:30", "2 hours ago", omit for now)' }, date: { type: 'string', description: 'Date of work (e.g., "today", "yesterday", "2025-10-17", omit for today)' }, tags: { type: 'array', items: { type: 'string' }, description: 'Tags to categorize work (e.g., ["development", "security"])' }, company: { type: 'string', description: 'Company to log time for (optional, uses default if omitted)' } }, required: ['task', 'duration'] }, annotations: { title: 'Log Time', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, handler: withErrorHandler('logging time', async (args: LogTimeInput) => { // Resolve company (single-company mode auto-selects, multi-company requires explicit) const userInput = `${args.task || ''} ${args.duration || ''}`.trim(); const company = getCompanyForOperation(args.company, userInput); // Sanitize and validate task description const sanitizedTask = sanitizeTaskDescription(args.task); // Parse inputs const duration = parseDuration(args.duration); const date = parseDate(args.date); const time = parseTime(args.time, date); const tags = args.tags || []; // Create time entry const entry: TimeEntry = { time: formatTime(time), task: sanitizedTask, duration: duration.hours, tags, date: formatDate(date) }; // Save to markdown await markdownManager.addEntry(company, entry); // Load weekly summary for confirmation const { year, week } = getISOWeek(date); const summary = await markdownManager.getWeeklySummary(company, year, week); // Check for parse issues const parseIssues = markdownManager.getParseIssues(); // Build response let response = `✓ Logged ${duration.formatted} for "${sanitizedTask}" at ${entry.time}`; if (args.date && args.date !== 'today') { response += ` on ${entry.date}`; } if (tags.length > 0) { response += ` [${tags.map(t => '#' + t).join(' ')}]`; } response += '\n\n'; if (summary) { response += `**Week ${week} Status:**\n`; response += `• Total: ${summary.totalHours.toFixed(1)}h`; const config = await markdownManager.loadConfig(company); if (config.commitments.total) { const limit = config.commitments.total.limit; const stats = summaryCalculator.getCommitmentStats(summary.totalHours, limit); response += ` / ${limit}h (${stats.percentage}%)`; if (stats.status === 'over') { response += ` ⚠️ OVER LIMIT`; } else if (stats.status === 'approaching') { response += ` ⚠️ Close to limit`; } } response += '\n'; // Show commitment breakdown for (const [commitment, hours] of Object.entries(summary.byCommitment)) { const limit = config.commitments[commitment]?.limit; if (limit) { const stats = summaryCalculator.getCommitmentStats(hours, limit); const warning = stats.status !== 'within' ? ` ${stats.indicator}` : ''; response += `• ${capitalizeName(commitment)}: ${hours.toFixed(1)}h / ${limit}h (${stats.percentage}%)${warning}\n`; } } } // Add parse warnings if any if (parseIssues.warnings.length > 0) { response += '\n\n⚠️ **Parse Warnings:**\n'; for (const warning of parseIssues.warnings) { response += `• ${warning}\n`; } if (parseIssues.unparsedLines.length > 0 && parseIssues.unparsedLines.length <= 3) { response += '\nUnparsed lines:\n'; for (const { lineNumber, content } of parseIssues.unparsedLines) { response += ` Line ${lineNumber}: ${content}\n`; } } } return createTextResponse(response); }) });
• src/types/index.ts:62-69 (schema)

  TypeScript interface definition for LogTimeInput, matching the tool's input schema and used in the handler signature.
  export interface LogTimeInput { task: string; duration: string; // "2h", "90m", "1.5h", etc. time?: string; // "14:30", "2 hours ago", omit for now date?: string; // "today", "yesterday", "2025-10-17" tags?: string[]; company?: string; }