market-fiyati-mcp
by gokhancvs
README.md
# Market Fiyatı MCP
> **Resmî değildir.** Bu proje Market Fiyatı, TÜBİTAK veya market zincirleriyle bağlantılı değildir ve onlar tarafından onaylanmamıştır.
> Kullanım koşulları operatörün sorumluluğundadır: [Amaç ve kullanım izinleri](#amaç-ve-kullanım-izinleri).
**Başlayın:** Aşağıdaki yapılandırmayı MCP istemcinize ekleyin.
Türkiye'de ürün, şube fiyatı ve sepet karşılaştırması için MCP sunucusu.
**Node.js 22+ gerekir.** Normal kullanım gerçek fiyat sorguları için `live` modudur;
`offline` geliştirme ve test içindir. Aşağıdaki örnek, önceki sürümlerde de çalışması için modu açıkça seçer.
## 1. İstemciye ekleyin
**Şube keşfi:** Ürün aramaları şube ID'si ister; yakındaki şubeleri bulan tool deneysel erişim gerektirir.
Bu ayar yakın şube, market listesi, adres/koordinat arama, toplu ürün güncelleme ve alternatif ürün tool'larını açar.
Bu yüzden örnek `"MARKET_FIYATI_ENABLE_EXPERIMENTAL": "true"` içerir. Ayarın varsayılanı `false` olarak kalır;
şube ID'lerinizi zaten biliyorsanız bu satırı silebilirsiniz.
```json
{
"mcpServers": {
"market-fiyati": {
"command": "npx",
"args": ["-y", "market-fiyati-mcp@2.0.2"],
"env": {
"MARKET_FIYATI_MODE": "live",
"MARKET_FIYATI_LATITUDE": "41.025591",
"MARKET_FIYATI_LONGITUDE": "28.974075",
"MARKET_FIYATI_DISTANCE": "4",
"MARKET_FIYATI_ENABLE_EXPERIMENTAL": "true"
}
}
}
}
```
**Örnek: Galata Kulesi — `41.025591, 28.974075`.**
`distance=4`, merkezden **4 km yarıçap** demektir (8 km çap).
**Sayı tipi:** Tool girdisindeki koordinat ve yarıçap tırnaksız JSON sayısıdır.
Yalnız `env` değerleri ortam değişkeni olduğu için tırnaklıdır; sunucu bunları sayıya çevirir.
`market_find_nearby_depots` için aynı örnek, tırnaksız sayılarla:
```json
{ "latitude": 41.025591, "longitude": 28.974075, "distance": 4 }
```
### Yapılandırma dosyası nerede?
Yukarıdaki `market-fiyati` girdisini istemcinizin dosyasına ekleyin ve istemciyi yeniden başlatın.
| İstemci | Dosya | Not |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`<br>Windows: `%APPDATA%\Claude\claude_desktop_config.json` | `mcpServers` anahtarı |
| Claude Code | Proje: `.mcp.json` · Komut: `claude mcp add` · Kullanıcı geneli: `claude mcp add-json -s user` | `mcpServers` anahtarı |
| Cursor | Genel: `~/.cursor/mcp.json` · Proje: `.cursor/mcp.json` | `mcpServers` anahtarı |
| VS Code | Proje: `.vscode/mcp.json` | Üst anahtar `servers`; girdiye `"type": "stdio"` ekleyin |
| Codex | `~/.codex/config.toml` | TOML: `[mcp_servers.market-fiyati]` ve `.env` tablosu |
Kendi konumunuz için koordinatları değiştirin. Kişisel konumunuzu özel istemci ayarında tutun; Git'e eklemeyin.
Env konumu 1.0.6'dan beri desteklenir ([yarıçap geçişi](docs/api.md#106-yarıçap-geçişi)). Paket kurulamıyorsa [kaynak koddan çalıştırın](#kaynak-koddan-geliştirme).
`npx` paketi indirir; bulunamazsa mutlak yolunu kullanın. [Hazır Galata yapılandırması](examples/mcp-config.json).
## 2. Bağlantıyı doğrulayın
Sunucuyu yeniden başlatıp AI'ya şunu yazın:
> `market_status` çağır. Modu ve konum ayarının hazır olup olmadığını göster.
**Beklenen:** `data.mode=live`, `data.liveRequestsEnabled=true`, `data.locationDefaults.configured=true`.
Status yalnız ayarları kontrol eder; gerçek fiyat için sonraki adımdaki aramayı yapın.
## 3. Fiyat sorgulayın
AI'ya istediğiniz ürünü ve marketleri söyleyin. Konum ayarı hazırsa tekrar vermeniz gerekmez.
Şubeler bilinmiyorsa yukarıda açtığınız deneysel erişimle `market_find_nearby_depots` bir kez çağrılır;
ürün aramasında dönen şube ID'leri kullanılır. Adımlar: [Gerçek fiyatlarla sorgulama](docs/live-testing.md).
### Örnek istekler
> Yakınımdaki şubelerde 1 litre yarım yağlı sütün en ucuz fiyatı ne?
> 3 kg yoğurdu fiyata göre sırala; tam eşleşmeleri ve alternatifleri ayrı göster.
> 500 g beyaz peynirin fiyatını şubeler arasında karşılaştır ve harita linklerini ver.
> 1 kg patates, 2 L süt ve 10'lu yumurtadan oluşan sepeti şube bazında karşılaştır.
> 1 kg toz şekerin fiyat geçmişini özetle.
Ürün adlarını ve paket boyutlarını açık yazın. "Sadece tam eşleşme" gibi kesin şartları belirtin;
aksi hâlde AI benzer ürünleri ayrı başlıkta açıklayarak önerebilir.
## Konum nasıl çalışır?
| Durum | Kural |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| Env kullanıyorum | Üç değeri birlikte ayarlayın; AI her sorguda tekrar sormaz. |
| Env kullanmıyorum | Üçünü de kaldırın; enlem, boylam ve yarıçapı her konumlu çağrıda sağlayın. |
| Başka konum arıyorum | Enlem/boylamı birlikte verin. Distance yoksa env yarıçapı kullanılır. |
| Eksik veya geçersiz değer | Env hatalıysa sunucu başlamaz; çağrı hatalıysa o çağrı reddedilir. Varsayılan yarıçap yoktur. |
| Ayarı değiştirdim | Env için yeniden başlatın. Çağrıdaki değişiklik yalnız o çağrıya aittir. |
Şubeler (`depots`) ürün çağrısında ayrıca gerekir; MCP bunları saklamaz.
Aynı süreç env konumunu paylaşır; farklı kullanıcılar ayrı süreç veya açık çağrı değerleri kullanmalıdır.
[Tüm konum kuralları ve sınırlar](docs/api.md#konum-ve-şube-bağlamı).
## Yapabilecekleriniz
| Amaç | Tool |
| ---------------------------- | ------------------------------- |
| Ürün ara | `market_search_products` |
| Şube fiyatlarını karşılaştır | `market_compare_product_offers` |
| Sepet karşılaştır | `market_compare_basket` |
| Fiyat geçmişini incele | `market_get_price_history` |
| Çağrı akışını öğren | `market://guide` |
**15 tool · 3 resource · 3 prompt.** Satın alma, sipariş ve barkod sorgusu desteklenmez.
## Sonuçları doğru okuyun
- Fiyatlar **TRY**. `percentage` indirim oranı değildir; API'nin [`discount` işaretine](docs/api.md#discount-işaretini-okuma) bakın.
- Eksik offer **bilinmiyor** demektir; “stok yok” veya “tüm fiyatlar tarandı” denemez.
- Eksik sepette `total=null`; `subtotal` yalnız bulunan ürünlerdir.
- Fiziksel şube karşılaştırması için `groupBy=depot` kullanın; zincir tek bir şube değildir.
- Sepet en fazla **5 ürün** alır; bütçe retry dâhil 5 HTTP denemesidir. Retry açıksa ürün sınırı düşer
(`market_status` içindeki `limits.basketItems`). Listeyi bölerek veya tool değiştirerek aşmayın.
## Sorun giderme
| Hata veya belirti | Neden ve çözüm |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NETWORK_DISABLED` | İstemci ayarında `MARKET_FIYATI_MODE=offline` vardır veya 1.0.7 ya da daha eski bir sürüm kuruludur. Değeri `live` yapıp sunucuyu yeniden başlatın. Değişkeni silmek yalnız 1.0.8 ve sonrasında yeterlidir. Ağsız geliştirme ortamında `offline` kalmalıdır. |
| `EXPERIMENTAL_DISABLED` | Yakın şube, adres arama gibi deneysel tool'lar kapalıdır. Ayara `"MARKET_FIYATI_ENABLE_EXPERIMENTAL": "true"` ekleyip yeniden başlatın veya şube ID'lerini kendiniz verin. |
| `OUTPUT_TOO_LARGE` | Yanıt yerel boyut sınırını aştı; kısmi veri dönmez. Aynı sorguyu tekrarlamayın: sayfa boyutunu (`size`), şube veya sepet ürünü sayısını azaltın. |
| `sh: market-fiyati-mcp: command not found` / Claude Code `Connection closed` | İstemci, `package.json` dosyası sabitlenen sürümle aynı `market-fiyati-mcp` olan bir klasörde (bu repo'nun checkout'u) başlatılmıştır; npx yayımlanmış paket yerine yerel projeyi çözer. `args` listesinde `-y`'den önce `"--prefix", "<klasör>"` ekleyin. `<klasör>`, `market-fiyati-mcp` `package.json`'u olmayan bir klasörün mutlak yoludur (ör. ev dizininiz). |
| Claude Code büyük sonucu dosyaya taşıyor | Yanıt boyutu ürün ve şube sayısıyla büyür. 2026-10-07 tarihli live oturumda 25 ürün × 25 şubelik aramalar istemcinin çıktı sınırını aştı, 15 ürün × 25 şube altında kaldı. Daha az şube veya daha küçük `size` kullanın ya da istemci ortamında `MAX_MCP_OUTPUT_TOKENS` değerini yükseltin. |
| Sunucu listede görünmüyor (Windows) | Claude Desktop MSIX paketiyle kurulduysa (Microsoft Store, WinGet veya resmî kurucu) uygulamanın dosyayı `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json` yolundan okuduğu [bildiriliyor](https://github.com/anthropics/claude-code/issues/26073). Settings > Developer > "Edit Config" ise `%APPDATA%` altındaki dosyayı açabilir. `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc` klasörü varsa `mcpServers` girdisini bu dosyaya ekleyin ve uygulamayı tamamen kapatıp açın; klasör yoksa bu satır sizin için geçerli değildir. Bu yol resmî belgede yer almaz. |
Diğer hata kodları: [API](docs/api.md#diğer-hata-kodları).
## Kaynak koddan geliştirme
Depoyu klonlayıp çalıştırın:
```sh
npm ci --ignore-scripts
MARKET_FIYATI_MODE=offline npm run check
```
`check` derlemeyi de yapar. İstemcide `command: "node"`, `args` içinde `dist/src/index.js` dosyasının
mutlak yolunu kullanın. Geliştirirken istemci env ayarını açıkça `MARKET_FIYATI_MODE=offline` yapın;
testlerin ağ engeli de korunur. Gerekirse `node` yolunu da mutlak yazın.
Sunucu stdio JSON-RPC kullanır; HTTP portu açmaz. Geliştirmede `MARKET_FIYATI_MODE=offline npm start`
MCP mesajlarını bekler. Mod ayarı olmadan başlangıç `live` seçer; yalnız başlatmak HTTP isteği göndermez.
stdout yalnız MCP trafiğidir. npm kurulumu ağ kullanabilir; uygulama testleri API'ye bağlanmaz.
## Ayrıntı gerektiğinde
| İhtiyaç | Belge |
| ------------------------------- | -------------------------------------------------------------------------------- |
| Gerçek fiyatları sorgula | [Gerçek fiyatlarla sorgulama](docs/live-testing.md) |
| Tool, filtre ve yanıt kuralları | [API](docs/api.md) |
| Ayarlar ve kod yapısı | [Mimari](docs/architecture.md) |
| Testler ve sınırları | [Doğrulama](docs/verification.md) · [Sentetik kabul](docs/offline-acceptance.md) |
| Sürüm çıkarma | [Yayın rehberi](docs/releasing.md) · [CHANGELOG](CHANGELOG.md) |
## Amaç ve kullanım izinleri
Bu proje, ticari kazanç veya başka bir çıkar gözetilmeden geliştirilmiş bağımsız bir çalışmadır.
Market Fiyatı'nın, TÜBİTAK'ın veya market zincirlerinin resmî ürünü değildir. Herhangi bir onay,
sponsorluk veya ortaklık iddiası yoktur.
[Market Fiyatı kullanım koşullarını](https://marketfiyati.org.tr/kullanim-kosullari) değerlendirmek ve
kullanımına uygun izinleri sağlamak operatörün sorumluluğundadır. Bu depo üçüncü taraf servislerine
erişim izni vermez; `live` ayarı yalnız teknik erişimi belirler.
Güvenlik açığı bildirmek için [özel bildirim yönergesini](SECURITY.md) kullanın.
## Lisans
[MIT](LICENSE) — Copyright (c) 2026 Gökhan Çavuş.
Lisans yalnızca yazılımı ve beraberindeki belgeleri kapsar. Üçüncü tarafların verilerine, markalarına,
logolarına veya servislerine erişim hakkı vermez. Yukarıdaki amaç beyanı MIT lisansını değiştirmez ve
koda ticari kullanım yasağı eklemez. Üçüncü taraf bileşenler kendi lisanslarına tabidir.
TDQS
A3.8/5.0
Scored across 15 tools
Disambiguation4/5
Most tools have clearly distinct purposes (geocoding, depots, categories, search, comparison, history), but a few boundaries blur: market_compare_product_offers vs market_get_product both return one product's branch offers, and market_find_alternatives vs market_find_similar_products both surface related items. The unusually verbose descriptions help disambiguate, but an agent could still misselect between these pairs.
Naming Consistency4/5
All 15 tools use a uniform market_ prefix with snake_case verb_noun patterns (list_markets, get_product, search_products, compare_basket, find_nearby_depots). The only deviation is market_status, which lacks a verb, but the overall convention is highly predictable.
Tool Count5/5
15 tools sit at the top of the ideal 3-15 range and each earns its place, covering geocoding, depot discovery, category browsing, keyword search, product lookup, offer comparison, basket comparison, price history, and sync. No redundant or filler tools for the stated scope.
Completeness4/5
The read-only price-comparison domain is well covered end-to-end: location resolution, depot discovery, category navigation, search, single-product and basket comparison, history, and alternatives/similar products. Minor gaps exist (e.g., barcode lookup explicitly unsupported, no richer market/chain detail), but core agent workflows have no dead ends.
Maintenance
ActivityMaintained
ResponsivenessNo issues