BrokerTrust MCP Server - PoC

MCP (Model Context Protocol) server pro práci s BrokerTrust Generic API přes OAuth 2.0 Authorization Code Flow.

Funkce

✅ OAuth 2.0 Authorization Code Flow
✅ Automatický refresh tokenů
✅ Strukturované logování (Serilog)
✅ MCP Protocol implementace
✅ Validace povinných polí při vytváření karet
✅ Práce s client-cards endpointy:

• GET /client-cards - vyhledávání karet
• GET /client-cards/{id} - detail karty
• POST /client-cards - vytvoření karty (s validací)
• PUT /client-cards/{id} - aktualizace karty

Povinná pole při vytváření karty:

Pro fyzickou osobu (FO):

• ✅ Jméno, Příjmení, Datum narození, Email

Pro OSVČ (FOP):

• ✅ Jméno, Příjmení, Datum narození, Email

Pro právnickou osobu (PO):

• ✅ Název firmy, Email

Požadavky

• .NET 9.0 SDK
• OAuth credentials (client_id, client_secret) od BrokerTrust

Instalace

1. Nastav OAuth credentials v appsettings.json:

{
  "OAuth": {
    "ClientId": "TVOJE_CLIENT_ID",
    "ClientSecret": "TVOJE_CLIENT_SECRET"
  }
}

2. Restore balíčků:

dotnet restore
dotnet build

Spuštění

První spuštění (OAuth autorizace)

dotnet run

Po spuštění:

1. Otevře se authorization URL - zkopíruj ji do prohlížeče
2. Přihlas se do BrokerTrust SSO
3. Po přesměrování zkopíruj celou URL zpět do konzole
4. ✅ Tokeny se automaticky uloží (zašifrovaně)
5. Můžeš začít používat příkazy

Další spuštění (používá uložené tokeny)

dotnet run

Už nepotřebuješ OAuth flow! Tokeny se načtou z .tokens souboru.

Dostupné příkazy:

• 1 - Vyhledat klientské karty
• 2 - Získat detail karty
• 3 - Vytvořit novou kartu
• 4 - Aktualizovat kartu
• tools - Zobrazit tools manifest
• exit - Ukončit

STDIO režim (pro Claude Desktop)

dotnet run stdio

Automaticky použije uložené tokeny. Pokud nejsou, zobrazí chybu.

📊 Logování

Aplikace používá Serilog pro strukturované logování do souborů.

Kde najdeš logy?

logs/
└── bt-generic-mcp-YYYYMMDD.log  # Nový soubor každý den

Sledování logů v reálném čase

Windows PowerShell:

Get-Content logs\bt-generic-mcp-*.log -Wait

Linux/Mac:

tail -f logs/bt-generic-mcp-*.log

Změna úrovně logování

V appsettings.json změň:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"  // nebo "Debug" pro více detailů
    }
  }
}

📖 Kompletní dokumentace: Documentation/LOGGING.md
🚀 Rychlý start: Documentation/LOGGING_QUICKSTART.md

Struktura projektu

BT.Generic.MCP/
├── Program.cs                    # Entry point, DI, Serilog konfigurace
├── OAuthClient.cs                # OAuth 2.0 logika
├── RestApiClient.cs              # REST API client
├── MCPProtocolHandler.cs         # MCP protokol
├── TokenStorage.cs               # Zašifrované ukládání tokenů
├── Models/
│   └── ClientCardModels.cs       # Data modely
├── appsettings.json              # Konfigurace
├── logs/                         # Log soubory (automaticky vytvořené)
└── Documentation/                # Kompletní dokumentace
    ├── LOGGING.md
    ├── LOGGING_QUICKSTART.md
    ├── TESTING_CHECKLIST.md
    └── ... další dokumenty

Příklady použití

Vyhledání karet podle příjmení

> 1
Příjmení: Novák

Získání detailu karty

> 2
ID klientské karty: 550e8400-e29b-41d4-a716-446655440000

Vytvoření nové karty

> 3
Legal Type (FO/PO/FOP): FO

--- Údaje fyzické osoby ---
Jméno (POVINNÉ): Jan
Příjmení (POVINNÉ): Novák
Datum narození (YYYY-MM-DD) (POVINNÉ): 1990-05-15
Email (POVINNÉ): [email protected]
Telefon (nepovinné): +420123456789

Odesílám požadavek...

OAuth Flow

1. Program vygeneruje Authorization URL
   ↓
2. Uživatel se přihlásí v prohlížeči
   ↓
3. SSO přesměruje na redirect_uri s authorization code
   ↓
4. Program vymění code za access_token + refresh_token
   ↓
5. Token se používá pro API requesty
   ↓
6. Při expiraci se automaticky refreshuje

Bezpečnostní features

