letgo-mcp

Letgo.com uzerinde arama yapma, ilan detaylarini goruntuleme ve filtreleme gibi islemleri yapmanizi saglayan bir Model Context Protocol (MCP) sunucusu. Playwright tarayici otomasyonu kullanarak Letgo'nun Akamai anti-bot korumasini asar ve gercek kullanici deneyimine yakin bir sekilde veriye erisir.

Ozellikler

• Sehir ve ilce bazinda konum belirleme

• Otomatik tamamlama onerilerini getirme

• Ilan arama (fiyat araligi, siralama, kategori ve sayfalama destegi)

• Tekil ilan detaylarini goruntuleme (aciklama, satici bilgisi, gorseller)

• Sonsuz kaydirma (infinite scroll) ile "Daha Fazla Yukle" butonuna otomatik tiklayarak tum sonuclari toplama

• Akamai anti-bot korumasina karsi oturum yenileme

• Ag (network) isteklerini yakalayarak debug etme

• Herhangi bir API anahtari gerektirmez

Related MCP server: Playwright Plus Python MCP

Gereksinimler

• Node.js v22 veya uzeri

• npm (Node.js ile birlikte gelir)

• Playwright tarayici motoru (kurulum sirasinda otomatik indirilir)

Kurulum

# Projeyi klonlayin
git clone <repo-url>
cd letgo-mcp

# Bagimliliklari yukleyin
npm install

# Playwright tarayicisini indirin
npx playwright install chromium

# Projeyi derleyin
npm run build

Derleme sonucunda dist/ klasoru altinda calistirilabilir JavaScript dosyalari olusur.

MCP Yapilandirmasi

letgo-mcp bir stdio MCP sunucusu olarak calisir. MCP destekli bir istemciye (Claude Desktop, OpenCode, vs.) asagidaki gibi eklenir:

Claude Desktop

claude_desktop_config.json dosyasina ekleyin:

{
  "mcpServers": {
    "letgo-mcp": {
      "command": "node",
      "args": ["/path/to/letgo-mcp/dist/index.js"]
    }
  }
}

OpenCode

.opencode.json dosyasina ekleyin:

{
  "mcpServers": {
    "letgo-mcp": {
      "command": "node",
      "args": ["/path/to/letgo-mcp/dist/index.js"]
    }
  }
}

Yolu projenizin tam dizin yolu ile degistirin.

Kullanim

Araclarin dogru sirada kullanilmasi gerekir. Asagidaki akis izlenmelidir:

1. Konum belirleme - letgo_set_location ile arama yapilacak sehir belirlenir. Bu adim her aramadan once mutlaka cagrilmalidir.

2. Arama - letgo_search_listings ile ilanlarda arama yapilir. Dilerse letgo_search_suggestions ile otomatik tamamlama onerileri alinabilir.

3. Detay - letgo_get_listing_details ile bir ilanin tum detaylari goruntulenir.

4. Bakim - Oturum sorunu yasanirsa letgo_refresh_session cagrilir. Ag isteklerini incelemek icin letgo_debug_network kullanilir.

Komut Satirindan Calistirma

# Derleme
npm run build

# Calistirma (stdio MCP sunucusu olarak)
npm start

# Gelistirme modu (derle + calistir)
npm run dev

Tools Referansi

Mimari

Proje iki ana bilesenden olusur:

Session Yonetimi (session.ts): Playwright ile bir Chromium tarayici ornegi baslatir. Tarayici headless: false modunda (gorunur) calisir. Letgo'nun Akamai bot tespitini gecmek icin cesitli onlemler alinir:

• Gercekci kullanici aracisi (user agent) ve viewport yapilandirmasi

• navigator.webdriver bayraginin gizlenmesi

• Turkce dil ve Istanbul saat dilimi ayarlari

• page.evaluate(fetch) yontemi ile API cagrilari yapilir, boylece tarayicinin mevcut cookie ve oturum bilgileri kullanilir

• Tarayici kapanirsa veya hata alinirsa otomatik olarak yeniden baslatilir

API Istemcisi (api-client.ts): Letgo'nun kendi API endpoint'lerine (/api/suggestions) ve DOM uzerinden ilan sayfalarina erisir. Arama sonuclari DOM scraping ile toplanir: sayfadaki "Daha Fazla Yukle" butonuna otomatik tiklanarak sonsuz kaydirma (infinite scroll) simule edilir, ardindan a[href*="/item/"] selector'u ile ilan kartlari ayiklanir.

Tool Handler (index.ts): MCP SDK uzerinden 6 araci (tool) tanimlar. Gelen istekleri api-client.ts ve session.ts modulusundeki fonksiyonlara yonlendirir. Girdi ve cikti semalari MCP standartlarina uygun sekilde tanimlanmistir.

Veri Akisi

MCP Istemcisi -> stdio -> index.ts (handler) -> 
  api-client.ts -> session.ts (Playwright) -> Letgo.com

Tum HTTP istekleri tarayici icinden (browser context) yapilir. Bu sayede Letgo'nun oturum ve cookie mekanizmasi sorunsuz calisir.

Onemli Notlar

• API anahtari gerekmez. Letgo'nun kendi web arayuzu uzerinden calisir, resmi bir API kullanilmaz.

• Tarayici gorunur calisir (headless: false). Letgo, Akamai anti-bot nedeniyle headless tarayicilari engelleyebilir. Bu nedenle tarayici penceresi acik kalir.

• Konum zorunludur. letgo_set_location cagrilmadan hicbir arama yapilamaz. Sehir adi Turkce karakterlerle girilmelidir (ornek: "Izmir", "Istanbul", "Ankara").

• Oturum sureleri sinirlidir. Letgo'nun Akamai cookie'leri belirli bir sure gecerli kalir. letgo_refresh_session ile oturum yenilenebilir.

• Rate limiting. Cok sik istek gonderildiginde Letgo gecici olarak erisimi kisitlayabilir. Oturum yenileme genelde bu sorunu cozer.

• DOM scraping. Arama sonuclari Letgo'nun HTML DOM'undan ayiklanir. Letgo arayuz degisikligi yaparsa scraping selector'larinin guncellenmesi gerekebilir.

• Sadece Turkiye. Letgo Turkiye platformu icin tasarlanmistir. Konum verileri Turkiye sehirlerini kapsar.