lots-aw-bridge

Lokaler Stdio-MCP-Server für die automatische Zeiterfassung in LOTS. Liest Events einer lokalen ActivityWatch-Instanz aus, wendet eine lernende Knowledge-Base an und stellt Claude Tools bereit, mit denen der tägliche Buchungs-Workflow in Sekunden erledigt ist.

→ Vollständige Anleitung & Einrichtung

Privacy-Grundsatz: ActivityWatch-Daten verlassen niemals die lokale Maschine. LOTS erhält nur die Zeiteinträge, die der Nutzer explizit bestätigt — niemals Window-Titel oder URLs.

Wie es funktioniert

ActivityWatch läuft im Hintergrund und protokolliert, welche Anwendungen und Websites aktiv sind. Die Bridge liest diese Events via REST aus, wendet Privacy-Filter an (Titel werden gestutzt, sensible Apps geblockt) und stellt sie Claude als strukturierte Sessions bereit.

Claude gleicht die Sessions mit einer lernenden Knowledge-Base ab — persönliche Regeln, die mit jedem korrigierten Eintrag schärfer werden — und schlägt fertige Zeiteinträge vor. Der Nutzer bestätigt, korrigiert oder ergänzt im Chat. LOTS bucht anschließend via LOTS-MCP.

Die Bridge selbst kommuniziert ausschließlich mit localhost:5600 (ActivityWatch). Kein Telemetrie, kein Cloud-Roundtrip für AW-Daten.

Installation

curl -fsSL https://lots.lilapixel.de/install.sh | bash

Der Installer richtet Homebrew, Node.js, ActivityWatch und die Bridge in einem Schritt ein und konfiguriert Claude Desktop automatisch.

Techie-Pfad (Node.js und ActivityWatch bereits vorhanden):

npx lots-aw-bridge install   # trägt Bridge in claude_desktop_config.json ein
npx lots-aw-bridge doctor    # prüft Konfiguration und AW-Verbindung

Claude Desktop neu starten — fertig.

Voraussetzungen:

• ActivityWatch läuft lokal auf http://localhost:5600
• Claude Desktop
• Node.js ≥ 18

Empfohlener Tages-Workflow

1. aw_get_sessions({date, timezone})                     → Sessions mit start/end (lokal)
2. list_my_kb_rules            [LOTS-MCP]                → persönliche Regeln
3. list_projects               [LOTS-MCP]                → Projekte mit matchHints
4. kb_match({events, accountRules, teamHints})           → Vorschläge mit start/end
5. Nutzer bestätigt / korrigiert
6. create_time_entry({startTime, duration, ...})         [LOTS-MCP] → gebucht
7. kb_record_correction(...)  + upsert_my_kb_rule        [LOTS-MCP] → KB lernt

aw_get_day_summary liefert alternativ aggregierte Tages-Übersichten (inkl. firstStart/lastEnd pro Bucket), ohne Einzel-Sessions — nützlich für einen schnellen Überblick oder bei sehr vielen kurzen Fenstern.

Claude führt den Workflow automatisch durch, sobald man z. B. schreibt:

„Buche meinen heutigen Tag bitte."

MCP-Tools

| Tool | Zweck | | --- | --- | | bridge_version | Installierte vs. verfügbare npm-Version — einmal pro Session aufrufen. | | aw_list_buckets | Übersicht aktiver ActivityWatch-Watcher (window / afk / web). | | aw_get_sessions | Empfohlen. Gemergte Sessions mit start/end (ISO-8601 + Offset), AFK-aware. | | aw_get_day_summary | Tages-Aggregation zu Buckets inkl. firstStart/lastEnd. | | aw_get_afk_events | AFK-Slices für Plausibilitätschecks. | | kb_match | Wendet KB-Regeln (5 Schichten) auf Events oder Sessions an — gibt Projektvorschläge zurück. | | kb_record_correction | Lernt aus Nutzer-Korrekturen (Sigmoid-Konfidenz, idempotent via correctionId). |

Knowledge-Base & Lernmechanismus

Die Bridge lernt mit jeder Korrektur dazu. Wenn Claude einen Eintrag falsch zuordnet und der Nutzer das richtige Projekt nennt, speichert kb_record_correction eine Regel lokal (~/.config/lots-aw-bridge/kb.json). Bei der nächsten Session mit derselben App/demselben Titel-Muster greift die Regel automatisch.

Zusätzlich können Regeln via upsert_my_kb_rule (LOTS-MCP) in der Cloud gespeichert werden — so greifen sie geräteübergreifend und überleben eine Neuinstallation.

Wissens-Schichten (Priorität hoch → niedrig):

| Schicht | Quelle | Beschreibung | | --- | --- | --- | | 0 | Lokal | Geblockte Apps — werden immer ignoriert, keine Timestamps | | 1 | Lokal | Manuelle Overrides (overrides.json) | | 2a | Lokal | Persönliche KB (~/.config/lots-aw-bridge/kb.json) | | 2b | LOTS-Cloud | Persönliche Regeln aus Firestore (list_my_kb_rules) | | 3 | LOTS-Cloud | Team-Hints aus Projekten (list_projects → matchHints) |

Privacy & Sicherheit

• awUrl muss localhost, 127.0.0.1 oder ::1 sein — sonst Hard-Fail CONFIG_PRIVACY_VIOLATION
• Window-Titel werden vor der Ausgabe auf einen titleStem reduziert (E-Mail-Adressen, API-Tokens und lange Pfade werden entfernt)
• Geblockte Apps liefern weder Titel noch Timestamps an Claude
• create_time_entry läuft direkt über LOTS-MCP — nicht durch die Bridge
• Die Bridge baut keine Verbindung zu externen Hosts auf (außer npm-Registry für bridge_version)

Sensible Apps (z. B. Banking, Passwort-Manager) können in overrides.json unter blockedApps eingetragen werden und tauchen dann in keiner Ausgabe auf.

Konfiguration

| Datei | Zweck | | --- | --- | | ~/.config/lots-aw-bridge/config.json | awUrl (Standard: http://localhost:5600), Logging | | ~/.config/lots-aw-bridge/overrides.json | blockedApps, redactTitlePatterns, manualOverrides | | ~/.config/lots-aw-bridge/kb.json | Lokal gelernte Match-Regeln (wird automatisch verwaltet) |

Beispiel overrides.json

{
  "blockedApps": ["1Password", "Banking App"],
  "redactTitlePatterns": ["token=[^&]+"],
  "manualOverrides": [
    {
      "when": { "app": "Figma" },
      "then": { "projectId": "proj_abc123" }
    }
  ]
}

Diagnose

npx lots-aw-bridge doctor

Prüft (7 Schritte): Config-Datei, Privacy-Constraint, AW-Erreichbarkeit, Window-Bucket, AFK-Bucket, Claude-Desktop-Konfiguration, npm-Version.

Entwicklung

npm install
npm test        # Vitest, alle Tests
npm run build   # esbuild → dist/cli.mjs

Konventionen: ESM, Node ≥ 18, Vitest, TDD. Vollständige Spezifikation: SPEC.md.

Lizenz

AGPL-3.0-only — Copyright 2026 Thomas Soring / LILAPIXEL Grafikdesign.

Nutzung, Modifikation und Weitergabe erlaubt; Änderungen müssen unter derselben Lizenz veröffentlicht werden.