olx-pik-toolkit

Interni CLI i MCP server za upravljanje OLX.ba / PIK.ba shopovima. Jedno jezgro (src/core), dva lica: CLI (src/cli) i MCP server (src/mcp).

Zahtjevi

• Node.js 18 ili noviji (koristi se ugradjeni fetch).
• Odobren API pristup za shop (Gold ili Platinum + odobrenje OLX/PIK podrske). Provjeri sa olx whoami.

Brzi start

npm install
npm run build
cp .env.example .env     # popuni OLX_TOKEN ili OLX_USERNAME/OLX_PASSWORD
node dist/cli/index.js whoami

CLI primjeri

# Sigurno (citanje)
node dist/cli/index.js listings ls --state active --all
node dist/cli/index.js refresh limits
node dist/cli/index.js category suggest "golf 7"
node dist/cli/index.js sponsor price 12345 --type 2 --days 7 --refresh-every 8

# Obnova
node dist/cli/index.js refresh one 12345
node dist/cli/index.js refresh all --limit 200            # dry-run
node dist/cli/index.js refresh all --limit 200 --yes      # izvrsi

# Trosak kredita (uvijek trazi --yes)
node dist/cli/index.js sponsor apply 12345 --type 2 --days 7 --refresh-every 8 --yes

# Slike (URL-ovi i/ili lokalni fajlovi)
node dist/cli/index.js listings images add 12345 --url https://primjer.com/1.jpg https://primjer.com/2.jpg
node dist/cli/index.js listings images add 12345 --file ./slika1.jpg ./slika2.jpg
node dist/cli/index.js listings images main 12345 67890     # postavi glavnu sliku po imageId
node dist/cli/index.js listings images rm 12345 67890        # obrisi sliku

Napomena o slikama (potvrdjeno uzivo): API prima slike samo kao stvarne fajlove preko multipart/form-data, pod poljem images[]. Ne prihvata image_url. Zato --url prvo preuzme sliku pa je posalje kao fajl, a --file salje lokalni fajl direktno. Oba zavrse isto na POST /listings/:id/image-upload.

Snapshot kategorija i lokacija (statički, bez stalnog dohvatanja)

Kategorije i lokacije se rijetko mijenjaju, pa se jednom povuku u JSON i koriste kao statički MCP resource (olx://categories, olx://locations). Pokreni jednom kad token proradi:

node --env-file=.env dist/cli/index.js category dump      # -> olx-dokumentacija/categories.json
node --env-file=.env dist/cli/index.js location dump      # -> locations.json + locations.csv (lagani index)

category dump uz puni categories.json pravi i lagani categories.csv (index: id, parent_id, level, path, name + zastavice brand/model/has_models/show_condition/fee). CSV se regenerise iz JSON-a i bez API poziva: node dist/cli/index.js category index.

Zatim commitaj te fajlove. Poslije toga AI/MCP cita kategorije i lokacije iz resursa bez ijednog API poziva:

• olx://categories-index (CSV) za PRONALAZAK kategorije po imenu/path. Lagano, koristi prvo.
• olx://categories (puni JSON) samo kad trebas polja kojih nema u CSV-u.
• olx://locations-index (CSV) za country_id (BiH = 49) i city_id po imenu. Lagano, koristi prvo.
• olx://locations (puni JSON) samo za detalje (lat/lon, zip, state).

Za forme i opcije izabrane kategorije koristi live alat olx_category_attributes <id> (opcije nisu u snapshotu, dolaze iz API-ja). Pojedinacni live upiti su i dalje dostupni (category list/children/get/brands/models, location countries/cities/city).

Vise klijenata (profili, vise tokena)

Za vise OLX naloga (razliciti klijenti) koristi profile. Token nikad ne ide u git.

Konfiguracija (bilo koji od tri nacina):

• Fajl .olx-profiles.json u korijenu (kopiraj iz .olx-profiles.example.json):

  {
    "default": "klijent_a",
    "profiles": {
      "klijent_a": { "token": "...", "base_url": "https://api.olx.ba" },
      "klijent_b": { "token": "..." }
    }
  }
  

• Ili env varijable OLX_TOKEN_<IME> (npr. OLX_TOKEN_KLIJENTA=...).
• Ili OLX_PROFILES_FILE za drugu putanju do fajla.

CLI: biraj profil po pozivu sa --profile:

node dist/cli/index.js --profile klijent_a listings ls --all
node dist/cli/index.js --profile klijent_b refresh all --limit 200 --yes
node dist/cli/index.js auth profiles            # lista konfigurisanih profila

Bez --profile koristi se OLX_PROFILE, pa default iz fajla, pa obican OLX_TOKEN.

MCP: jedan server radi na jednom nalogu (radi sigurnosti, da se nalozi ne mijesaju). Za vise klijenata registruj vise servera u .mcp.json, svaki sa svojim OLX_PROFILE:

{
  "mcpServers": {
    "olx-klijent-a": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/mcp/server.js"],
      "env": { "OLX_PROFILE": "klijent_a", "OLX_PROFILES_FILE": ".olx-profiles.json" }
    },
    "olx-klijent-b": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/mcp/server.js"],
      "env": { "OLX_PROFILE": "klijent_b", "OLX_PROFILES_FILE": ".olx-profiles.json" }
    }
  }
}

