# Balíček FineProxy pro agenty

Verze: 2026-09-22

Tento soubor použijte k posouzení, zda lze stávající integraci proxy migrovat na FineProxy. Neobsahuje žádný API klíč, data účtu ani soukromý endpoint.

## Zdroje pravdivých informací

- Interaktivní dokumentace klientského API: `https://fineproxy.org/account_new/docs`
- Nastavení MCP: `https://fineproxy.org/account_new/mcp`
- Aktuální klientská specifikace OpenAPI: stáhněte ji z dokumentace API v zákaznickém ovládacím panelu.
- Vytváření a správa API klíčů: `https://fineproxy.org/account_new/settings`
- MCP endpoint: `https://fineproxy.org/account_new/api/v1/mcp`

Z tohoto přehledu si nikdy nevymýšlejte endpointy. Pro cesty požadavků, schémata, parametry a odpovědi používejte aktuální specifikaci OpenAPI.

## Přehled platformy

- REST API: OpenAPI 3.1, 49 zdokumentovaných zákaznických operací.
- MCP: 49 nástrojů přes bezstavové JSON-RPC 2.0 a Streamable HTTP.
- Ověřování: bearer API klíče vytvořené v zákaznickém ovládacím panelu.
- API a MCP používají stejná oprávnění s omezeným rozsahem.
- Dokumentace partnerského API je viditelná pouze účtům s aktivním partnerským statusem.

## Podporovaná workflow

### Nákup a zřizování

- Zobrazit země a aktuální zásoby IP adres.
- Vytvořit cenovou nabídku přesného balíčku pro více zemí bez nákupu.
- Nakoupit z peněženky v ovládacím panelu s cenovým limitem a klíčem idempotence.

Standardní sekvence nákupu přes MCP je:

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

### Správa služeb

- Číst a spravovat služby.
- Obnovovat, pozastavovat, obnovit provoz nebo rušit služby, pokud je daná akce podporována.
- Zapínat nebo vypínat automatické obnovení.
- Nahrazovat nebo přidávat IP adresy.
- Měnit přihlašovací údaje služby.
- Číst a spravovat limity seznamu povolených IP adres.
- Zobrazovat, nakupovat a rušit kompatibilní doplňky.

### Analytika a diagnostika

- Přehled využití a časové řady.
- Nejčastější cíle.
- Kategorie chyb.
- Provozní doporučení.

### Fakturace a podpora

- Číst faktury a stahovat je ve formátu PDF.
- Zobrazit platební brány.
- Zahájit vklad do peněženky a číst jeho stav.
- Vytvářet, číst, zodpovídat a uzavírat tickety podpory.

### Přístup k proxy a účet

- Číst konfiguraci připojení k rotujícím proxy.
- Měnit přihlašovací jméno a heslo služby.
- Spravovat limity připojení pro jednotlivé IP adresy v seznamu povolených.
- Číst informace v profilu, IP adresu volajícího a historii přihlášení.
- Konfigurovat webhooky.

## Rozsahy oprávnění

- `customer:read` — číst informace o zákazníkovi a účtu.
- `customer:write` — aktualizovat informace o zákazníkovi.
- `wallet:read` — číst informace o peněžence.
- `wallet:deposit` — vytvářet a sledovat vklady.
- `wallet:spend` — utrácet prostředky z peněženky. Považujte jej za finanční oprávnění.
- `services:read` — číst služby a nastavení proxy.
- `services:write` — vytvářet nebo měnit služby a doplňky.
- `tickets:read` — číst tickety podpory.
- `tickets:write` — vytvářet, zodpovídat, aktualizovat nebo uzavírat tickety.
- `catalog:read` — číst produkty, možnosti, země a zásoby.
- `usage:read` — číst údaje o využití a diagnostiku.
- `webhooks` — spravovat odběry webhooků.

Audit migrace začněte s oprávněními pouze pro čtení. Oprávnění k zápisu nebo finanční oprávnění přidejte až po kontrole navržených změn.

## Bezpečnostní chování

- Finanční nástroje vyžadují `wallet:spend`.
- Nákupy obsahují očekávanou celkovou cenu z nabídky. Při neshodě ceny se operace zamítne.
- Nevratné operace vyžadují výslovné potvrzení.
- Opakované finanční požadavky používají klíč idempotence, aby tatáž operace nebyla naúčtována dvakrát.
- Aktuální zásoby, způsobilost tarifu a oprávnění účtu mohou zabránit jinak platné operaci.
- FineProxy MCP pracuje se zákaznickým účtem. Přístup ke zdrojovému kódu nezíská, pokud uživatel samostatně neposkytne kódovacímu agentovi přístup k repozitáři.

## Šablona konfigurace MCP

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

Skutečný klíč uchovávejte v proměnné prostředí nebo správci tajných údajů. Neodevzdávejte jej spolu s konfigurací MCP.

## Kontrolní seznam kompatibility migrace

Ve stávající integraci prověřte:

1. Inicializaci klienta poskytovatele a všechny importy specifické pro poskytovatele.
2. Ověřovací hlavičky, přihlašovací údaje, proměnné prostředí a ukládání tajných údajů.
3. Workflow nákupu, obnovení a zrušení služeb a náhrady IP adres.
4. Identifikátory zemí a předpoklady o zásobách.
5. Formáty seznamů proxy, protokoly, porty, uživatelská jména, hesla a seznamy povolených IP adres.
6. Stránkování a filtrování.
7. Opakování, práci s časovými limity a idempotenci.
8. Modely chyb a práci s limity požadavků.
9. Analytiku využití a diagnostiku.
10. Fakturaci, faktury a vklady.
11. Integraci ticketů podpory.
12. Webhooky a předpoklady o datových strukturách událostí.
13. Testy, testovací data, mocky a tajné údaje CI vázané na současného poskytovatele.

Každé workflow zařaďte do jedné z kategorií:

- Kompatibilní beze změn.
- Kompatibilní po změně konfigurace.
- Vyžaduje adaptér nebo transformaci dat.
- Vyžaduje odlišné provozní workflow.
- Nepodporované nebo nepotvrzené aktuální dokumentací.

## Požadovaný výstup auditu

Audit by měl obsahovat:

1. Soupis všech závislostí na současném poskytovateli.
2. Posouzení kompatibility jednotlivých workflow.
3. Požadované rozsahy FineProxy.
4. Přesné soubory a cesty v kódu, které by se změnily.
5. Změny ověřování a správy tajných údajů.
6. Otevřené otázky, které vyžadují aktuální specifikaci OpenAPI nebo potvrzení podpory.
7. Postupný plán migrace s možností návratu.
8. Integrační testy vyžadované před přechodem.

Během prvního průchodu auditu neupravujte kód.