Połącz narzędzia AI z Flowtly przez MCP tylko do odczytu

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, CORS i transportu dla endpointu MCP.
• Przestrzenie nazw zasobów tylko do odczytu z operacjami listowania i odczytu.
• OAuth 2.0 z Dynamic Client Registration dla połączenia w jednym kroku.
• 16 narzędzi tylko do odczytu w 10 przestrzeniach nazw zasobów.
• Ładunki JSON-RPC, przykłady kodu i wskazówki dotyczące integracji.

Szybki start

• Krok 1 — Połącz (OAuth): Dodaj https://mcp.flowtly.eu jako konektor w swoim narzędziu AI i autoryzuj dostęp tylko do odczytu. W Claude Code: claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp. Pełny przewodnik: Łączenie narzędzi AI.
• 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"}} — serwer odpowiada możliwościami {"tools":{}}.
• Krok 3 — Wylistuj narzędzia: Wyślij POST {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}, aby odkryć dostępne narzędzia tylko do odczytu (np. invoices.list, transactions.list, counterparties.list).
• Krok 4 — Wywołaj narzędzie: Wyślij POST {"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"transactions.list","arguments":{}}}. Wynik pojawia się jako result.content[].text (ciąg JSON).
• 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" }
• Możliwości w odpowiedzi: {"tools":{}}
• Odkryj narzędzia: wywołaj tools/list, aby pobrać dostępne narzędzia tylko do odczytu wraz z ich danymi wejściowymi w formacie JSON-Schema.

tools/list

• Metoda: tools/list — zwraca każde narzędzie tylko do odczytu dostępne dla Twojego połączenia.
• Narzędzia (16): invoices.list/get, transactions.list, bankAccounts.list/get, counterparties.list/get, suppliers.list, contracts.list/get/paymentScheduleLines, attachments.list/get, costGroups.list, taxGroups.list, projects.list.
• Każdy wpis ma name, description oraz inputSchema w formacie JSON-Schema opisujący jego argumenty.
• Przykład: {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}

tools/call

• Metoda: tools/call — wywołaj narzędzie po nazwie wraz z jego argumentami.
• Parametry: {"name":"<tool>","arguments":{...}}, np. {"name":"invoices.list","arguments":{}}.
• Argumenty: stosuj się do inputSchema narzędzia z tools/list (filtry, paginacja, identyfikatory). Pomiń, aby użyć rozsądnych wartości domyślnych.
• Tylko do odczytu: każde narzędzie wyłącznie odczytuje dane — nie ma narzędzi do zapisu.
• Najpierw odkrywanie: wywołaj tools/list, aby przed wywołaniem poznać dokładne nazwy narzędzi i schematy argumentów.
• Paginacja i filtry: przekazywane wewnątrz arguments zgodnie ze schematem każdego narzędzia (np. zakresy dat, rozmiar strony).
• Pojedyncze rekordy: narzędzia *.get przyjmują argument id i zwracają jedną encję; narzędzia *.list zwracają kolekcje.
• Odpowiedź: {"jsonrpc":"2.0","id":"...","result":{"content":[{"type":"text","text":"{...}"}]}} — przetwórz content[].text jako JSON.

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.

Narzędzia według przestrzeni nazw