# SoonaR MCP konektor

Pripojenie na **SoonaR** priamo do Claude Desktop. SoonaR je interný nástroj na hľadanie
a spracovanie slovenských firiem ako obchodných leadov (register + financie + kontakty + CRM).
Po pripojení dostaneš v Claude sadu nástrojov, ktoré vie volať priamo v chate.

Tento konektor je **tenký klient** - len zavolá SoonaR API cez sieť. Žiadna databáza,
žiadne tajomstvá okrem tvojho API tokenu.

## Čo budeš vedieť robiť (cez chat)
- Hľadať firmy podľa kritérií: sektor / NACE, kraj, obrat, tržby, zisk, medziročný rast, dlh.
- Pozrieť detail firmy vrátane konateľov (štatutárov) na kontaktovanie.
- Obohatiť kontakt (email/telefón cez Lusha).
- Pushnúť firmu do Odoo CRM + naplánovať hovor.
- Nájsť firmy, ktoré práve naberajú ľudí (z pracovných inzerátov).

## Predpoklady
1. **Claude Desktop** (stiahni: https://claude.ai/download).
2. **Git** (https://git-scm.com/downloads). Na Windows nainštaluj "Git for Windows"
   s predvolenými nastaveniami. Slúži na stiahnutie tohto konektora cez `git clone`.
   (Ak Git nechceš, môžeš si repo stiahnuť aj ako ZIP - viď krok 1.)
3. **Python 3.10+** (https://www.python.org/downloads/). Pri inštalácii na Windows zaškrtni
   **"Add Python to PATH"**.
4. **Tvoj API token** - pošle ti ho admin (damia). Je to tvoj osobný kľúč, **nezdieľaj ho**.

## 1) Stiahni konektor
**Možnosť A - Git (odporúčané):** naklonuj repo, napr. do `C:\Users\<ty>\soonar-mcp`:
```bash
git clone <URL-tohto-repa> soonar-mcp
```
**Možnosť B - bez Gitu:** na stránke repa klikni **Code -> Download ZIP**, rozbaľ ho
(napr. do `C:\Users\<ty>\soonar-mcp`).

## 2) Nainštaluj závislosti
V priečinku konektora spusti:
```bash
pip install -r requirements.txt
```
(nainštaluje `mcp` a `httpx`)

## 3) Pripoj do Claude Desktop (Edit Config)
1. Otvor **Claude Desktop**.
2. Choď do **Settings -> Developer -> Edit Config**. Otvorí sa súbor
   `claude_desktop_config.json` v tvojom editore.
3. Vlož tento blok (ak už `mcpServers` máš, len doň pridaj kľúč `"soonar"`).
   **Uprav cestu** k `mcp_server.py` a **vlož svoj token**:
```json
{
  "mcpServers": {
    "soonar": {
      "command": "python",
      "args": ["C:\\Users\\TVOJE_MENO\\soonar-mcp\\mcp_server.py"],
      "env": {
        "SOONAR_API_URL": "https://soonar.zvar.it",
        "SOONAR_API_TOKEN": "VLOZ_SVOJ_TOKEN"
      }
    }
  }
}
```
4. **Ulož** súbor.

Poznámky k ceste a príkazu:
- **Windows:** v ceste daj dvojité spätné lomky `\\` (ako vyššie).
- Ak `python` nefunguje, skús `py`, alebo daj plnú cestu k `python.exe`.
- **macOS/Linux:** `"command": "python3"` a cesta typu `"/Users/ty/soonar-mcp/mcp_server.py"`.

Vzor je aj v súbore [claude_desktop_config.example.json](claude_desktop_config.example.json).

## 4) Reštartuj Claude Desktop
Úplne ho **zavri a znova otvor**. Po štarte uvidíš ikonu nástrojov (kladivko) a medzi nimi
nástroje **soonar**.

## 5) Vyskúšaj v chate
- "koľko firiem máme v databáze?"
- "nájdi 10 IT firiem v Bratislave s obratom nad 1M a bez dlhu"
- "ukáž detail firmy s IČO 31333532"
- "ktoré firmy naberajú Python vývojárov?"
- "pridaj firmu s IČO 31333532 do CRM a naplánuj hovor o 3 dni"

## Dôležité - kredity a zápisy
- **enrich_contact** (email/telefón cez Lusha) **míňa kredity** (~10 za telefón). Nástroj ti
  najprv ukáže odhad ceny a zostatok - over to pred potvrdením.
- **push_lead / create_contacts** zapisujú do Odoo CRM **naozaj**. Vždy si over, čo robíš.

## Riešenie problémov
- **Nástroje sa neukázali:** skontroluj, či je `claude_desktop_config.json` validný JSON
  (čiarky, zátvorky), či sedí cesta k `mcp_server.py`, a **reštartuj** Claude Desktop.
- **python not found / ENOENT:** Python nie je na PATH. Daj plnú cestu k `python.exe`, alebo
  preinštaluj Python so zaškrtnutým "Add to PATH".
- **401 / invalid token:** zlý alebo chýbajúci token. Skontroluj `SOONAR_API_TOKEN`.
- **Connection error:** over `SOONAR_API_URL = https://soonar.zvar.it`.

Kde je konfiguračný súbor (ak by "Edit Config" nešiel):
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`