• ✅ OAuth 2.0 Authorization Code Flow
• ✅ Token Persistence - Zašifrované ukládání tokenů (AES-256)
• ✅ Automatický refresh tokenů před expirací
• ✅ State parameter pro CSRF ochranu
• ✅ Bearer token autentizace
• ✅ .gitignore chrání tokenů a klíčů
• ✅ Citlivá data nejsou logována

Token Persistence

Aplikace automaticky ukládá OAuth tokeny do .tokens souboru:

• 🔒 Zašifrováno pomocí AES-256
• ♻️ Automatické načítání při dalším spuštění
• 🔄 Refresh tokeny se ukládají a používají
• 💻 Claude Desktop může používat uložené tokeny

📖 Vice info: Documentation/TOKEN_PERSISTENCE.md

Troubleshooting

"Token exchange failed"

1. Zkontroluj logy: logs/bt-generic-mcp-*.log
2. Hledej [ERR] záznamy
3. Ověř client_id a client_secret v appsettings.json

# Hledej chyby v lozích
Select-String -Path "logs\*.log" -Pattern "\[ERR\]"

"No access token available"

1. Zkontroluj logy pro detaily
2. Smaž .tokens a projdi OAuth flow znovu
3. Ujisti se, že máš správné OAuth credentials

"401 Unauthorized"

1. Zkontroluj logy - token mohl expirovat
2. Auto-refresh by měl proběhnout automaticky
3. Hledej refresh token události v lozích

# Hledej OAuth události
Select-String -Path "logs\*.log" -Pattern "OAuth|Token|refresh"

Aplikace se nespustí

1. Zkontroluj, že máš .NET 9.0 SDK: dotnet --version
2. Proveď clean build:

dotnet clean
dotnet restore
dotnet build

3. Zkontroluj logy pro detailní chybové zprávy

Rozšíření

Pro přidání dalších endpointů:

1. Přidej metodu do RestApiClient.cs:

public async Task<string> NewEndpointAsync(params)
{
    _logger.LogInformation("Volání NewEndpoint");
    var endpoint = "/new-endpoint";
    var request = await CreateAuthenticatedRequestAsync(HttpMethod.Get, endpoint);
    var response = await _httpClient.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsStringAsync();
}

2. Přidej handler do MCPProtocolHandler.cs

3. Přidej tool do manifestu v GetToolsManifest()

4. Přidej case do switch v HandleToolCallAsync()

📚 Dokumentace

🚀 Začínáš?

• 📖 README.md - Tento soubor
• 📖 Documentation/DOCUMENTATION_INDEX.md - Navigace v dokumentaci
• 🚀 Documentation/LOGGING_QUICKSTART.md - Rychlý start

📖 Hlavní dokumenty

• 📖 Documentation/LOGGING.md - Kompletní dokumentace logování
• 📖 Documentation/TOKEN_PERSISTENCE.md - Ukládání tokenů
• 📖 Documentation/MCP_SETUP.md - Nastavení MCP
• 📖 Documentation/CONSOLE_VS_LOGGER.md - Kdy použít Console vs Logger

✅ Changelogy a testy

• 📖 Documentation/CHANGELOG.md - Historie změn
• 📖 Documentation/CHANGELOG_LOGGING.md - Změny v logování
• 📖 Documentation/SUMMARY_LOGGING_CHANGES.md - Souhrn změn
• 📖 Documentation/TESTING_CHECKLIST.md - Testing checklist

🖥️ Claude Desktop integrace

• 📖 Documentation/CLAUDE_DESKTOP_CHECKLIST.md - Krok za krokem

✨ Pro vývojáře

• 📖 Documentation/IMPLEMENTATION_COMPLETE.md - Přehled implementace
• 📖 Documentation/GIT_COMMIT_GUIDE.md - Git návod

Technologie

• Framework: .NET 9.0
• Logování: Serilog + Microsoft.Extensions.Logging
• DI: Microsoft.Extensions.DependencyInjection
• Šifrování: AES-256 (pro tokeny)
• Protokol: MCP (Model Context Protocol)
• OAuth: Authorization Code Flow

Další kroky

✅ Hotovo

• OAuth 2.0 flow
• Token persistence
• MCP protokol
• Client cards operace
• Strukturované logování
• Dependency Injection

🔮 Možná rozšíření

• Přidat další endpointy z Generic API
• Implementovat rate limiting
• Přidat unit testy
• Vytvořit Docker image
• Support pro více uživatelů/tokenů
• Application Insights integrace
• Health checks

Kontakt a podpora

Pro otázky ohledně OAuth credentials nebo API přístupů kontaktuj BrokerTrust tým.

---

Verze: 1.1.0
Poslední aktualizace: 2025-10-01
Status: ✅ Production Ready