activitywatch_query_examples

Instructions

Implementation Reference

• src/queryExamples.ts:13-156 (handler)

  The handler function that returns a static markdown document containing examples of correct query formats for ActivityWatch tools, instructions, and common error patterns.

    handler: async () => {
      const examples = `
  # ActivityWatch MCP Query Examples
  
  Here are several examples of properly formatted queries for the ActivityWatch MCP server.
  
  ## CORRECT FORMAT
  
  All queries must follow this structure:
  
  \`\`\`json
  {
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": ["events = query_bucket('aw-watcher-window_hostname'); RETURN = events;"]
  }
  \`\`\`
  
  Note that:
  1. 'timeperiods' is an array with date ranges in the format "start/end"
  2. 'query' is an array with a SINGLE STRING containing ALL statements
  3. All query statements are in the same string, separated by semicolons
  
  ## COMMONLY USED QUERIES
  
  ### Get Active Window Events
  
  \`\`\`json
  {
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": ["window_events = query_bucket(find_bucket('aw-watcher-window_')); RETURN = window_events;"]
  }
  \`\`\`
  
  ### Get Active Window Events When Not AFK
  
  \`\`\`json
  {
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": ["window_events = query_bucket(find_bucket('aw-watcher-window_')); afk_events = query_bucket(find_bucket('aw-watcher-afk_')); not_afk = filter_keyvals(afk_events, 'status', ['not-afk']); active_events = filter_period_intersect(window_events, not_afk); RETURN = active_events;"]
  }
  \`\`\`
  
  ### Group Events by App
  
  \`\`\`json
  {
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": ["window_events = query_bucket(find_bucket('aw-watcher-window_')); events_by_app = merge_events_by_keys(window_events, ['app']); RETURN = sort_by_duration(events_by_app);"]
  }
  \`\`\`
  
  ### Filter by App Name
  
  \`\`\`json
  {
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": ["window_events = query_bucket(find_bucket('aw-watcher-window_')); vscode_events = filter_keyvals(window_events, 'app', ['Code']); RETURN = vscode_events;"]
  }
  \`\`\`
  
  ## COMMON ERRORS
  
  ### ❌ INCORRECT: Splitting query into multiple array items
  
  \`\`\`json
  {
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": [
      "window_events = query_bucket(find_bucket('aw-watcher-window_'));",
      "RETURN = window_events;"
    ]
  }
  \`\`\`
  
  ### ❌ INCORRECT: Not wrapping query in an array
  
  \`\`\`json
  {
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": "window_events = query_bucket(find_bucket('aw-watcher-window_')); RETURN = window_events;"
  }
  \`\`\`
  
  ### ❌ INCORRECT: Double-wrapping query in nested arrays
  
  \`\`\`json
  {
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": [[
      "window_events = query_bucket(find_bucket('aw-watcher-window_')); RETURN = window_events;"
    ]]
  }
  \`\`\`
  
  ### ✅ CORRECT: Single string with all statements in an array
  
  \`\`\`json
  {
    "timeperiods": ["2024-10-28/2024-10-29"],
    "query": ["window_events = query_bucket(find_bucket('aw-watcher-window_')); RETURN = window_events;"]
  }
  \`\`\`
  
  ## NOTE FOR MCP CLIENT DEVELOPERS
  
  If you're developing an MCP client that interacts with this server, be aware that:
  
  1. The server expects \`query\` to be an array of strings
  2. The server then transforms this to an array of arrays for the ActivityWatch API
  3. Some MCP clients may inadvertently add extra array nesting
  4. The server tries to automatically detect and handle these cases
  
  Potential issues to watch for:
  - The server transforming already-nested arrays (e.g., turning \`[["query"]]\` into \`[[["query"]]]\`)
  - Error messages that don't match the actual issue
  
  ## INSTRUCTIONS FOR CLAUDE USERS
  
  When asking Claude to run a query using the 'activitywatch_run_query' tool in the ActivityWatch MCP server, use this format in your request:
  
  "Please run this query with the 'activitywatch_run_query' tool:
  - timeperiods: ['2024-10-28/2024-10-29']
  - query: ['all statements go here in one string separated by semicolons; RETURN = results;']"
  
  ⚠️ Important: Make sure you explicitly tell Claude to put ALL query statements in ONE string inside the array. Do not double-wrap the query in another array.
  
  ⚠️ If you consistently get errors about query format, try modifying your query to include explicit formatting instructions:
  
  "Please run this query with the 'activitywatch_run_query' tool using EXACTLY this format:
  {
    'timeperiods': ['2024-10-28/2024-10-29'],
    'query': ['all statements go here in one string separated by semicolons; RETURN = results;']
  }"
  `;
  
      return {
        content: [
          {
            type: "text",
            text: examples
          }
        ]
      };
    }

• src/queryExamples.ts:9-12 (schema)

  The input schema defining no required parameters for this tool.

  inputSchema: {
    type: "object",
    properties: {}
  },

• src/index.ts:49-53 (registration)

  Registration of the tool in the MCP server's listTools handler, providing name, description, and schema.

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

• src/index.ts:84-85 (registration)

  Dispatch logic in the MCP server's callTool handler that invokes the tool's handler function when requested.

  } else if (request.params.name === activitywatch_query_examples_tool.name) {
    return makeSafeToolResponse(activitywatch_query_examples_tool.handler)();

• src/index.ts:7-7 (registration)

  Import of the tool definition from its implementation file.

  import { activitywatch_query_examples_tool } from "./queryExamples.js";