mikrus-pl/mcp-server-clickup-data

MCP Server ClickUp Data – MVP

Cel projektu

Serwer MCP umożliwia Large Language Model (LLM) dostęp do przetworzonych danych z ClickUp oraz inicjowanie synchronizacji tych danych. Projekt stanowi walidację koncepcji wykorzystania LLM do raportowania i interakcji z danymi biznesowymi.

Kluczowe funkcjonalności (MVP)

Narzędzia – Odczyt danych (SQLite)

• listUsers – pobiera listę użytkowników (ID, username)
• getUserCurrentRate(userId) – pobiera aktualną stawkę użytkownika
• getUserRateHistory(userId) – pobiera historię stawek użytkownika
• getReportedTaskAggregates(filters) – pobiera dane z tabeli ReportedTaskAggregates, umożliwiając filtrowanie po clientName, reported_for_user_id, extracted_month_from_parent_name (zwraca dane w formacie JSON array of objects)
• listClients – zwraca unikalną listę klientów na podstawie danych w ReportedTaskAggregates lub Tasks.custom_field_client
• getTimeMatrix(filters) – zwraca zwarte, zagregowane dane czasu pracy w formie „macierzy” z gotowymi sumami (overall/byUser/byClient/byMonth). Ułatwia pracę agentom AI, minimalizując ryzyko błędów przy sumowaniu.

Narzędzia – Wywoływanie komend CDC

• Inicjowanie synchronizacji danych przez wywołanie komend CLI z clickup-data-collector (poprzez child_process)

Struktura projektu

├── .env                 # zmienne środowiskowe
├── .gitignore           # plik ignorowania dla GIT
├── kick-off-requirements.md # wymagania MVP
├── package.json         # zależności npm
├── server.js            # główny serwer Node.js
├── src/
│   ├── db/              # obsługa bazy danych (np. database.js)
│   ├── tools/           # narzędzia do obsługi danych i komend
│   └── utils/           # pomocnicze funkcje
├── tests/               # skrypty pomocnicze do testowania
├── docs/                # dokumentacja (uwaga: pliki w tym katalogu mogą nie być w pełni aktualne, wiedza z nich powinna być weryfikowana przed użyciem)

Wymagania

• Node.js
• SQLite (baza danych lokalna)
• Dostęp do clickup-data-collector (CLI)

Uruchomienie

1. Skonfiguruj plik .env z wymaganymi zmiennymi środowiskowymi.
2. Zainstaluj zależności:

   npm install
   

3. Uruchom serwer:

   node server.js
   

Dokumentacja

Szczegółowe wymagania znajdują się w pliku kick-off-requirements.md.

getTimeMatrix – szczegółowa dokumentacja

Opis: Zwraca zwarte, zagregowane dane czasu pracy w formie „macierzy” z gotowymi sumami (overall/byUser/byClient/byMonth). Automatycznie optymalizuje wymiary i pola wierszy w zależności od filtrów. Ułatwia pracę agentom AI, minimalizując ryzyko błędów przy sumowaniu.

Wejście (wszystkie pola opcjonalne):

• clientName: string – dokładna nazwa klienta (case-insensitive)
• userId: integer – ClickUp user id
• month: string – polska nazwa miesiąca (np. „lipiec”, case-insensitive)
• includeTotals: boolean – dołącz bloki sum (domyślnie true)
• pretty: boolean – pretty-print JSON (domyślnie true)

Zasady doboru wymiarów (heurystyki):

• Tylko month → wiersze: userId, user, client, minutes, hhmm
• Tylko userId → userId, user, client, ...
• Tylko clientName → userId, user, month, ... (+ totals.byMonth dla sum per miesiąc)
• userId & clientName (bez month) → userId, user, client, month, ...
• userId & clientName & month → pojedyncza kombinacja (jeśli istnieje)

Wyjście (przykład):

{
  "filters": { "clientName": "MOKO", "userId": 87872985, "month": "lipiec" },
  "dimensions": ["userId", "user", "client"],
  "rows": [
    { "userId": 87872985, "user": "Jan Kowalski", "client": "MOKO", "minutes": 123, "hhmm": "2:03", "cost": 82 }
  ],
  "totals": {
    "overall": { "minutes": 123, "hhmm": "2:03", "cost": 82 },
    "byUser": [{ "userId": 87872985, "user": "Jan Kowalski", "minutes": 123, "hhmm": "2:03", "cost": 82 }],
    "byClient": [{ "client": "MOKO", "minutes": 123, "hhmm": "2:03", "cost": 82 }],
    "byMonth": [{ "month": "lipiec", "minutes": 123, "hhmm": "2:03", "cost": 82 }],
    "revenueByClient": [{ "client": "MOKO", "revenue": 500 }],
    "revenueByMonth": [{ "month": "lipiec", "revenue": 500 }]
  }
}

Kalkulacje i jednostki:

• minutes: Suma minut pracy (z total_time_minutes)
• hhmm: Czas w formacie h:mm
• cost: Koszt pracy = minutes * hourly_rate / 60 (PLN)
• revenue: Przychód z faktur (PLN)

Przykłady uruchomienia testu:

node tests/test-getTimeMatrixTool.js --month czerwiec
node tests/test-getTimeMatrixTool.js --client MOKO
node tests/test-getTimeMatrixTool.js --client MOKO --user 87872985

Projekt MVP – wersja wstępna. Wszelkie uwagi i propozycje zmian mile widziane!