Alat olx_list_accounts pokazuje aktivni nalog i sve profile.

MCP server

npm run build
node dist/mcp/server.js   # radi preko stdio

Za kolege: kloniranje i dodavanje MCP-a u Claude Code

Repozitorij ima .mcp.json u korijenu, pa Claude Code automatski ponudi olx-pik MCP server kad otvoriš projekat. Token se NE čuva u repou; svako postavlja svoj kroz env varijablu OLX_TOKEN.

Koraci poslije kloniranja:

# 1. Build (dist/ je u .gitignore, pa se mora lokalno izgraditi)
npm install
npm run build

# 2. Postavi svoj token u okruzenje (zamijeni vrijednost svojim tokenom)
export OLX_TOKEN=tvoj_token        # zsh/bash; trajno dodaj u ~/.zshrc ili ~/.bashrc

# 3. Otvori Claude Code u korijenu repozitorija
claude

Pri prvom otvaranju Claude Code pita da odobriš projektni MCP server olx-pik. Potvrdi, pa provjeri sa /mcp. Server preuzima OLX_TOKEN iz tvog okruzenja preko ${OLX_TOKEN} u .mcp.json.

Alternativa bez .mcp.json (registracija samo za tebe, token ostaje lokalno):

claude mcp add olx-pik -s user \
  -e OLX_TOKEN=tvoj_token \
  -e OLX_BASE_URL=https://api.olx.ba \
  -- node "$(pwd)/dist/mcp/server.js"

Napomene:

• Bez postavljenog OLX_TOKEN server se podigne, ali API pozivi vraćaju 401/403. Provjeri pristup sa node --env-file=.env dist/cli/index.js whoami ili kroz MCP alat olx_whoami.
• Token nikad ne commitati. .env i pravi tokeni su u .gitignore.

Claude Code skillovi

Repozitorij nosi i dva skilla u .claude/skills/ (folder je skriven u file browserima jer pocinje tackom, ali je u gitu):

• olx-mcp-setup: postavljanje i koristenje toolkita (token, MCP, CLI, troubleshooting).
• olx-analiza-profila: analiza vlastitog profila i oglasa uz strategiju iz KB resursa.

Dolaze automatski sa kloniranjem; nista se ne instalira posebno.

Detaljan plan za repo, build, MCP integraciju u Claude Code i rollout tima je u PLAN.md. Strateska i API referenca za AI je u olx-dokumentacija/OLX_PIK_AI_Knowledgebase.md.