Twórz bezpieczniejszych agentów z dokumentacją Flowtly MCP

Jak być na bieżąco

1. Uruchom komendę sync po każdej aktualizacji MCP.
2. Zrestartuj stos agentów, aby wczytać nowe możliwości.
3. Dodaj tę stronę do zakładek, żeby mieć świeże wskazówki MCP.

Co w środku

• Zasady autoryzacji i kluczy API dla endpointów MCP.
• Schematy zasobów dla bazy wiedzy, bloga, release notes, inwestorów i aktualizacji produktu.
• Ładunki JSON-RPC oraz wskazówki do zapisów/odczytów dla agentów.
• 14 logicznych podsumowań dla obliczeniowej analityki.
• Ładunki JSON-RPC, przykłady kodu i wskazówki dotyczące integracji.

Szybki start

• Krok 1 — Zdobądź token: Przejdź do Flowtly Workspace → Agent Tokens i wygeneruj token klienta.
• Krok 2 — Inicjalizuj: Wyślij POST do https://mcp.flowtly.eu/mcp z {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Krok 3 — Odczytaj dane: Wyślij POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Krok 4 — Zapisz dane: Wyślij POST {"jsonrpc":"2.0","id":"write-1","method":"resources/work-times/write","params":{"uri":"/api/work-times","contents":[{"text":"{\"date\":\"2026-04-03\",\"seconds\":3600,\"project\":\"/projects/1\",\"description\":\"Support\"}"}]}}
• Wszystkie żądania używają Authorization: Bearer <YOUR_TOKEN> i Content-Type: application/json.

Transport i Auth

• Endpointy: POST /mcp (wejście JSON-RPC), GET /health (liveness), POST /api/chat (proxy konsoli; wymaga Authorization: Bearer )
• Nagłówki: Authorization Bearer token (preferowany; fallback FLOWTLY_API_KEY), nagłówek instance opcjonalny i przekazywany dalej
• Content-Type: application/json
• Body: JSON-RPC 2.0 { "jsonrpc": "2.0", "id": "...", "method": "...", "params": {...} }
• CORS: Poświadczenia dozwolone tylko z https://workspace.flowtly.eu. Nigdy nie łącz Access-Control-Allow-Origin: * z Access-Control-Allow-Credentials: true.
• Upstream API: https://api.flowtly.eu — serwer MCP pośredniczy we wszystkich żądaniach do Flowtly REST API.

initialize

• Negocjuje możliwości i namespaces.
• Przykładowe parametry: { "protocolVersion": "2024-11-05" }
• Zwraca capabilities (list, read, write) i namespaces (work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests).
• Dostępne przestrzenie nazw: work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, budget-groups, budgets, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.

resources/list

• Metoda: resources/{namespace}/list (domyślny namespace: work-times, gdy pominięty)
• Namespaces: work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.
• Zwraca URI per namespace (szczegóły poniżej).
• Przykład: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Metoda: resources/{namespace}/read (domyślnie work-times).
• Parametry obejmują uri, np. /api/work-times
• allowPrefixes umożliwia dopasowania między namespaces; {current} rozwija się do /api/employees/me.
• Niektóre zasoby dodają domyślne wartości (work-times dodaje zakres dat; employees dodaje itemsPerPage; holidays/vacations dodają domyślną paginację).
• Responsibilities śledzi do 10 linków @id, aby wzbogacić tytuł/nazwę.
• Namespace logical zwraca serwerowe podsumowania zamiast surowych payloadów.
• Zwraca payload contents z bazowej API Flowtly.
• Odpowiedź: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Tylko zasoby z allowWrite przyjmują zapis; POST chyba że URI kończy się id (wtedy PATCH z application/merge-patch+json).
• /api/.../create wymusza POST nawet przy id; typ można nadpisać przez params.contentType.
• Pomocnik logical write: resources/logical/write obsługuje /logical/recruiting/resource-requests/update?id= oraz /logical/recruiting/resource-request-candidates/update?id= (PATCH).
• Konwencja IRI: params.uri używa ścieżek /api/..., ale odniesienia do encji w ładunkach JSON muszą używać IRIs upstream (np. "project": "/projects/1", nie "/api/projects/1").
• Przestrzenie nazw z możliwością zapisu: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Pomocnicy zapisu logicznego: resources/logical/write obsługuje /logical/work-times/log (POST do /api/work-times), /logical/recruiting/resource-requests/update?id=<id> i /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Wbudowani agenci

