@yakirmar/mcp-toggl 1.1.0 → 1.2.0

package/dist/index.js

@@ -5,22 +5,45 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { config } from 'dotenv';
 import { TogglAPI, TimelineNotEnabledError, TogglAPIError } from './toggl-api.js';
 import { buildTimelineResponse } from './timeline.js';
+import { normalizeReportRows, summarizeByUser, userDisplayName } from './reports.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';
+import { OrganizationResolutionError, parseOrganizationId, resolveOrganizationId, } from './organization.js';
+import { buildTimeEntryInterval, filterHydratedEntries, pickDefined, getDateRange, generateDailyReport, generateWeeklyReport, formatReportForDisplay, secondsToHours, groupEntriesByProject, groupEntriesByWorkspace, generateProjectSummary, generateWorkspaceSummary, toLocalYMD, parseLocalYMD, localDateRangeFromArgs, reportDateWindow, } 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) {
+function requireId(value, field) {
     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.');
+        throw new Error(`${field} is required and must be a positive integer.`);
     }
     return parsed;
 }
+function requireName(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${field} is required and must be a non-empty string.`);
+    }
+    return value.trim();
+}
+// Fields a caller may set when creating or updating a project / client.
+const PROJECT_FIELDS = [
+    'name',
+    'client_id',
+    'active',
+    'is_private',
+    'billable',
+    'color',
+    'estimated_hours',
+    'start_date',
+    'end_date',
+    'currency',
+    'rate',
+];
+const CLIENT_FIELDS = ['name', 'notes', 'archived'];
 function jsonResponse(data) {
     return {
         content: [
@@ -54,10 +77,15 @@ function errorPayload(error) {
         payload.tip = error.tip;
         payload.available_workspaces = error.available_workspaces;
     }
+    if (error instanceof OrganizationResolutionError) {
+        payload.code = error.code;
+        payload.tip = error.tip;
+        payload.available_organizations = error.available_organizations;
+    }
     return payload;
 }
 // Version for CLI output and server metadata
-const VERSION = '1.1.0';
+const VERSION = '1.2.0';
 // Basic CLI flags: --help / -h and --version / -v
 const argv = process.argv.slice(2);
 if (argv.includes('--version') || argv.includes('-v')) {
@@ -67,7 +95,7 @@ if (argv.includes('--version') || argv.includes('-v')) {
 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` +
+        `  npx @yakirmar/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` +
@@ -77,7 +105,7 @@ if (argv.includes('--help') || argv.includes('-h')) {
         `  {\n` +
         `    "mcpServers": {\n` +
         `      "mcp-toggl": {\n` +
-        `        "command": "npx @verygoodplugins/mcp-toggl@latest",\n` +
+        `        "command": "npx @yakirmar/mcp-toggl@latest",\n` +
         `        "env": { "TOGGL_API_KEY": "your_api_key_here" }\n` +
         `      }\n` +
         `    }\n` +
@@ -88,7 +116,7 @@ if (argv.includes('--help') || argv.includes('-h')) {
         `      "servers": {\n` +
         `        "mcp-toggl": {\n` +
         `          "command": "npx",\n` +
-        `          "args": ["@verygoodplugins/mcp-toggl@latest"],\n` +
+        `          "args": ["@yakirmar/mcp-toggl@latest"],\n` +
         `          "env": { "TOGGL_API_KEY": "your_api_key_here" }\n` +
         `        }\n` +
         `      }\n` +
@@ -117,6 +145,7 @@ const cacheConfig = {
     batchSize: parseInt(process.env.TOGGL_BATCH_SIZE || '100'),
 };
 const defaultWorkspaceId = parseWorkspaceId(process.env.TOGGL_DEFAULT_WORKSPACE_ID);
+const defaultOrganizationId = parseOrganizationId(process.env.TOGGL_DEFAULT_ORG_ID);
 // Initialize API and cache
 const api = new TogglAPI(API_KEY);
 const cache = new CacheManager(cacheConfig);
@@ -148,6 +177,71 @@ async function resolveWorkspaceForTool(args, action) {
         action,
     });
 }
+async function resolveOrganizationForTool(args, action) {
+    return resolveOrganizationId({
+        explicitOrganizationId: args?.organization_id,
+        defaultOrganizationId,
+        getWorkspaces: () => cache.getWorkspaces(),
+        action,
+    });
+}
+// Workspace member id -> display name. Requires admin rights; when the token
+// lacks them we degrade to the username Toggl embeds in each report row rather
+// than failing the whole call.
+async function workspaceUserNames(workspaceId) {
+    try {
+        const users = await api.getWorkspaceUsers(workspaceId);
+        return new Map(users.map((user) => [user.id, userDisplayName(user)]));
+    }
+    catch (error) {
+        console.error(`Could not list users for workspace ${workspaceId} (admin rights required):`, error);
+        return new Map();
+    }
+}
+const REPORT_FILTER_FIELDS = [
+    'user_ids',
+    'project_ids',
+    'client_ids',
+    'tag_ids',
+    'task_ids',
+    'billable',
+    'description',
+];
+// Shared path for both team tools: pull the cross-user detailed report and the
+// reference data needed to make sense of the ids inside it. The rows themselves
+// are left untouched — the Reports API response schema is not published.
+async function fetchTeamReport(workspaceId, args) {
+    const window = reportDateWindow(args);
+    const params = {
+        ...pickDefined(args ?? {}, REPORT_FILTER_FIELDS),
+        start_date: window.start_date,
+        end_date: window.end_date,
+    };
+    const minMinutes = args?.min_duration_minutes;
+    if (typeof minMinutes === 'number')
+        params.min_duration_seconds = Math.round(minMinutes * 60);
+    const maxMinutes = args?.max_duration_minutes;
+    if (typeof maxMinutes === 'number')
+        params.max_duration_seconds = Math.round(maxMinutes * 60);
+    const [{ rows, truncated }, userNames, projects, clients] = await Promise.all([
+        api.searchDetailedReport(workspaceId, params),
+        workspaceUserNames(workspaceId),
+        cache.getProjects(workspaceId),
+        cache.getClients(workspaceId),
+    ]);
+    return {
+        rows,
+        window,
+        truncated,
+        users: [...userNames].map(([id, name]) => ({ id, name })),
+        projects: projects.map((project) => ({
+            id: project.id,
+            name: project.name,
+            client_id: project.client_id,
+        })),
+        clients: clients.map((client) => ({ id: client.id, name: client.name })),
+    };
+}
 // Create MCP server
 const server = new Server({
     name: 'mcp-toggl',
@@ -598,6 +692,326 @@ const tools = [
             },
         },
     },
+    {
+        name: 'toggl_create_project',
+        description: 'Create a project in a workspace. Only name is required; optionally attach it to a client and set billing, color, dates, and rate.',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Project name (required).' },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace ID. If omitted, uses TOGGL_DEFAULT_WORKSPACE_ID or the only available workspace; required when multiple workspaces exist.',
+                },
+                client_id: { type: 'number', description: 'Client to attach the project to (optional).' },
+                active: { type: 'boolean', description: 'Whether the project is active (default: true).' },
+                is_private: { type: 'boolean', description: 'Whether the project is private.' },
+                billable: { type: 'boolean', description: 'Whether the project is billable.' },
+                color: { type: 'string', description: 'Project color as a hex string, e.g. "#0b83d9".' },
+                estimated_hours: { type: 'number', description: 'Estimated hours for the project.' },
+                start_date: { type: 'string', description: 'Project start date (YYYY-MM-DD).' },
+                end_date: { type: 'string', description: 'Project end date (YYYY-MM-DD).' },
+                currency: { type: 'string', description: 'Currency code, e.g. "USD".' },
+                rate: { type: 'number', description: 'Hourly rate for the project.' },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'toggl_update_project',
+        description: 'Update an existing project. Provide project_id plus at least one field to change; omitted fields are left untouched.',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'number', description: 'Project to update (required).' },
+                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: { type: 'string', description: 'New project name.' },
+                client_id: {
+                    type: 'number',
+                    description: 'Move the project to this client.',
+                },
+                active: {
+                    type: 'boolean',
+                    description: 'Set false to archive the project, true to reactivate it.',
+                },
+                is_private: { type: 'boolean', description: 'Whether the project is private.' },
+                billable: { type: 'boolean', description: 'Whether the project is billable.' },
+                color: { type: 'string', description: 'Project color as a hex string.' },
+                estimated_hours: { type: 'number', description: 'Estimated hours for the project.' },
+                start_date: { type: 'string', description: 'Project start date (YYYY-MM-DD).' },
+                end_date: { type: 'string', description: 'Project end date (YYYY-MM-DD).' },
+                currency: { type: 'string', description: 'Currency code.' },
+                rate: { type: 'number', description: 'Hourly rate for the project.' },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'toggl_delete_project',
+        description: 'Delete a project by id. This cannot be undone; time entries on the project lose their project association. To keep history, prefer toggl_update_project with active: false to archive it instead.',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'number', description: 'Project to delete (required).' },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace ID. If omitted, uses TOGGL_DEFAULT_WORKSPACE_ID or the only available workspace; required when multiple workspaces exist.',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'toggl_create_client',
+        description: 'Create a client in a workspace.',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Client name (required).' },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace ID. If omitted, uses TOGGL_DEFAULT_WORKSPACE_ID or the only available workspace; required when multiple workspaces exist.',
+                },
+                notes: { type: 'string', description: 'Free-form notes for the client (optional).' },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'toggl_update_client',
+        description: 'Update an existing client. Provide client_id plus at least one field to change; omitted fields are left untouched. Set archived: true to archive.',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                client_id: { type: 'number', description: 'Client to update (required).' },
+                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: { type: 'string', description: 'New client name.' },
+                notes: { type: 'string', description: 'Free-form notes for the client.' },
+                archived: { type: 'boolean', description: 'Archive (true) or unarchive (false).' },
+            },
+            required: ['client_id'],
+        },
+    },
+    {
+        name: 'toggl_delete_client',
+        description: 'Delete a client by id. This cannot be undone; projects belonging to the client lose their client association. To keep history, prefer toggl_update_client with archived: true instead.',
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                client_id: { type: 'number', description: 'Client to delete (required).' },
+                workspace_id: {
+                    type: 'number',
+                    description: 'Workspace ID. If omitted, uses TOGGL_DEFAULT_WORKSPACE_ID or the only available workspace; required when multiple workspaces exist.',
+                },
+            },
+            required: ['client_id'],
+        },
+    },
+    // Team / admin tools (workspace-wide, require admin rights)
+    {
+        name: 'toggl_list_users',
+        description: 'List the members of a workspace (id, name, email, admin/owner flags). ADMIN ONLY: requires admin rights on the workspace; a non-admin token typically gets a 403. Use the returned ids as user_ids for toggl_team_entries / toggl_team_summary.',
+        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_org_users',
+        description: 'List the members of an ORGANIZATION (across all its workspaces), with richer data than toggl_list_users: org/workspace admin flags, active status, role, and how many workspaces each member belongs to. ORG ADMIN ONLY. If organization_id is omitted it is derived from your workspaces (or TOGGL_DEFAULT_ORG_ID). Use the returned user_id values as user_ids for toggl_team_entries / toggl_team_summary. Prefer toggl_list_users when you only care about one workspace.',
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                organization_id: {
+                    type: 'number',
+                    description: 'Organization ID. If omitted, uses TOGGL_DEFAULT_ORG_ID or the only organization derivable from your workspaces.',
+                },
+                filter: {
+                    type: 'string',
+                    description: 'Free-text filter on name/email, applied by Toggl.',
+                },
+                active_status: {
+                    type: 'string',
+                    description: 'Filter by active status as supported by Toggl, e.g. "active" or "inactive".',
+                },
+                only_admins: {
+                    type: 'boolean',
+                    description: 'Return only organization admins.',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_team_entries',
+        description: "Get time entries for OTHER users in the workspace (what your team worked on), via the Toggl Reports API. ADMIN ONLY: what you can see is enforced by Toggl — a non-admin token sees only its own data. PRIVACY: this returns teammates' entry descriptions. Filter with user_ids (from toggl_list_users), project_ids, client_ids, tag_ids, billable, or description. Date window via period or start_date/end_date (INCLUSIVE; defaults to the last 31 days). Entries are hydrated with user/project/client names and sorted newest-first.",
+        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.',
+                },
+                user_ids: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Only entries by these user ids. Omit for all visible users.',
+                },
+                project_ids: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Only entries on these project ids.',
+                },
+                client_ids: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Only entries for these client ids.',
+                },
+                tag_ids: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Only entries carrying these tag ids.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Filter by entry description (matched by Toggl).',
+                },
+                billable: { type: 'boolean', description: 'Only billable (true) or non-billable (false).' },
+                period: {
+                    type: 'string',
+                    enum: ['today', 'yesterday', 'week', 'lastWeek', 'month', 'lastMonth'],
+                    description: 'Predefined date window (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).',
+                },
+                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: 100,
+                    description: 'Maximum entries to return (default: 100, max: 1000).',
+                },
+            },
+        },
+    },
+    {
+        name: 'toggl_team_summary',
+        description: 'Total hours per user across the workspace for a period — who logged how much, how much was billable, and across how many projects. ADMIN ONLY: requires admin rights; a non-admin token sees only its own totals. Accepts the same filters and date window as toggl_team_entries (dates INCLUSIVE; defaults to the last 31 days). Sorted by total hours descending.',
+        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.',
+                },
+                user_ids: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Only these user ids. Omit for all visible users.',
+                },
+                project_ids: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Only entries on these project ids.',
+                },
+                client_ids: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Only entries for these client ids.',
+                },
+                billable: { type: 'boolean', description: 'Only billable (true) or non-billable (false).' },
+                period: {
+                    type: 'string',
+                    enum: ['today', 'yesterday', 'week', 'lastWeek', 'month', 'lastMonth'],
+                    description: 'Predefined date window (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).',
+                },
+            },
+        },
+    },
     // Cache management
     {
         name: 'toggl_warm_cache',
@@ -939,7 +1353,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 });
             }
             case 'toggl_delete_entry': {
-                const timeEntryId = requireEntryId(args?.time_entry_id);
+                const timeEntryId = requireId(args?.time_entry_id, 'time_entry_id');
                 let workspaceId = parseWorkspaceId(args?.workspace_id);
                 if (workspaceId === undefined) {
                     let existing;
@@ -1167,6 +1581,167 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'toggl_create_project': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'creating a project');
+                const name = requireName(args?.name, 'name');
+                const payload = {
+                    ...pickDefined(args ?? {}, PROJECT_FIELDS),
+                    name,
+                };
+                const project = await api.createProject(workspaceId, payload);
+                cache.invalidateProjects(workspaceId);
+                return jsonResponse({
+                    success: true,
+                    message: 'Project created',
+                    project,
+                });
+            }
+            case 'toggl_update_project': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'updating a project');
+                const projectId = requireId(args?.project_id, 'project_id');
+                const updates = pickDefined(args ?? {}, PROJECT_FIELDS);
+                if (Object.keys(updates).length === 0) {
+                    throw new Error(`Provide at least one field to update. Updatable fields: ${PROJECT_FIELDS.join(', ')}.`);
+                }
+                const project = await api.updateProject(workspaceId, projectId, updates);
+                cache.invalidateProjects(workspaceId);
+                return jsonResponse({
+                    success: true,
+                    message: 'Project updated',
+                    project,
+                });
+            }
+            case 'toggl_delete_project': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'deleting a project');
+                const projectId = requireId(args?.project_id, 'project_id');
+                await api.deleteProject(workspaceId, projectId);
+                cache.invalidateProjects(workspaceId);
+                return jsonResponse({
+                    success: true,
+                    message: 'Project deleted',
+                    project_id: projectId,
+                    workspace_id: workspaceId,
+                });
+            }
+            case 'toggl_create_client': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'creating a client');
+                const name = requireName(args?.name, 'name');
+                const payload = {
+                    ...pickDefined(args ?? {}, ['name', 'notes']),
+                    name,
+                };
+                const client = await api.createClient(workspaceId, payload);
+                cache.invalidateClients(workspaceId);
+                return jsonResponse({
+                    success: true,
+                    message: 'Client created',
+                    client,
+                });
+            }
+            case 'toggl_update_client': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'updating a client');
+                const clientId = requireId(args?.client_id, 'client_id');
+                const updates = pickDefined(args ?? {}, CLIENT_FIELDS);
+                if (Object.keys(updates).length === 0) {
+                    throw new Error(`Provide at least one field to update. Updatable fields: ${CLIENT_FIELDS.join(', ')}.`);
+                }
+                const client = await api.updateClient(workspaceId, clientId, updates);
+                cache.invalidateClients(workspaceId);
+                return jsonResponse({
+                    success: true,
+                    message: 'Client updated',
+                    client,
+                });
+            }
+            case 'toggl_delete_client': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'deleting a client');
+                const clientId = requireId(args?.client_id, 'client_id');
+                await api.deleteClient(workspaceId, clientId);
+                cache.invalidateClients(workspaceId);
+                return jsonResponse({
+                    success: true,
+                    message: 'Client deleted',
+                    client_id: clientId,
+                    workspace_id: workspaceId,
+                });
+            }
+            // Team / admin tools
+            case 'toggl_list_users': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'listing workspace users');
+                const users = await api.getWorkspaceUsers(workspaceId);
+                // Passed through exactly as Toggl returns them: this endpoint's response
+                // schema is not published, so reshaping it here risks dropping or
+                // mislabeling fields. Interpret the objects as-is.
+                return jsonResponse({
+                    workspace_id: workspaceId,
+                    count: users.length,
+                    note: 'users[] is Toggl\'s raw response, unmodified. The Toggl user id (usually "id" here) is what time entries are keyed by — pass it as user_ids to toggl_team_entries / toggl_team_summary.',
+                    users,
+                });
+            }
+            case 'toggl_list_org_users': {
+                const organizationId = await resolveOrganizationForTool(args, 'listing organization users');
+                const users = await api.getOrganizationUsers(organizationId, {
+                    filter: args?.filter,
+                    active_status: args?.active_status,
+                    only_admins: args?.only_admins,
+                });
+                // Raw passthrough — this endpoint's response schema is not published.
+                return jsonResponse({
+                    organization_id: organizationId,
+                    count: users.length,
+                    note: "users[] is Toggl's raw response, unmodified. CAUTION: these objects carry two different ids — the organization-user id (\"id\") and the Toggl user id (\"user_id\"). Only user_id matches time entries, so pass user_id (not id) as user_ids to toggl_team_entries / toggl_team_summary.",
+                    users,
+                });
+            }
+            case 'toggl_team_entries': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'reading team time entries');
+                const { rows, window, truncated, users, projects, clients } = await fetchTeamReport(workspaceId, args);
+                const requestedLimit = typeof args?.limit === 'number' ? args.limit : 100;
+                const limit = Math.min(Math.max(1, Math.floor(requestedLimit)), 1000);
+                const limited = rows.slice(0, limit);
+                // Rows are returned exactly as the Reports API produced them — its response
+                // schema is not published, so reshaping risks dropping fields. Reference
+                // lookups are supplied alongside so ids can be resolved to names.
+                return jsonResponse({
+                    workspace_id: workspaceId,
+                    start_date: window.start_date,
+                    end_date: window.end_date,
+                    row_count: rows.length,
+                    returned: limited.length,
+                    truncated: truncated || rows.length > limited.length,
+                    note: "rows[] is the Toggl Reports API response, unmodified. A row typically groups several time entries under a nested array. Use the lookups below to resolve user_id / project_id / client_id to names. Durations are in seconds.",
+                    lookups: { users, projects, clients },
+                    rows: limited,
+                });
+            }
+            case 'toggl_team_summary': {
+                const workspaceId = await resolveWorkspaceForTool(args, 'summarizing team time');
+                const { rows, window, truncated, users: workspaceUsers } = await fetchTeamReport(workspaceId, args);
+                // Unlike the other team tools this cannot be a raw passthrough: totalling
+                // hours per user requires knowing which field holds the duration.
+                const userNames = new Map(workspaceUsers.map((user) => [user.id, user.name]));
+                const entries = normalizeReportRows(rows, userNames);
+                const users = summarizeByUser(entries);
+                const totalSeconds = users.reduce((sum, user) => sum + user.total_seconds, 0);
+                // If Toggl returned rows but every duration came out zero, the field names
+                // this aggregation assumes are wrong. Say so instead of reporting "0 hours"
+                // as though the team logged nothing.
+                const schemaWarning = rows.length > 0 && totalSeconds === 0
+                    ? 'Toggl returned rows but no durations could be read from them, so these totals are unreliable. The report response shape may differ from what this aggregation expects. Use toggl_team_entries to inspect the raw rows.'
+                    : undefined;
+                return jsonResponse({
+                    workspace_id: workspaceId,
+                    start_date: window.start_date,
+                    end_date: window.end_date,
+                    user_count: users.length,
+                    total_hours: secondsToHours(totalSeconds),
+                    total_seconds: totalSeconds,
+                    truncated,
+                    ...(schemaWarning ? { schema_warning: schemaWarning } : {}),
+                    users,
+                });
+            }
             // Cache management
             case 'toggl_warm_cache': {
                 const workspaceId = await resolveWorkspaceForTool(args, 'warming the cache');