# FineProxy Agent Pack

Wersja: 2026-09-22

Użyj tego pliku, aby ocenić, czy istniejącą integrację proxy można przenieść do FineProxy. Plik nie zawiera klucza API, danych konta ani prywatnego punktu końcowego.

## Źródła prawdy

- Interaktywna dokumentacja API klienta: `https://fineproxy.org/account_new/docs`
- Konfiguracja MCP: `https://fineproxy.org/account_new/mcp`
- Aktualna specyfikacja OpenAPI klienta: pobierz ją z dokumentacji API w panelu klienta.
- Tworzenie kluczy API i zarządzanie nimi: `https://fineproxy.org/account_new/settings`
- Punkt końcowy MCP: `https://fineproxy.org/account_new/api/v1/mcp`

Nigdy nie wymyślaj punktu końcowego na podstawie tego opisu. Ścieżki żądań, schematy, parametry i odpowiedzi sprawdzaj w aktualnej specyfikacji OpenAPI.

## Podsumowanie platformy

- REST API: OpenAPI 3.1, 49 udokumentowanych operacji klienta.
- MCP: 49 narzędzi przez bezstanowy JSON-RPC 2.0 i Streamable HTTP.
- Uwierzytelnianie: klucze API typu bearer tworzone w panelu klienta.
- API i MCP używają tych samych uprawnień o ograniczonym zakresie.
- Dokumentacja partnerskiego API jest widoczna tylko dla kont z aktywnym statusem partnera.

## Obsługiwane procesy

### Zakup i udostępnianie

- Wyświetlanie krajów i aktualnych zasobów IP.
- Wycena dokładnego pakietu obejmującego wiele krajów bez dokonywania zakupu.
- Zakup z wykorzystaniem portfela w panelu, z kontrolą ceny i kluczem idempotencji.

Standardowa sekwencja zakupu przez MCP:

1. `list_countries`
2. `quote_composite`
3. `order_composite`

### Zarządzanie usługami

- Odczytywanie usług i zarządzanie nimi.
- Odnawianie, zawieszanie, przywracanie lub anulowanie, jeśli jest obsługiwane.
- Włączanie lub wyłączanie automatycznego odnawiania.
- Wymiana lub dodawanie adresów IP.
- Zmiana danych dostępowych usługi.
- Odczytywanie limitów listy dozwolonych i zarządzanie nimi.
- Wyświetlanie, kupowanie i anulowanie zgodnych dodatków.

### Analityka i diagnostyka

- Przegląd użycia i szeregi czasowe.
- Najczęstsze usługi docelowe.
- Kategorie błędów.
- Zalecenia operacyjne.

### Rozliczenia i wsparcie

- Odczytywanie faktur i pobieranie ich w formacie PDF.
- Wyświetlanie bramek płatniczych.
- Rozpoczynanie wpłaty do portfela i odczytywanie jej statusu.
- Tworzenie, odczytywanie, odpowiadanie na i zamykanie zgłoszeń do pomocy technicznej.

### Dostęp do proxy i konta

- Odczytywanie konfiguracji połączenia proxy rotacyjnego.
- Zmiana loginu i hasła usługi.
- Zarządzanie limitami połączeń dla poszczególnych adresów IP na liście dozwolonych.
- Odczytywanie danych profilu, adresu IP wywołującego i historii logowania.
- Konfigurowanie webhooków.

## Zakresy uprawnień

- `customer:read` — odczytywanie informacji o kliencie i koncie.
- `customer:write` — aktualizowanie informacji o kliencie.
- `wallet:read` — odczytywanie informacji o portfelu.
- `wallet:deposit` — tworzenie i monitorowanie wpłat.
- `wallet:spend` — wydawanie środków z portfela. Traktuj jako uprawnienie finansowe.
- `services:read` — odczytywanie usług i ustawień proxy.
- `services:write` — tworzenie lub modyfikowanie usług i dodatków.
- `tickets:read` — odczytywanie zgłoszeń do pomocy technicznej.
- `tickets:write` — tworzenie, aktualizowanie i zamykanie zgłoszeń lub odpowiadanie na nie.
- `catalog:read` — odczytywanie produktów, opcji, krajów i zasobów.
- `usage:read` — odczytywanie danych o użyciu i diagnostyki.
- `webhooks` — zarządzanie subskrypcjami webhooków.

