getUserTimeEntriesByName
Find and list time entries for a specific user by name with partial matching. Filter results by date range using optional start and end parameters.
Instructions
List time entries for a user by name (case-insensitive, partial match allowed). Optional: start, end (ISO8601).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| userName | Yes | User name (partial/case-insensitive) | |
| start | No | Start date (ISO8601, optional) | |
| end | No | End date (ISO8601, optional) |
Implementation Reference
- src/handlers.ts:297-329 (handler)Handler function for the 'getUserTimeEntriesByName' tool. It finds a user by partial, case-insensitive name match from the workspace users, then fetches their time entries for the optional start/end date range using the Clockify API.
case "getUserTimeEntriesByName": { const { userName, start, end } = request.params.arguments || {}; if (!userName || typeof userName !== "string") { throw new Error("userName is required"); } // Fetch users const users = await clockifyFetch(`/workspaces/${workspaceId}/users`); // Define a type for user type User = { id: string; name: string }; // Find user by name (case-insensitive, partial match) const userMatch = (users as User[]).find( (u) => u.name && u.name.toLowerCase().includes(userName.toLowerCase()), ); if (!userMatch) { throw new Error(`No user found matching name: ${userName}`); } let url = `/workspaces/${workspaceId}/user/${userMatch.id}/time-entries`; const params = []; if (typeof start === "string" && start) params.push(`start=${encodeURIComponent(start)}`); if (typeof end === "string" && end) params.push(`end=${encodeURIComponent(end)}`); if (params.length) url += `?${params.join("&")}`; const entries = await clockifyFetch(url); return { content: [ { type: "text", text: JSON.stringify(entries, null, 2), }, ], }; } - src/handlers.ts:127-149 (schema)Input schema definition for the 'getUserTimeEntriesByName' tool, including parameters userName (required), start, end (optional).
{ name: "getUserTimeEntriesByName", description: "List time entries for a user by name (case-insensitive, partial match allowed). Optional: start, end (ISO8601).", inputSchema: { type: "object", properties: { userName: { type: "string", description: "User name (partial/case-insensitive)", }, start: { type: "string", description: "Start date (ISO8601, optional)", }, end: { type: "string", description: "End date (ISO8601, optional)", }, }, required: ["userName"], }, }, - src/index.ts:43-49 (registration)Registers the tool listing and calling handlers with the MCP server, which exposes and implements the 'getUserTimeEntriesByName' tool among others.
server.setRequestHandler(ListToolsRequestSchema, listToolsHandler); /** * Handler for the create_note tool. * Creates a new note with the provided title and content, and returns success message. */ server.setRequestHandler(CallToolRequestSchema, callToolHandler); - src/handlers.ts:13-32 (helper)Helper function to make authenticated API calls to Clockify, used by the tool handler to fetch users and time entries.
async function clockifyFetch(endpoint: string, options: RequestInit = {}) { const apiKey = getApiKey(); const baseUrl = "https://api.clockify.me/api/v1"; const url = endpoint.startsWith("http") ? endpoint : `${baseUrl}${endpoint}`; const headers = { "X-Api-Key": apiKey, "Content-Type": "application/json", ...(options.headers || {}), }; const response = await fetch(url, { ...options, headers }); if (!response.ok) { const text = await response.text(); console.error( `[Error] Clockify API ${url} failed: ${response.status} ${text}`, ); throw new Error(`Clockify API error: ${response.status} ${text}`); } return response.json(); }