• EmployeeAgent (employee): Codzienne operacje — rejestruj czas pracy, sprawdzaj urlopy, przeglądaj zadania. Dostęp: każdy uwierzytelniony użytkownik (ograniczony tokenem/instancją).
• ManagerAgent (manager): Wsparcie dla kierownika projektu/inżynierów — stawki, obsada, koszty, zatwierdzenia. Wymaga: roli project_manager lub admin.
• ExecutiveAgent (executive): Przeglądy dla kadry kierowniczej — KPIs, budżety, podsumowania, zatwierdzenia. Wymaga: roli admin, executive, director, vp lub c-level.
• HRManagerAgent (hr): HR i urlopy — salda urlopów, historia nieobecności, święta zespołowe. Dostęp: każdy uwierzytelniony użytkownik.
• AccountancyAgent (accountancy): Zapytania finansowe — lista transakcji, podsumowanie kwot. Nigdy nie udostępnia adresów URL załączników. Dostęp: każdy uwierzytelniony użytkownik.
• RecruiterAgent (recruiter): Rekrutacja — lista otwartych ról, wyszukiwanie/tworzenie kandydatów, przypisywanie do ról, dodawanie notatek. Wymaga: roli candidates_manager, admin lub recruiter.
• OnboardingAgent (onboarding): Wskazówki dla nowych użytkowników — pomoc w konfiguracji, nawigacja, odpowiedzi na pytania „gdzie znaleźć X”. Dostęp: każdy uwierzytelniony użytkownik.
• TechAgent (tech): Ustawienia techniczne — żądania poświadczeń MCP/ChatGPT. Generuje poświadczenia klienta dla każdego użytkownika po zatwierdzeniu przez administratora. Dostęp: otwarty dla wszystkich ról (zostanie zaostrzony).
• Wybór agenta: Użyj employee do zadań osobistych; hr do urlopów/wakacji; manager do obsady/kosztów; executive do KPIs; accountancy do finansów; recruiter do kandydatów; onboarding do konfiguracji.
• Model dostępu: Sprawdzanie ról wykorzystuje role/uprawnienia/pozwolenia Flowtly. Agenci z ograniczeniami odmawiają wykonania działań, gdy nie pasuje wymagana rola. Wszyscy agenci używają wyłącznie narzędzia MCP API — bez zewnętrznych usług.

Namespace logical (/logical/*)

• Podsumowania tylko do odczytu: work-times, employees, projects, employee-work-times, project-rates, transactions, project-profitability.
• Podsumowania rekrutacji: company-onboarding/status, recruiting/open-roles, recruiting/candidates.
• Podsumowania urlopów: logical/holidays.
• Przykład: /logical/work-times/summary obsługuje date[after]/date[before] (domyślnie ostatnie 7 dni).
• Stawki projektowe: /logical/project-rates/summary — karty stawek i przegląd stawek rozliczeniowych.
• Transakcje: /logical/transactions/summary — sumy wydatków, kategoryzacja i trendy.
• Rentowność projektu: /logical/project-profitability/summary — przychody vs koszty na projekt.
• Grupy budżetowe: /logical/budget-groups/summary — alokacje grup budżetowych i status wykorzystania.
• Budżety: /logical/budgets/summary — wykorzystanie poszczególnych budżetów i alerty.
• Wdrożenie firmy: /logical/company-onboarding/status — postęp konfiguracji obszaru roboczego i oczekujące kroki.
• Otwarte role: /logical/recruiting/open-roles — niezrealizowane zapotrzebowania na zasoby i proces rekrutacji.
• Kandydaci: /logical/recruiting/candidates — rozkład kandydatów w etapach procesu rekrutacji.
• Urlopy: /logical/holidays — zagregowane dane dotyczące urlopów i dostępności zespołu.
• Rejestr czasu pracy (zapis): /logical/work-times/log — POST tworzy wpis czasu pracy za pośrednictwem /api/work-times.

Buforowanie i wydajność

• Logiczna pamięć podręczna Redis: Opcjonalna pamięć podręczna dla odczytów logicznych. Może współdzielić Redis z głównym API dla wzorców unieważniania.
• Zmienne środowiskowe: MCP_LOGICAL_CACHE_ENABLED (automatycznie włączane, gdy istnieje URL Redis), MCP_LOGICAL_CACHE_REDIS_URL (alternatywy: REDIS_URL, CACHE_REDIS_URL).
• Format klucza: Prefiks mcp:logical:v1: — zakreskowany przez instancję + podmiot, zawiera znormalizowany logiczny URI. Skonfiguruj prefiks za pomocą MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 sekund (24 godziny). Skonfiguruj za pomocą MCP_LOGICAL_CACHE_TTL_SECONDS.

Kształt błędu

• { "jsonrpc": "2.0", "id": "...", "error": { "code": -32000, "message": "Upstream Flowtly API failed", "data": { "status": 502 } } }
• Typowe kody błędów: -32700 (błąd parsowania), -32600 (nieprawidłowe żądanie), -32601 (metoda nie znaleziona), -32000 (awaria API nadrzędnego).
• Pole data.status odzwierciedla kod statusu HTTP z nadrzędnego API Flowtly, gdy jest dostępny.

Notatki

• allowPrefixes pozwala resources/read akceptować URI zaczynające się od dozwolonych prefiksów.
• Referencja w stylu OpenAPI dostępna w public/mcp/openapi.json.
• Kontrakty intencji LLM: Wzorce routera + menedżera udokumentowane w docs/llm-intent-architecture.md, zaimplementowane w packages/agent/src/intents/contract.ts.
• Stronicowanie: Ustawienia domyślne są automatycznie stosowane dla każdej przestrzeni nazw. Nadpisz za pomocą jawnych parametrów zapytania, gdy zajdzie taka potrzeba.

resources/list według namespace