Rozpocznij audyt migracji z uprawnieniami tylko do odczytu. Dodaj uprawnienia do zapisu lub operacji finansowych dopiero po przejrzeniu proponowanych zmian.

## Zabezpieczenia

- Narzędzia finansowe wymagają `wallet:spend`.
- Zakupy zawierają oczekiwaną łączną kwotę z wyceny. Niezgodność ceny powoduje odrzucenie operacji.
- Nieodwracalne operacje wymagają jawnego potwierdzenia.
- Ponowienia operacji finansowych używają klucza idempotencji, aby opłata za tę samą operację nie została naliczona dwukrotnie.
- Aktualne zasoby, zgodność z planem i uprawnienia konta mogą uniemożliwić wykonanie operacji, która poza tym jest prawidłowa.
- MCP FineProxy obsługuje konto klienta. Nie uzyskuje dostępu do kodu źródłowego, chyba że użytkownik osobno udostępni agentowi kodującemu repozytorium.

## Szablon konfiguracji MCP

```json
{
  "mcpServers": {
    "fineproxy": {
      "url": "https://fineproxy.org/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}
```

Prawdziwy klucz przechowuj w zmiennej środowiskowej lub menedżerze sekretów. Nie zatwierdzaj go w repozytorium wraz z konfiguracją MCP.

## Lista kontrolna zgodności migracji

Sprawdź w istniejącej integracji:

1. Inicjalizację klienta dostawcy i wszystkie importy specyficzne dla dostawcy.
2. Nagłówki uwierzytelniania, dane dostępowe, zmienne środowiskowe i przechowywanie sekretów.
3. Procesy zakupu, odnawiania i anulowania oraz wymiany adresów IP.
4. Identyfikatory krajów i założenia dotyczące zasobów.
5. Formaty list proxy, protokoły, porty, nazwy użytkowników, hasła i listy dozwolonych adresów IP.
6. Paginację i filtrowanie.
7. Sposób ponawiania, obsługę przekroczenia czasu i idempotencję.
8. Modele błędów i obsługę limitów zapytań.
9. Analitykę użycia i diagnostykę.
10. Rozliczenia, faktury i wpłaty.
11. Integrację ze zgłoszeniami do pomocy technicznej.
12. Webhooki i założenia dotyczące ładunków zdarzeń.
13. Testy, dane testowe, mocki i sekrety CI powiązane z obecnym dostawcą.

Zaklasyfikuj każdy proces jako:

- Zgodny bez zmian.
- Zgodny po zmianie konfiguracji.
- Wymagający adaptera lub przekształcenia danych.
- Wymagający innego procesu operacyjnego.
- Nieobsługiwany lub niepotwierdzony w aktualnej dokumentacji.

## Wymagany wynik audytu

Audyt powinien obejmować:

1. Wykaz wszystkich zależności od obecnego dostawcy.
2. Ocenę zgodności każdego procesu.
3. Wymagane zakresy FineProxy.
4. Dokładne pliki i ścieżki kodu, które wymagałyby zmiany.
5. Zmiany w uwierzytelnianiu i zarządzaniu sekretami.
6. Otwarte pytania wymagające sprawdzenia aktualnej specyfikacji OpenAPI lub potwierdzenia przez pomoc techniczną.
7. Etapowy plan migracji z możliwością wycofania zmian.
8. Testy integracyjne wymagane przed przełączeniem.

Nie modyfikuj kodu podczas pierwszego etapu audytu.