Productivity Chronicle Analyzer Service (ActivityWatch Bridge)

An implementation of the Model Context Protocol (MCP) server designed to interface with the ActivityWatch ecosystem. This bridge enables sophisticated large language models, such as Claude, to derive actionable insights from granular personal time logs.

Core Capabilities

• Bucket Manifest Retrieval: Obtain a comprehensive inventory of all tracked ActivityWatch data containers.
• AQL Execution: Permit the execution of complex operations using the native ActivityWatch Query Language (AQL).
• Raw Data Fetching: Direct retrieval of underlying event streams from specified buckets.
• Configuration Access: Securely pull the current operational parameters of the underlying ActivityWatch instance.

Deployment Guide

Installation of this analysis service can be accomplished via the Node Package Manager (npm) registry or through manual compilation from source.

Registry Installation (Future Availability)

bash

Global deployment

npm install -g productivity-chronicle-analyzer-service

Local integration

npm install productivity-chronicle-analyzer-service

Compiling from Source Repository

1. Clone the repository structure: bash git clone https://github.com/8bitgentleman/activitywatch-mcp-server.git cd activitywatch-mcp-server

2. Install necessary dependencies: bash npm install

3. Execute the build process: bash npm run build

Essential Dependencies

• A functional, running instance of ActivityWatch.
• Node.js runtime environment (version 14 or later).
• An MCP-compatible client application (e.g., Claude for Desktop).

Operationalizing the Service

Integration with Claude Desktop Client

1. Locate and open the configuration manifest for Claude Desktop:

   • Windows OS Path: %APPDATA%\Claude\claude_desktop_config.json
   • macOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Insert the service definition into the mcpServers object:

{ "mcpServers": { "activitywatch": { "command": "productivity-chronicle-analyzer-service", "args": [] } } }

If you compiled the tool manually, adjust the directive to point to the compiled entry point:

{ "mcpServers": { "activitywatch": { "command": "node", "args": ["/path/to/activitywatch-mcp-server/dist/index.js"] } } }

1. Initiate a restart of the Claude Desktop environment.
2. Verify operational status via the designated MCP indicator within the Claude UI.

Illustrative Query Prompts

Users can utilize the following conversational structures in Claude:

• Inventory Check: "List the names of all data buckets accessible via the ActivityWatch repository."
• Application Utilization Summary: "Provide a breakdown of my time spent across various software programs for the current day."
• Web History Analysis: "Determine the top websites where my focus was directed today."
• Focus Time Quantification: "Calculate the aggregate duration spent within defined productivity applications."
• System State Retrieval: "Examine the current configuration parameters of the ActivityWatch backend."

Available Interface Functions

list-buckets

Retrieves the manifest of all available data segments. Filtering by data type is supported.

Parameters: - type (optional): A constraint string to filter container types (e.g., "window", "web", "afk"). - includeData (optional): A boolean flag to embed segment content within the initial response.

run-query

Executes a custom analytical script against the ActivityWatch data store using AQL.

Parameters: - timeperiods: A required array of strings specifying the temporal scopes, formatted as inclusive ranges: ["YYYY-MM-DD/YYYY-MM-DD"]. - query: An array containing the complete set of AQL statements. All statements must be concatenated within one string, separated by semicolons. - name (optional): A label assigned to the query operation (useful for internal tracking).

Critical Requirement: The query array must contain only one string entry, which encapsulates the entire multi-statement AQL script.

Example Request Structure:

{ "timeperiods": ["2024-10-28/2024-10-29"], "query": ["usage = query_bucket('aw-watcher-window_XYZ'); RETURN = usage;"] }

Note that: - timeperiods mandates the slash-separated range format. - The query array item must hold the entire execution sequence.

get-events

Fetches raw, untransformed event records from a designated ActivityWatch segment.

Parameters: - bucketId: The unique identifier for the source data segment. - start (optional): Timestamp specifying the beginning of the data extraction window (ISO format). - end (optional): Timestamp specifying the termination of the data extraction window (ISO format). - limit (optional): An integer defining the maximum record count to be returned.

get-settings

Retrieves operational configuration values from the ActivityWatch backend.

Parameters: - key (optional): If specified, only the value corresponding to this configuration key is returned; otherwise, the full settings object is provided.

ActivityWatch Query Language (AQL) Examples

ActivityWatch employs a concise, SQL-like syntax for data manipulation. Key constructs include:

// Analysis of general application activity app_logs = query_bucket(find_bucket("aw-watcher-window_")); RETURN = app_logs;

// Filtering out periods marked as inactive (AFK) afks = query_bucket(find_bucket("aw-watcher-afk_")); active_periods = filter_period_intersect(app_logs, afks, negate=true); // Note: Negation logic might vary, illustrative concept RETURN = active_periods;

// Aggregating durations by application identifier app_logs = query_bucket(find_bucket("aw-watcher-window_")); app_duration_summary = merge_events_by_keys(app_logs, ["app"]); RETURN = sort_by_duration(app_duration_summary); // Sort descending by total time

// Isolating time spent in a specific application (e.g., VS Code) app_logs = query_bucket(find_bucket("aw-watcher-window_")); vscode_sessions = filter_keyvals(app_logs, "app", ["Code"]); RETURN = vscode_sessions;

Connection Configuration

The service defaults to interfacing with the ActivityWatch API endpoint located at http://localhost:5600. Users needing to target a remote or non-standard ActivityWatch deployment must modify this default host/port mapping within the server's source code configuration files.

Debugging Common Issues

ActivityWatch Service Inoperability

If the ActivityWatch process is not actively running, the bridge server will report connection failures. Ensure the ActivityWatch daemon is active and reachable at the default address (http://localhost:5600).

AQL Execution Failures

Troubleshooting query execution errors involves:

1. Validating the structural correctness of the AQL syntax.
2. Confirming that all referenced data segment identifiers are accurate.
3. Verifying that the specified time intervals contain recorded entries.
4. Consulting the ActivityWatch server logs for granular diagnostics.

Client (Claude/MCP) Formatting Discrepancies

If the client reports issues submitting structured requests to this server, the problem is almost certainly related to the JSON payload structure.

Verify adherence to this precise schema for query execution:

{ "timeperiods": ["2024-10-28/2024-10-29"], "query": ["statement_one; statement_two; RETURN = final_result;"] }

Frequent pitfalls:

• Incorrect formatting of temporal boundaries (must be an array containing a single "start/end" string).
• The critical error: Distributing individual AQL statements across separate elements of the query array.

Rectifying the Statement Separation Mistake

INCORRECT Example (Split Statements):

{ "query": [ "browser_data = query_bucket('aw-watcher-web');", "idle_data = query_bucket('aw-watcher-afk');", "RETURN = browser_data;" ], "timeperiods": ["2024-10-28/2024-10-29"] }

CORRECT Example (Consolidated Statement):

{ "timeperiods": ["2024-10-28/2024-10-29"], "query": ["browser_data = query_bucket('aw-watcher-web'); idle_data = query_bucket('aw-watcher-afk'); RETURN = browser_data;"] }

Prompting Guidance for Claude

When instructing Claude, emphasize the required structure: "Execute using timeperiods as ["YYYY-MM-DD/YYYY-MM-DD"] and ensure the query parameter contains one string where all required AQL commands are delimited solely by semicolons, culminating in the RETURN statement."

Collaboration

Contributions, feature suggestions, and pull requests are actively encouraged and welcomed for enhancement.

Licensing

This project is distributed under the terms of the MIT License.