@yakirmar/mcp-toggl 1.1.0

package/dist/index.js

@@ -0,0 +1,1264 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { config } from 'dotenv';
+import { TogglAPI, TimelineNotEnabledError, TogglAPIError } from './toggl-api.js';
+import { buildTimelineResponse } from './timeline.js';
+import { CacheManager } from './cache-manager.js';
+import { WorkspaceResolutionError, parseWorkspaceId, resolveWorkspaceId, resolveProjectForClient, } from './workspace.js';
+import { buildTimeEntryInterval, filterHydratedEntries, getDateRange, generateDailyReport, generateWeeklyReport, formatReportForDisplay, secondsToHours, groupEntriesByProject, groupEntriesByWorkspace, generateProjectSummary, generateWorkspaceSummary, toLocalYMD, parseLocalYMD, localDateRangeFromArgs, } from './utils.js';
+function parseInclusiveEndDate(value) {
+    const date = parseLocalYMD(value);
+    date.setDate(date.getDate() + 1);
+    return date;
+}
+// Parse a required positive-integer entity id from tool arguments.
+function requireEntryId(value) {
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error('time_entry_id is required and must be a positive integer.');
+    }
+    return parsed;
+}
+function jsonResponse(data) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : 'An error occurred';
+}
+function errorPayload(error) {
+    const payload = {
+        error: true,
+        message: errorMessage(error),
+    };
+    if (error instanceof TogglAPIError) {
+        payload.code = error.code;
+        payload.status = error.status;
+        if (error.retry_after_seconds !== undefined) {
+            payload.retry_after_seconds = error.retry_after_seconds;
+        }
+        if (error.tip) {
+            payload.tip = error.tip;
+        }
+    }
+    if (error instanceof WorkspaceResolutionError) {
+        payload.code = error.code;
+        payload.tip = error.tip;
+        payload.available_workspaces = error.available_workspaces;
+    }
+    return payload;
+}
+// Version for CLI output and server metadata
+const VERSION = '1.1.0';
+// Basic CLI flags: --help / -h and --version / -v
+const argv = process.argv.slice(2);
+if (argv.includes('--version') || argv.includes('-v')) {
+    console.error(`mcp-toggl version ${VERSION}`);
+    process.exit(0);
+}
+if (argv.includes('--help') || argv.includes('-h')) {
+    console.error(`mcp-toggl - Toggl MCP Server\n\n` +
+        `Usage:\n` +
+        `  npx @verygoodplugins/mcp-toggl@latest [--help] [--version]\n\n` +
+        `Environment:\n` +
+        `  TOGGL_API_KEY                Required Toggl API token\n` +
+        `  TOGGL_DEFAULT_WORKSPACE_ID   Optional default workspace id\n` +
+        `  TOGGL_CACHE_TTL              Cache TTL in ms (default: 3600000)\n` +
+        `  TOGGL_CACHE_SIZE             Max cached entities (default: 1000)\n\n` +
+        `Claude Desktop (claude_desktop_config.json):\n` +
+        `  {\n` +
+        `    "mcpServers": {\n` +
+        `      "mcp-toggl": {\n` +
+        `        "command": "npx @verygoodplugins/mcp-toggl@latest",\n` +
+        `        "env": { "TOGGL_API_KEY": "your_api_key_here" }\n` +
+        `      }\n` +
+        `    }\n` +
+        `  }\n\n` +
+        `Cursor (~/.cursor/mcp.json):\n` +
+        `  {\n` +
+        `    "mcp": {\n` +
+        `      "servers": {\n` +
+        `        "mcp-toggl": {\n` +
+        `          "command": "npx",\n` +
+        `          "args": ["@verygoodplugins/mcp-toggl@latest"],\n` +
+        `          "env": { "TOGGL_API_KEY": "your_api_key_here" }\n` +
+        `        }\n` +
+        `      }\n` +
+        `    }\n` +
+        `  }\n`);
+    process.exit(0);
+}
+// Load environment variables
+config({ quiet: true });
+// Validate required environment variables
+// Support a few aliases for convenience/backward-compat
+const RAW_API_KEY = process.env.TOGGL_API_KEY || process.env.TOGGL_API_TOKEN || process.env.TOGGL_TOKEN;
+const API_KEY = RAW_API_KEY?.trim();
+if (!API_KEY) {
+    console.error('Missing required environment variable: TOGGL_API_KEY');
+    console.error('Also accepted: TOGGL_API_TOKEN or TOGGL_TOKEN');
+    process.exit(1);
+}
+if (process.env.TOGGL_API_TOKEN || process.env.TOGGL_TOKEN) {
+    console.warn('Using TOGGL_API_TOKEN/TOGGL_TOKEN. Prefer TOGGL_API_KEY going forward.');
+}
+// Initialize configuration
+const cacheConfig = {
+    ttl: parseInt(process.env.TOGGL_CACHE_TTL || '3600000'),
+    maxSize: parseInt(process.env.TOGGL_CACHE_SIZE || '1000'),
+    batchSize: parseInt(process.env.TOGGL_BATCH_SIZE || '100'),
+};
+const defaultWorkspaceId = parseWorkspaceId(process.env.TOGGL_DEFAULT_WORKSPACE_ID);
+// Initialize API and cache
+const api = new TogglAPI(API_KEY);
+const cache = new CacheManager(cacheConfig);
+cache.setAPI(api);
+// Track if cache has been warmed
+let cacheWarmed = false;
+// Helper to ensure cache is warm
+async function ensureCache() {
+    if (!cacheWarmed) {
+        try {
+            const workspaces = await cache.getWorkspaces();
+            const singleWorkspaceId = workspaces.length === 1 ? workspaces[0].id : undefined;
+            const workspaceIdToWarm = defaultWorkspaceId || singleWorkspaceId;
+            if (workspaceIdToWarm) {
+                await cache.warmCache(workspaceIdToWarm);
+            }
+            cacheWarmed = true;
+        }
+        catch (error) {
+            console.error('Failed to warm cache:', error);
+        }
+    }
+}
+async function resolveWorkspaceForTool(args, action) {
+    return resolveWorkspaceId({
+        explicitWorkspaceId: args?.workspace_id,
+        defaultWorkspaceId,
+        getWorkspaces: () => cache.getWorkspaces(),
+        action,
+    });
+}
+// Create MCP server
+const server = new Server({
+    name: 'mcp-toggl',
+    version: VERSION,
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Define tool schemas
+const tools = [
+    // Health/authentication
+    {
+        name: 'toggl_check_auth',
+        description: 'Verify Toggl API connectivity and authentication is valid',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    // Time tracking tools
+    {
+        name: 'toggl_get_time_entries',
+        description: 'Get time entries with optional date range filters. Returns hydrated entries with project/workspace names.',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                period: {
+                    type: 'string',
+                    enum: ['today', 'yesterday', 'week', 'lastWeek', 'month', 'lastMonth'],
+                    description: 'Predefined period to fetch entries for',
+                },
+                start_date: {
+                    type: 'string',
+                    description: 'Start date (YYYY-MM-DD format, inclusive, local timezone)',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'End date (YYYY-MM-DD format, inclusive, local timezone)',
+                },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Filter by workspace ID',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Filter by project ID',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_get_current_entry',
+        description: 'Get the currently running time entry, if any',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'toggl_start_timer',
+        description: 'Start a new time entry timer',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                description: {
+                    type: 'string',
+                    description: 'Description of the time entry',
+                },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace ID. If omitted, uses TOGGL_DEFAULT_WORKSPACE_ID or the only available workspace; required when multiple workspaces exist.',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (optional)',
+                },
+                task_id: {
+                    type: 'number',
+                    description: 'Task ID (optional)',
+                },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Tags for the entry',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_stop_timer',
+        description: 'Stop the currently running timer',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'toggl_create_entry',
+        description: 'Create a completed (past) time entry for a project, optionally scoped to a client, with a start time and either an end time or a length in minutes. ' +
+            'Times are ISO 8601 datetimes: use Z or an offset (2026-07-11T09:00:00Z / 2026-07-11T09:00:00+03:00) for an absolute time, omit the offset for the host local timezone, or pass a bare YYYY-MM-DD for local midnight. ' +
+            'Provide exactly one of end or duration_minutes. Use toggl_start_timer instead to begin a currently-running timer.',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                description: {
+                    type: 'string',
+                    description: 'Description of the time entry',
+                },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace ID. If omitted, uses TOGGL_DEFAULT_WORKSPACE_ID or the only available workspace; required when multiple workspaces exist.',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project to attach the entry to (optional).',
+                },
+                client_id: {
+                    type: 'number',
+                    description: 'Client to attach the entry to (optional). Toggl entries attach to a project, not a client directly: when set without project_id the client must have exactly one project; when both are set the project must belong to this client.',
+                },
+                task_id: {
+                    type: 'number',
+                    description: 'Task ID (optional).',
+                },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Tags for the entry',
+                },
+                billable: {
+                    type: 'boolean',
+                    description: 'Whether the entry is billable (optional).',
+                },
+                start: {
+                    type: 'string',
+                    description: 'Start time as an ISO 8601 datetime (required).',
+                },
+                end: {
+                    type: 'string',
+                    description: 'End time as an ISO 8601 datetime. Provide this or duration_minutes.',
+                },
+                duration_minutes: {
+                    type: 'number',
+                    description: 'Length of the entry in minutes. Provide this or end.',
+                },
+            },
+            required: ['start'],
+        },
+    },
+    {
+        name: 'toggl_search_entries',
+        description: 'Search time entries and return matches including their id (use the id with toggl_delete_entry). ' +
+            'All filters combine with AND; text filters (description, project_name, client_name, tag) are case-insensitive substring matches. ' +
+            'Date window: pass period or start_date/end_date (YYYY-MM-DD, inclusive, local); defaults to roughly the last 31 days. ' +
+            'start_after/start_before further narrow by entry start time (ISO 8601 datetime). ' +
+            'Results are hydrated with project/workspace/client/tag names and sorted newest-first.',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                description: {
+                    type: 'string',
+                    description: 'Case-insensitive substring match on the entry description.',
+                },
+                project_name: {
+                    type: 'string',
+                    description: 'Case-insensitive substring match on the project name.',
+                },
+                client_name: {
+                    type: 'string',
+                    description: 'Case-insensitive substring match on the client name.',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Exact project id to match.',
+                },
+                client_id: {
+                    type: 'number',
+                    description: 'Exact client id to match.',
+                },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Exact workspace id to match.',
+                },
+                tag: {
+                    type: 'string',
+                    description: 'Case-insensitive substring match against any of the entry tags.',
+                },
+                billable: {
+                    type: 'boolean',
+                    description: 'Match only billable (true) or non-billable (false) entries.',
+                },
+                period: {
+                    type: 'string',
+                    enum: ['today', 'yesterday', 'week', 'lastWeek', 'month', 'lastMonth'],
+                    description: 'Predefined date window to search within (alternative to start_date/end_date).',
+                },
+                start_date: {
+                    type: 'string',
+                    description: 'Window start (YYYY-MM-DD, inclusive, local timezone).',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'Window end (YYYY-MM-DD, inclusive, local timezone).',
+                },
+                start_after: {
+                    type: 'string',
+                    description: 'Only entries starting at or after this ISO 8601 datetime.',
+                },
+                start_before: {
+                    type: 'string',
+                    description: 'Only entries starting at or before this ISO 8601 datetime.',
+                },
+                min_duration_minutes: {
+                    type: 'number',
+                    description: 'Only entries at least this many minutes long.',
+                },
+                max_duration_minutes: {
+                    type: 'number',
+                    description: 'Only entries at most this many minutes long.',
+                },
+                limit: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 1000,
+                    default: 50,
+                    description: 'Maximum number of matches to return (default: 50, max: 1000).',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_delete_entry',
+        description: 'Delete a time entry by its id. If workspace_id is omitted it is resolved from the entry itself. ' +
+            'Use toggl_search_entries first to find the id when you do not already have it. This cannot be undone.',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                time_entry_id: {
+                    type: 'number',
+                    description: 'Id of the time entry to delete (required).',
+                },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace the entry belongs to. If omitted, it is looked up from the entry.',
+                },
+            },
+            required: ['time_entry_id'],
+        },
+    },
+    // Reporting tools
+    {
+        name: 'toggl_daily_report',
+        description: 'Generate a daily report with hours by project and workspace',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                date: {
+                    type: 'string',
+                    description: 'Date for report (YYYY-MM-DD format, defaults to today)',
+                },
+                format: {
+                    type: 'string',
+                    enum: ['json', 'text'],
+                    description: 'Output format (default: json)',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_weekly_report',
+        description: 'Generate a weekly report with daily breakdown and project summaries',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                week_offset: {
+                    type: 'number',
+                    description: 'Week offset from current week (0 = this week, -1 = last week)',
+                },
+                format: {
+                    type: 'string',
+                    enum: ['json', 'text'],
+                    description: 'Output format (default: json)',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_project_summary',
+        description: 'Get total hours per project for a date range',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                period: {
+                    type: 'string',
+                    enum: ['week', 'lastWeek', 'month', 'lastMonth'],
+                    description: 'Predefined period',
+                },
+                start_date: {
+                    type: 'string',
+                    description: 'Start date (YYYY-MM-DD format, inclusive, local timezone)',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'End date (YYYY-MM-DD format, inclusive, local timezone)',
+                },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Filter by workspace ID',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_workspace_summary',
+        description: 'Get total hours per workspace for a date range',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                period: {
+                    type: 'string',
+                    enum: ['week', 'lastWeek', 'month', 'lastMonth'],
+                    description: 'Predefined period',
+                },
+                start_date: {
+                    type: 'string',
+                    description: 'Start date (YYYY-MM-DD format, inclusive, local timezone)',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'End date (YYYY-MM-DD format, inclusive, local timezone)',
+                },
+            },
+        },
+    },
+    // Management tools
+    {
+        name: 'toggl_list_workspaces',
+        description: 'List all available workspaces',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'toggl_list_projects',
+        description: 'List projects for a workspace',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace ID. If omitted, uses TOGGL_DEFAULT_WORKSPACE_ID or the only available workspace; required when multiple workspaces exist.',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_list_clients',
+        description: 'List clients for a workspace',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace ID. If omitted, uses TOGGL_DEFAULT_WORKSPACE_ID or the only available workspace; required when multiple workspaces exist.',
+                },
+            },
+        },
+    },
+    // Cache management
+    {
+        name: 'toggl_warm_cache',
+        description: 'Pre-fetch and cache workspace, project, client, and tag data for better performance',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace ID to warm. If omitted, uses TOGGL_DEFAULT_WORKSPACE_ID or the only available workspace; required when multiple workspaces exist.',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_cache_stats',
+        description: 'Get cache statistics and performance metrics',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'toggl_clear_cache',
+        description: 'Clear all cached data',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'toggl_get_timeline',
+        description: 'Get Toggl Desktop activity timeline showing application usage. PRIVACY NOTE: raw events include window titles that may contain sensitive document names, email subjects, chat text, URLs, OAuth pages, or database names; use include_events: false for privacy-conscious summary-only usage. Requires Toggl Track Desktop timeline sync to be enabled. Response semantics: summary is { [appName: string]: total_seconds }; total_events is the post-filter event count; returned_events is the returned events array length; truncated means only the events array was limited, never the summary. limit does not affect summary calculation. total_seconds is canonical; total_hours is rounded to 4 decimals for display.',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                period: {
+                    type: 'string',
+                    enum: ['today', 'yesterday', 'week', 'lastWeek', 'month', 'lastMonth'],
+                    description: 'Predefined period (alternative to start_date/end_date)',
+                },
+                start_date: {
+                    type: 'string',
+                    description: 'Start date (YYYY-MM-DD format, inclusive, local timezone)',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'End date (YYYY-MM-DD format, inclusive, local timezone)',
+                },
+                app: {
+                    type: 'string',
+                    description: 'Filter by application name, case-insensitive partial match',
+                },
+                include_events: {
+                    type: 'boolean',
+                    description: 'Include raw events array (default: true). Set false for summary only.',
+                },
+                redact_titles: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'When true, returned events keep app name, timestamps, duration, idle state, and desktop_id, but set title to null.',
+                },
+                limit: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 1000,
+                    default: 50,
+                    description: 'Maximum events to return in events array (default: 50, max: 1000). Does not affect summary calculation.',
+                },
+            },
+        },
+    },
+];
+// Handle tool listing
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            // Health/authentication
+            case 'toggl_check_auth': {
+                const me = await api.getMe();
+                const workspaces = await cache.getWorkspaces();
+                const maskEmail = (e) => {
+                    if (!e)
+                        return undefined;
+                    const [user, domain] = e.split('@');
+                    if (!domain)
+                        return '***';
+                    const u = user.length <= 2 ? '*'.repeat(user.length) : `${user[0]}***${user.slice(-1)}`;
+                    return `${u}@${domain}`;
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                authenticated: true,
+                                user: {
+                                    id: me.id,
+                                    email: maskEmail(me.email),
+                                    fullname: me.fullname,
+                                },
+                                workspaces: workspaces.map((w) => ({ id: w.id, name: w.name })),
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Time tracking tools
+            case 'toggl_get_time_entries': {
+                await ensureCache();
+                let entries;
+                if (args?.period) {
+                    const range = getDateRange(args.period);
+                    entries = await api.getTimeEntriesForDateRange(range.start, range.end);
+                }
+                else if (args?.start_date || args?.end_date) {
+                    const start = args?.start_date ? parseLocalYMD(args.start_date) : new Date();
+                    start.setHours(0, 0, 0, 0);
+                    const end = args?.end_date ? parseInclusiveEndDate(args.end_date) : new Date();
+                    if (!args?.end_date) {
+                        end.setHours(0, 0, 0, 0);
+                        end.setDate(end.getDate() + 1);
+                    }
+                    entries = await api.getTimeEntriesForDateRange(start, end);
+                }
+                else {
+                    entries = await api.getTimeEntriesForToday();
+                }
+                // Filter by workspace/project if specified
+                if (args?.workspace_id) {
+                    entries = entries.filter((e) => e.workspace_id === args.workspace_id);
+                }
+                if (args?.project_id) {
+                    entries = entries.filter((e) => e.project_id === args.project_id);
+                }
+                // Hydrate with names
+                const hydrated = await cache.hydrateTimeEntries(entries);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                count: hydrated.length,
+                                entries: hydrated,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_get_current_entry': {
+                const entry = await api.getCurrentTimeEntry();
+                if (!entry) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    running: false,
+                                    message: 'No timer currently running',
+                                }),
+                            },
+                        ],
+                    };
+                }
+                await ensureCache();
+                const hydrated = await cache.hydrateTimeEntries([entry]);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                running: true,
+                                entry: hydrated[0],
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_start_timer': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'starting a timer');
+                const entry = await api.startTimer(workspaceId, args?.description, args?.project_id, args?.task_id, args?.tags);
+                await ensureCache();
+                const hydrated = await cache.hydrateTimeEntries([entry]);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: 'Timer started',
+                                entry: hydrated[0],
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_stop_timer': {
+                const current = await api.getCurrentTimeEntry();
+                if (!current) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    success: false,
+                                    message: 'No timer currently running',
+                                }),
+                            },
+                        ],
+                    };
+                }
+                const stopped = await api.stopTimer(current.workspace_id, current.id);
+                await ensureCache();
+                const hydrated = await cache.hydrateTimeEntries([stopped]);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: 'Timer stopped',
+                                entry: hydrated[0],
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_create_entry': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'creating a time entry');
+                let projectId = args?.project_id;
+                const clientId = args?.client_id;
+                if (clientId !== undefined) {
+                    const projects = await cache.getProjects(workspaceId);
+                    projectId = resolveProjectForClient(projects, clientId, projectId);
+                }
+                const { start, stop, duration } = buildTimeEntryInterval({
+                    start: args?.start,
+                    end: args?.end,
+                    duration_minutes: args?.duration_minutes,
+                });
+                const created = await api.createTimeEntry(workspaceId, {
+                    description: args?.description,
+                    project_id: projectId,
+                    task_id: args?.task_id,
+                    tags: args?.tags,
+                    billable: args?.billable,
+                    start,
+                    stop,
+                    duration,
+                });
+                await ensureCache();
+                const hydrated = await cache.hydrateTimeEntries([created]);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: 'Time entry created',
+                                entry: hydrated[0],
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_search_entries': {
+                await ensureCache();
+                // Default to roughly the last 31 days; override with period or explicit dates.
+                const todayMidnight = new Date();
+                todayMidnight.setHours(0, 0, 0, 0);
+                let start = new Date(todayMidnight);
+                start.setDate(start.getDate() - 31);
+                let end = new Date(todayMidnight);
+                end.setDate(end.getDate() + 1);
+                if (args?.period) {
+                    const range = getDateRange(args.period);
+                    start = range.start;
+                    end = range.end;
+                }
+                else {
+                    if (args?.start_date)
+                        start = parseLocalYMD(args.start_date);
+                    if (args?.end_date)
+                        end = parseInclusiveEndDate(args.end_date);
+                }
+                const entries = await api.getTimeEntriesForDateRange(start, end);
+                const hydrated = await cache.hydrateTimeEntries(entries);
+                const matches = filterHydratedEntries(hydrated, {
+                    description: args?.description,
+                    project_name: args?.project_name,
+                    client_name: args?.client_name,
+                    project_id: args?.project_id,
+                    client_id: args?.client_id,
+                    workspace_id: args?.workspace_id,
+                    tag: args?.tag,
+                    billable: args?.billable,
+                    start_after: args?.start_after,
+                    start_before: args?.start_before,
+                    min_duration_minutes: args?.min_duration_minutes,
+                    max_duration_minutes: args?.max_duration_minutes,
+                });
+                // Newest first so the most likely deletion target is at the top.
+                matches.sort((a, b) => new Date(b.start).getTime() - new Date(a.start).getTime());
+                const requestedLimit = typeof args?.limit === 'number' ? args.limit : 50;
+                const limit = Math.min(Math.max(1, Math.floor(requestedLimit)), 1000);
+                const limited = matches.slice(0, limit);
+                return jsonResponse({
+                    count: matches.length,
+                    returned: limited.length,
+                    truncated: matches.length > limited.length,
+                    entries: limited,
+                });
+            }
+            case 'toggl_delete_entry': {
+                const timeEntryId = requireEntryId(args?.time_entry_id);
+                let workspaceId = parseWorkspaceId(args?.workspace_id);
+                if (workspaceId === undefined) {
+                    let existing;
+                    try {
+                        existing = await api.getTimeEntry(timeEntryId);
+                    }
+                    catch (error) {
+                        throw new Error(`Time entry ${timeEntryId} was not found. Provide workspace_id, ` +
+                            `or use toggl_search_entries to find a valid id.`, { cause: error });
+                    }
+                    if (!existing?.workspace_id) {
+                        throw new Error(`Time entry ${timeEntryId} was not found. Use toggl_search_entries to find a valid id.`);
+                    }
+                    workspaceId = existing.workspace_id;
+                }
+                await api.deleteTimeEntry(workspaceId, timeEntryId);
+                return jsonResponse({
+                    success: true,
+                    message: 'Time entry deleted',
+                    time_entry_id: timeEntryId,
+                    workspace_id: workspaceId,
+                });
+            }
+            // Reporting tools
+            case 'toggl_daily_report': {
+                await ensureCache();
+                const date = args?.date ? parseLocalYMD(args.date) : new Date();
+                date.setHours(0, 0, 0, 0);
+                const nextDay = new Date(date);
+                nextDay.setDate(nextDay.getDate() + 1);
+                const entries = await api.getTimeEntriesForDateRange(date, nextDay);
+                const hydrated = await cache.hydrateTimeEntries(entries);
+                const report = generateDailyReport(toLocalYMD(date), hydrated);
+                if (args?.format === 'text') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: formatReportForDisplay(report),
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(report, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_weekly_report': {
+                await ensureCache();
+                const weekOffset = args?.week_offset || 0;
+                const entries = await api.getTimeEntriesForWeek(weekOffset);
+                const hydrated = await cache.hydrateTimeEntries(entries);
+                // Calculate week boundaries in local time.
+                const today = new Date();
+                today.setHours(0, 0, 0, 0);
+                const dayOfWeek = today.getDay();
+                const diff = today.getDate() - dayOfWeek + (dayOfWeek === 0 ? -6 : 1);
+                const monday = new Date(today);
+                monday.setDate(diff + weekOffset * 7);
+                const sunday = new Date(monday);
+                sunday.setDate(sunday.getDate() + 6);
+                const report = generateWeeklyReport(monday, sunday, hydrated);
+                if (args?.format === 'text') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: formatReportForDisplay(report),
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(report, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_project_summary': {
+                await ensureCache();
+                let entries;
+                if (args?.period) {
+                    const range = getDateRange(args.period);
+                    entries = await api.getTimeEntriesForDateRange(range.start, range.end);
+                }
+                else if (args?.start_date && args?.end_date) {
+                    const start = parseLocalYMD(args.start_date);
+                    const end = parseInclusiveEndDate(args.end_date);
+                    entries = await api.getTimeEntriesForDateRange(start, end);
+                }
+                else {
+                    // Default to current week
+                    entries = await api.getTimeEntriesForWeek(0);
+                }
+                if (args?.workspace_id) {
+                    entries = entries.filter((e) => e.workspace_id === args.workspace_id);
+                }
+                const hydrated = await cache.hydrateTimeEntries(entries);
+                const byProject = groupEntriesByProject(hydrated);
+                const summaries = [];
+                byProject.forEach((projectEntries, projectName) => {
+                    summaries.push(generateProjectSummary(projectName, projectEntries));
+                });
+                // Sort by total hours descending
+                summaries.sort((a, b) => b.total_seconds - a.total_seconds);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                project_count: summaries.length,
+                                total_hours: secondsToHours(summaries.reduce((t, s) => t + s.total_seconds, 0)),
+                                projects: summaries,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_workspace_summary': {
+                await ensureCache();
+                let entries;
+                if (args?.period) {
+                    const range = getDateRange(args.period);
+                    entries = await api.getTimeEntriesForDateRange(range.start, range.end);
+                }
+                else if (args?.start_date && args?.end_date) {
+                    const start = parseLocalYMD(args.start_date);
+                    const end = parseInclusiveEndDate(args.end_date);
+                    entries = await api.getTimeEntriesForDateRange(start, end);
+                }
+                else {
+                    // Default to current week
+                    entries = await api.getTimeEntriesForWeek(0);
+                }
+                const hydrated = await cache.hydrateTimeEntries(entries);
+                const byWorkspace = groupEntriesByWorkspace(hydrated);
+                const summaries = [];
+                byWorkspace.forEach((wsEntries, wsName) => {
+                    const wsId = wsEntries[0]?.workspace_id || 0;
+                    summaries.push(generateWorkspaceSummary(wsName, wsId, wsEntries));
+                });
+                // Sort by total hours descending
+                summaries.sort((a, b) => b.total_seconds - a.total_seconds);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                workspace_count: summaries.length,
+                                total_hours: secondsToHours(summaries.reduce((t, s) => t + s.total_seconds, 0)),
+                                workspaces: summaries,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Management tools
+            case 'toggl_list_workspaces': {
+                const workspaces = await cache.getWorkspaces();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                count: workspaces.length,
+                                workspaces: workspaces.map((ws) => ({
+                                    id: ws.id,
+                                    name: ws.name,
+                                    premium: ws.premium,
+                                    default_currency: ws.default_currency,
+                                })),
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_list_projects': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'listing projects');
+                const projects = await cache.getProjects(workspaceId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                workspace_id: workspaceId,
+                                count: projects.length,
+                                projects: projects.map((p) => ({
+                                    id: p.id,
+                                    name: p.name,
+                                    active: p.active,
+                                    billable: p.billable,
+                                    color: p.color,
+                                    client_id: p.client_id,
+                                })),
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_list_clients': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'listing clients');
+                const clients = await cache.getClients(workspaceId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                workspace_id: workspaceId,
+                                count: clients.length,
+                                clients: clients.map((c) => ({
+                                    id: c.id,
+                                    name: c.name,
+                                    archived: c.archived,
+                                })),
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Cache management
+            case 'toggl_warm_cache': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'warming the cache');
+                await cache.warmCache(workspaceId);
+                cacheWarmed = true;
+                const stats = cache.getStats();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: 'Cache warmed successfully',
+                                stats,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_cache_stats': {
+                const stats = cache.getStats();
+                const hitRate = stats.hits + stats.misses > 0
+                    ? Math.round((stats.hits / (stats.hits + stats.misses)) * 100)
+                    : 0;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ...stats,
+                                hit_rate: `${hitRate}%`,
+                                cache_warmed: cacheWarmed,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_clear_cache': {
+                cache.clearCache();
+                cacheWarmed = false;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: 'Cache cleared successfully',
+                            }),
+                        },
+                    ],
+                };
+            }
+            case 'toggl_get_timeline': {
+                localDateRangeFromArgs(args);
+                let allEvents;
+                try {
+                    allEvents = await api.getTimeline();
+                }
+                catch (error) {
+                    if (error instanceof TimelineNotEnabledError) {
+                        return jsonResponse({
+                            enabled: false,
+                            total_events: 0,
+                            returned_events: 0,
+                            truncated: false,
+                            total_seconds: 0,
+                            total_hours: 0,
+                            summary: {},
+                            events: [],
+                            message: 'Toggl Desktop timeline is not enabled yet. Open the Toggl Track Desktop app for Mac, enable timeline/activity tracking and sync, then retry this tool after the app has uploaded activity data.',
+                        });
+                    }
+                    throw error;
+                }
+                return jsonResponse(buildTimelineResponse(allEvents, args));
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return jsonResponse(errorPayload(error));
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Toggl MCP server running');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map