activitywatch_get_events

Instructions

Implementation Reference

• src/rawEvents.ts:32-127 (handler)

  The main handler function that fetches raw events from an ActivityWatch bucket via the API, constructs query params, makes axios GET request, returns JSON data or detailed error messages.

    handler: async (args: { bucketId: string; limit?: number; start?: string; end?: string }) => {
      try {
        // Construct query parameters
        const params: Record<string, string> = {};
        
        if (args.limit) {
          params.limit = String(args.limit);
        }
        
        if (args.start) {
          params.start = args.start;
        }
        
        if (args.end) {
          params.end = args.end;
        }
        
        // Build query string
        const queryString = Object.entries(params)
          .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
          .join('&');
        
        const url = `${AW_API_BASE}/buckets/${encodeURIComponent(args.bucketId)}/events${queryString ? `?${queryString}` : ''}`;
        
        console.error(`Fetching events from: ${url}`);
        
        // Make the request
        const response = await axios.get(url);
        
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(response.data, null, 2)
            }
          ]
        };
      } catch (error) {
        console.error("Error in raw events tool:", error);
        
        // Check if the error is an Axios error with a response property
        if (axios.isAxiosError(error) && error.response) {
          const statusCode = error.response.status;
          let errorMessage = `Failed to fetch events: ${error.message} (Status code: ${statusCode})`;
          
          // Include response data if available
          if (error.response.data) {
            const errorDetails = typeof error.response.data === 'object'
              ? JSON.stringify(error.response.data)
              : String(error.response.data);
            errorMessage += `\nDetails: ${errorDetails}`;
          }
          
          // Special handling for 404 errors - likely bucket not found
          if (statusCode === 404) {
            errorMessage = `Bucket not found: ${args.bucketId}
            
  Please check that you've entered the correct bucket ID. You can get a list of available buckets using the activitywatch_list_buckets tool.
  `;
          }
          
          return {
            content: [{ type: "text", text: errorMessage }],
            isError: true
          };
        } 
        // Handle network errors or other axios errors without response
        else if (axios.isAxiosError(error)) {
          const errorMessage = `Failed to fetch events: ${error.message}
  
  This appears to be a network or connection error. Please check:
  - The ActivityWatch server is running
  - The API base URL is correct (currently: ${AW_API_BASE})
  - No firewall or network issues are blocking the connection
  `;
          return {
            content: [{ type: "text", text: errorMessage }],
            isError: true
          };
        } 
        // Handle non-axios errors
        else if (error instanceof Error) {
          return {
            content: [{ type: "text", text: `Failed to fetch events: ${error.message}` }],
            isError: true
          };
        } 
        // Fallback for unknown errors
        else {
          return {
            content: [{ type: "text", text: "Failed to fetch events: Unknown error" }],
            isError: true
          };
        }
      }
    }

• src/rawEvents.ts:5-26 (schema)

  Input schema defining the tool parameters: required bucketId (string), optional limit (number), start and end (ISO strings).

  const inputSchema = {
    type: "object",
    properties: {
      bucketId: {
        type: "string",
        description: "ID of the bucket to fetch events from"
      },
      limit: {
        type: "number",
        description: "Maximum number of events to return (default: 100)"
      },
      start: {
        type: "string",
        description: "Start date/time in ISO format (e.g. '2024-02-01T00:00:00Z')"
      },
      end: {
        type: "string",
        description: "End date/time in ISO format (e.g. '2024-02-28T23:59:59Z')"
      }
    },
    required: ["bucketId"]
  };

• src/index.ts:59-63 (registration)

  Tool registration in the ListToolsRequestHandler, exposing name, description, and inputSchema to MCP clients.

  {
    name: activitywatch_get_events_tool.name,
    description: activitywatch_get_events_tool.description,
    inputSchema: activitywatch_get_events_tool.inputSchema
  },

• src/index.ts:248-265 (registration)

  Dispatch and argument validation logic in the CallToolRequestHandler that routes requests to the tool's handler.

  } else if (request.params.name === activitywatch_get_events_tool.name) {
    // For the raw events tool
    if (!args.bucketId || typeof args.bucketId !== 'string') {
      return makeSafeToolResponse(() => ({
        content: [{
          type: "text",
          text: "Error: Missing required parameter 'bucketId' (must be a string)"
        }],
        isError: true
      }))();
    }
    
    return makeSafeToolResponse(activitywatch_get_events_tool.handler)({
      bucketId: args.bucketId,
      limit: typeof args.limit === 'number' ? args.limit : undefined,
      start: typeof args.start === 'string' ? args.start : undefined,
      end: typeof args.end === 'string' ? args.end : undefined
    });