Mapbox

Mapbox MCP Sunucusu

Mapbox API'leri için Model Context Protocol (MCP) uygulayan Node.js sunucusu.

Yapay Zeka Uygulamalarınız için Coğrafi Zeka

Mapbox MCP Sunucusu, herhangi bir yapay zeka aracısını veya uygulamasını, Mapbox'ın kapsamlı konum zekası platformuna sorunsuz erişim sağlayarak coğrafi farkındalığa sahip bir sisteme dönüştürür. Bu sunucu sayesinde yapay zekanız yerleri anlayabilir ve bunlar hakkında akıl yürütebilir, fiziksel dünyada gezinme yapabilir ve aşağıdakiler dahil zengin coğrafi verilere erişebilir:

• Küresel coğrafi kodlama ile adresleri ve yer adlarını koordinatlara ve tersini dönüştürme
• Dünya genelinde milyonlarca işletme, simge yapı ve yer üzerinde ilgi çekici nokta (POI) araması
• Gerçek zamanlı trafikle araba, yürüyüş ve bisiklet için çok modlu rota planlama
• Erişilebilirliği analiz etmek ve lojistiği optimize etmek için seyahat süresi matrisleri
• Birden fazla durak için en uygun ziyaret sırasını bulmak üzere rota optimizasyonu (gezgin satıcı problemi)
• Temiz rota görselleştirmesi için GPS izlerini yol ağına oturtan harita eşleştirme
• Belirli zaman veya mesafe kısıtlamaları dahilinde ulaşılabilir alanları görselleştirmek için izokron üretimi
• Sohbet içinde doğrudan gerçek bir Mapbox GL JS haritasında rotaları, arama sonuçlarını ve kendi özel GeoJSON'unuzu görüntülemek için canlı, etkileşimli harita oluşturma (render_map_tool)
• Konumların, rotaların ve coğrafi verilerin görsel temsillerini oluşturmak için statik harita görüntüleri
• API çağrıları gerektirmeden mesafe, alan, kerteriz, tampon bölge ve mekansal analiz için çevrimdışı coğrafi hesaplamalar

İster bir yapay zeka seyahat asistanı, ister lojistik optimizasyon aracı, ister konum tabanlı öneri sistemi veya "nerede"yi anlaması gereken herhangi bir uygulama geliştiriyor olun, Mapbox MCP Sunucusu bunu mümkün kılacak mekansal zekayı sağlar. Ayrıca Claude Desktop ve VS Code gibi popüler istemcilerde de etkinleştirebilirsiniz. Ayrıntılar için aşağıya bakın.

Kullanım

Bu MCP sunucusunu kullanmak için bir Mapbox erişim belirteci gereklidir.

Barındırılan MCP Uç Noktası

Hızlı erişim için barındırılan MCP uç noktamızı kullanabilirsiniz:

Uç Nokta: https://mcp.mapbox.com/mcp

Farklı istemciler ve API kullanımı için ayrıntılı kurulum talimatları için Barındırılan MCP Sunucu Kılavuzu bölümüne bakın.

Mapbox erişim belirteci almak için:

1. mapbox.com/signup adresinden ücretsiz bir Mapbox hesabı oluşturun
2. Hesap sayfanıza gidin
3. Yeni bir belirteç oluşturun veya varsayılan genel belirteci kullanın

Mapbox erişim belirteçleri hakkında daha fazla bilgi için Mapbox'ın erişim belirteçleri belgelerine bakın.

Entegrasyon Kılavuzları

Farklı entegrasyonlar için ayrıntılı kurulum talimatları için aşağıdaki kılavuzlara bakın:

• Claude Desktop Kurulumu - Claude Desktop'ı bu MCP sunucusuyla çalışacak şekilde yapılandırma talimatları
• Goose Kurulumu - Goose AI aracı çerçevesini kurma
• VS Code Kurulumu - Visual Studio Code'da geliştirme ortamı kurma
• Cursor AI IDE Kurulumu - Cursor AI IDE'de geliştirme ortamı kurma
• Smolagents Entegrasyonu - Smolagents AI aracılarını Mapbox araçlarına bağlamayı gösteren örnek
• Araçları Doğrudan İçe Aktarma - MCP sunucusunu çalıştırmadan kendi uygulamalarınızda Mapbox araçlarını kullanma
• render_map_tool Kılavuzu - Harita görselleştirme ilkel öğesi: tam yük şeması ve başka hiçbir Mapbox aracı olmadan kendi verilerinizi bağımsız olarak oluşturma
• Elicitations - search_and_geocode_tool ve directions_tool kullanıcıdan sonuçları netleştirmesini veya bir rota seçmesini nasıl ister ve istemci bunu desteklemediğinde nasıl zarif bir şekilde geri döner

Örnek Komutlar

Kurulumdan sonra bu komutları Claude Desktop veya diğer MCP istemcileriyle deneyin:

Konum Temellendirme

Koordinat öncelikli sorgular için — "çevremde ne var", "bu hangi mahalle", "N dakikada nereye ulaşılır" — ground_location_tool kullanın. Tek bir çağrıda ters coğrafi kodlama, kategori araması ve izokronu birleştirir, sorguya göre doğru stratejiyi uyarlayarak seçer ve alıntılarla birlikte yazılmış kayıtlar (adlar, adresler, koordinatlar, mesafeler, ulaşılabilirlik çokgenleri) döndürür.

Aşağıdaki dört komutun her biri tek bir araç çağrısında farklı bir strateji uygular:

• Mahalle — "47.6097, -122.3408 hangi mahallede ve çevremde ne var?"
• POI — "40.7580, -73.9855 koordinatlarına 10 dakikalık yürüme mesafesindeki kahve dükkanları"
• Bölge — "37.7749, -122.4194'ten 15 dakikalık yürüyüşle nereye ulaşabilirim?"
• Rota — "34.0522, -118.2437'ye birini bırakmak için en yakın sürülebilir nokta"

Konum Keşfi

• "Empire State Binası'na yürüme mesafesindeki kahve dükkanlarını bul"
• "Seattle'dan Portland'a gitmek istiyorum, yol üzerinde Starbucks var mı?"
• "Boston'dan New York'a giden rota üzerindeki benzin istasyonlarını göster"
• "Times Square yakınında hangi restoranlar var?"

Navigasyon ve Seyahat

• "LAX'tan Hollywood'a güncel trafikle araba tarifleri al"
• "Central Park'tan Times Square'e yürümek ne kadar sürer?"
• "Otelimden (Four Seasons) JFK Havalimanı'na yoğun saatte taksiyle seyahat süresini hesapla"

Görselleştirme ve Haritalar

• "Mapbox harita oluşturma aracını kullanarak Golden Gate Köprüsü'nden San Francisco'daki Union Square'e yol tariflerini göster" — gerçek bir Mapbox haritasında canlı, etkileşimli bir rota oluşturur
• "Golden Gate Köprüsü'nden Fisherman's Wharf'a giden rotayı her iki konumda işaretleyicilerle gösteren bir harita görüntüsü oluştur"
• "Önemli simge yapıları işaretlenmiş Manhattan'ın uydu görünümünü göster"
• "Seattle şehir merkezinin bir mil yakınındaki tüm Starbucks konumlarını vurgulayan bir harita oluştur"
• "Şu koordinatların üzerinde 'Depo' etiketli bir işaretleyiciyle dolu bir çokgen göster: [...]" — kendi GeoJSON'unuzu doğrudan render_map_tool ile oluşturur, başka hiçbir Mapbox aracına gerek yoktur

Analiz ve Planlama

• "Portland şehir merkezinden arabayla 30 dakikada ulaşılabilen alanları göster"
• "Denver'daki bu 3 otel konumu (Marriott, Sheraton ve Hilton) ile kongre merkezi arasındaki seyahat süresi matrisini hesapla"
• "San Francisco'daki bu 3 turistik cazibe merkezini (Golden Gate, Musical Stairs ve Fisherman's Wharf) ziyaret etmek için en uygun rotayı bul"
• "Bu 8 adres için teslimat rotasını optimize et: [adres listesi]"

GPS ve Rota Eşleştirme

• "Bu GPS izini temizle ve yollardaki gerçek rotayı göster: [zaman damgalı koordinat listesi]"
• "Kaydedilmiş bu bisiklet sürüşünü bisiklet ağına oturt: [GPS koordinatları]"
• "Bu sürüş rotasını yol ağıyla eşleştir ve trafik sıkışıklığı seviyelerini göster"

Çevrimdışı Coğrafi Hesaplamalar

• "Bu iki koordinat arasındaki mesafe mil cinsinden nedir?"
• "Bu çokgenin alanını kilometrekare cinsinden hesapla"
• "37.7749°K, 122.4194°B noktası bu hizmet alanı çokgeninin içinde mi?"
• "San Francisco'dan New York'a kerteriz nedir?"
• "Londra ile Paris arasındaki orta noktayı bul"
• "Bu konumun çevresinde 5 millik bir tampon bölge oluştur"
• "Bu mahalle sınırının merkez noktasını hesapla"
• "Bu rota koordinatları için sınırlayıcı kutu nedir?"
• "Nokta sayısını azaltmak için bu karmaşık çokgeni basitleştir"

Daha İyi Sonuçlar İçin İpuçları

• Konumlar konusunda spesifik olun (tam adresler veya simge yapı adları kullanın)
• Tercih ettiğiniz seyahat yöntemini belirtin (araba, yürüyüş, bisiklet)
• İlgili olduğunda zaman kısıtlamaları ekleyin ("yoğun saatte", "öğleden sonra 3'te")
• Gerektiğinde belirli çıktı biçimleri isteyin ("harita görüntüsü olarak", "JSON biçiminde")

Ayrıntılı örnekler: Farklı kullanım durumları ve MCP Inspector test talimatlarıyla rota boyunca arama komutunun kapsamlı örnekleri için examples/search-along-route.md dosyasına bakın.

Kaynaklar

MCP sunucusu statik referans verilerini MCP kaynakları olarak sunar. Kaynaklar, istemcilerin araç çağrıları yapmadan doğrudan başvurabileceği salt okunur verilere erişim sağlar.

Mevcut Kaynaklar

Mapbox Kategorileri Kaynağı

URI Deseni: mapbox://categories veya mapbox://categories/{language}

Kategori arama aracıyla kullanılmak üzere mevcut kategori kimliklerinin tam listesine erişin. Kategoriler, arama sonuçlarını türe göre filtrelemek için kullanılabilir (ör. "restaurant", "hotel", "gas_station").

Örnekler:

• mapbox://categories - Varsayılan (İngilizce) kategori listesi
• mapbox://categories/ja - Japonca kategori adları
• mapbox://categories/es - İspanyolca kategori adları

Kaynaklara Erişim:

• Yerel MCP kaynak desteğine sahip istemciler: resources/read MCP protokol yöntemini kullanın
• Kaynak desteği olmayan istemciler: Kaynak URI'si ile resource_reader_tool kullanın

Zengin Harita Önizlemeleri (render_map_tool)

Bu sunucudaki her coğrafi araç (rota tarifleri, izokron, arama ve daha fazlası) sonucunu render_map_tool aracılığıyla canlı, etkileşimli bir Mapbox GL JS haritası olarak görüntüleyebilir — sunucunun tek görselleştirme ilkel öğesi. Desteklenen istemcilerde, sohbetin içinde doğrudan bağımsız bir HTML paneli olarak MCP Apps protokolü (@modelcontextprotocol/ext-apps) aracılığıyla Tam Ekran geçişiyle oluşturulur:

• Claude Desktop ✅
• VS Code ile GitHub Copilot ✅
• Claude Code ✅
• Goose ✅

Bu sunucunun diğer araçlarından hiçbirine ihtiyacınız yok. render_map_tool ayrıca doğrudan elle oluşturulmuş GeoJSON'u da kabul eder — kendi çokgenleriniz, işaretleyicileriniz ve rotalarınız — directions_tool, isochrone_tool veya başka herhangi bir Mapbox API çağrısına bağımlılık olmadan. Yük şeması ve eksiksiz bağımsız bir örnek için tam render_map_tool kılavuzuna bakın.

MCP Apps desteği olmayan istemcilerde garantili statik bir görüntüye ihtiyacınız varsa, bunun yerine static_map_image_tool kullanın — her istemcinin görüntüleyebileceği base64 kodlu bir PNG/JPEG döndürür.

CLIENT_NEEDS_RESOURCE_FALLBACK

Kaynak Geri Dönüş Araçları (Uyumlu Olmayan İstemciler için Opt-In)

Kaynaklar, çoğu istemci tarafından desteklenen temel bir MCP özelliğidir (Claude Desktop, VS Code, MCP Inspector vb.). Ancak bazı istemciler (smolagents gibi) kaynakları hiç desteklemez. Bu istemciler için sunucu, kaynaklarla aynı içeriği ancak araç çağrıları aracılığıyla sunan "kaynak geri dönüş araçları" sağlayabilir.

Geri Dönüş Araçları:

• resource_reader_tool - URI ile herhangi bir kaynağı okumak için genel geri dönüş
• category_list_tool - Kategori listesine erişim sağlar (mapbox://categories)

Varsayılan olarak bu araçlar DAHİL DEĞİLDİR (istemcinizin kaynakları desteklediği varsayılır). İstemciniz kaynakları desteklemiyorsa, geri dönüş araçlarını etkinleştirin:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Bunu ne zaman ayarlamalı:

• ✅ smolagents veya kaynak desteği olmayan diğer istemcileri kullanıyorsanız true olarak ayarlayın
• ❌ Claude Desktop, VS Code, MCP Inspector veya kaynak destekli herhangi bir istemci kullanıyorsanız ayarlanmamış bırakın (varsayılan)
• ❌ Emin değilseniz ayarlanmamış bırakın (çoğu istemci kaynakları destekler)

Araçlar

Yardımcı Araçlar

Kaynak Okuyucu Aracı

Yerel MCP kaynak API'sini desteklemeyen istemciler için MCP kaynaklarına erişim sağlar. Kategori listesi gibi kaynakları okumak için bu aracı kullanın.

Parametreler:

• uri: Okunacak kaynak URI'si (ör. mapbox://categories, mapbox://categories/ja)

Örnek Kullanım:

• Varsayılan kategorileri okuyun: {"uri": "mapbox://categories"}
• Japonca kategorileri okuyun: {"uri": "mapbox://categories/ja"}

Not: MCP istemciniz yerel kaynakları destekliyorsa, daha iyi performans için kaynak API'sini doğrudan kullanmayı tercih edin.

Çevrimdışı Coğrafi Araçlar

Bu araçlar, Mapbox API çağrıları gerektirmeden tamamen çevrimdışı coğrafi hesaplamalar gerçekleştirir. Doğru coğrafi hesaplamalar için Turf.js kullanırlar ve internet bağlantısı olmadan bile her yerde çalışırlar.

Mesafe Aracı

Haversine formülünü kullanarak iki coğrafi koordinat arasındaki mesafeyi hesaplayın.

Özellikler:

• Birden fazla birimi destekler: kilometre, mil, metre, fit, deniz mili
• Doğru büyük daire mesafesi hesaplaması
• API çağrısı gerekmez

Örnek Kullanım: "San Francisco (37.7749°K, 122.4194°B) ile New York (40.7128°K, 74.0060°B) arasındaki mesafe nedir?"

Çokgen İçindeki Noktalar Aracı

Bir veya daha fazla noktayı bir çokgene veya çoklu çokgene karşı test eder, yalnızca içeride olanları döndürür. Tek bir çağrıda tek bir noktayı veya bir grubu işler.

Özellikler:

• Karmaşık çokgenler (delikler dahil) ile çalışır
• Çoklu çokgenleri destekler
• Tek çağrıda herhangi bir sayıda noktayı toplu olarak test eder
• Coğrafi sınırlama, teslimat bölgesi doğrulama ve müşteri segmentasyonu için kullanışlıdır

Örnek Kullanım: "Bu teslimat adreslerinden hangileri hizmet alanımızın içinde?"

Hedef Aracı

Bir başlangıç noktası, kerteriz ve mesafe verildiğinde jeodezik (büyük daire) sapma kullanarak bir hedef noktası hesaplayın.

Özellikler:

• Yönlendirilmiş bir yol değil, düz çizgi sapması
• "X'in 5 km kuzeyinde bir nokta bul" veya arama sapmaları oluşturmak için kullanışlıdır
• API çağrısı gerektirmez

Örnek Kullanım: "Space Needle'ın 10 km kuzeydoğusundaki nokta nedir?"

Kerteriz Aracı

Bir koordinattan diğerine pusula yönünü (kerteriz) hesaplayın.

Özellikler:

• Kerterizi derece cinsinden döndürür (0-360°)
• Ana yönü sağlar (K, KD, D, GD, G, GB, B, KB)
• Navigasyon ve yön sorguları için kullanışlıdır

Örnek Kullanım: "Buradan havaalanına gitmek için hangi yöne gitmeliyim?"

Orta Nokta Aracı

Büyük daire yolu boyunca iki koordinat arasındaki coğrafi orta noktayı bulun.

Özellikler:

• Dünya'nın eğri yüzeyindeki gerçek orta noktayı hesaplar
• Buluşma noktası önerileri için kullanışlıdır
• Uzun mesafeli hesaplamaları doğru şekilde işler

Örnek Kullanım: "San Francisco ile New York arasında yarı yol neresi?"

Merkez Noktası Aracı

Bir çokgenin veya çoklu çokgenin geometrik merkezini (merkez noktası) hesaplayın.

Özellikler:

• Karmaşık şekillerle çalışır
• Tüm noktaların aritmetik ortalamasını döndürür
• Etiket veya işaretçi yerleştirmek için kullanışlıdır

Örnek Kullanım: "Bu mahalle sınırı için bir işaretçiyi nereye yerleştirmeliyim?"

Alan Aracı

Bir çokgenin alanını hesaplayın.

Özellikler:

• Birden çok birimi destekler: metrekare, kilometrekare, dönüm, hektar, mil kare, fit kare
• Dünya yüzeyinde doğru alan hesaplaması
• Her boyuttaki çokgenlerle çalışır

Örnek Kullanım: "Bu parkın alanı dönüm cinsinden nedir?"

Sınırlayıcı Kutu Aracı

Bir geometriyi içeren minimum sınırlayıcı kutuyu (bbox) hesaplayın.

Özellikler:

• Noktalar, çizgiler, çokgenler ve çoklu çokgenlerle çalışır
• [minimumBoylam, minimumEnlem, maksimumBoylam, maksimumEnlem] döndürür
• Görünüm alanı hesaplamaları ve uzamsal dizinleme için kullanışlıdır

Örnek Kullanım: "Bu rota için sınırlayıcı kutu nedir?"

Tampon Aracı

Bir nokta, çizgi veya çokgen etrafında bir tampon bölge (çokgen) oluşturun.

Özellikler:

• Birden çok mesafe birimini destekler
• Noktalar etrafında dairesel tamponlar oluşturur
• Yakınlık analizi ve etki bölgeleri oluşturmak için kullanışlıdır

Örnek Kullanım: "Bu konumun etrafında 5 km'lik bir tampon bölge göster"

Basitleştirme Aracı

Douglas-Peucker algoritmasını kullanarak bir çizgi veya çokgendeki köşe sayısını azaltın.

Özellikler:

• Ayrıntı düzeyi için yapılandırılabilir tolerans
• Karmaşıklığı azaltırken genel şekli korur
• Dosya boyutlarını küçültmek ve işleme performansını artırmak için kullanışlıdır
• Topolojiyi koruma seçeneği (kendi kendine kesişmeleri önleme)

Örnek Kullanım: "Nokta sayısını azaltmak için bu karmaşık sınırı basitleştir"

Uzunluk Aracı

Bir dizi koordinatla tanımlanan bir çizginin toplam uzunluğunu ölçün.

Özellikler:

• Kilometre, mil, metre ve fit destekler
• Yönlendirme API çağrısı olmadan çizilmiş bir rotayı, yolu veya sınırı ölçmek için kullanışlıdır

Örnek Kullanım: "Bu yürüyüş parkuru ne kadar uzun?"

Dışbükey Aracı

Bir dizi noktanın dışbükey gövdesini hesaplayın — hepsini içeren en küçük dışbükey çokgen.

Özellikler:

• Sınırlayıcı alan analizi veya kapsama alanı tahmini için kullanışlıdır
• API çağrıları olmadan çevrimdışı çalışır

Örnek Kullanım: "Tüm bu mağaza konumlarını içeren en küçük çokgen nedir?"

En Yakın Nokta Aracı

Bir koleksiyonda verilen bir hedef noktaya en yakın noktayı bulun.

Özellikler:

• Her aday için distance_tool çağırmak ve sıralamaktan daha verimlidir
• Bir konuma en yakın mağazayı, durağı veya simgesel yapıyı bulmak için kullanışlıdır

Örnek Kullanım: "Bu mağazalardan hangisi şu anki konumuma en yakın?"

Çizgi Üzerinde En Yakın Nokta Aracı

Bir noktayı bir çizgi veya rota üzerindeki en yakın konuma yaslayın, bu noktayı ve ona olan mesafeyi döndürün.

Özellikler:

• "Bu rotadaki hangi nokta konumuma en yakın?" veya API çağrısı olmadan harita eşleştirme için kullanışlıdır

Örnek Kullanım: "Bu yürüyüş parkurunda şu anda en yakın olduğum yer neresi?"

Birleşim, Kesişim ve Fark Araçları

İki veya daha fazla çokgeni birleştirin veya karşılaştırın — union_tool bunları tek bir geometride birleştirir, intersect_tool paylaştıkları alanı bulur ve difference_tool birini diğerinden çıkarır.

Özellikler:

• Hizmet alanlarını birleştirmek, kapsama alanı örtüşmesini bulmak veya hariç tutma bölgelerini hesaplamak için kullanışlıdır (ör. "A bölgesi tarafından kapsanan ancak B bölgesi tarafından kapsanmayan nedir?")
• Tamamen çevrimdışı çalışır — API çağrısı gerekmez
• Her biri, sonucun doğrudan görselleştirilebilmesi için bir render_map_tool referansı döndürür

Örnek Kullanım: "Bu iki teslimat bölgesini tek bir kapsama alanında birleştir" / "Bu iki izokron nerede örtüşüyor?" / "Bu hizmet alanının 15 dakikalık izokronumuz tarafından kapsanmayan kısmı nedir?"

Mapbox API Araçları

Kategori Listesi Aracı (Kullanımdan Kaldırıldı)

⚠️ Kullanımdan Kaldırıldı: Bunun yerine resource_reader_tool URI'si mapbox://categories olan aracı kullanın veya istemciniz MCP kaynaklarını destekliyorsa mapbox://categories kaynağına doğrudan erişin.

Bu araç, MCP kaynaklarını veya resource_reader_tool'u desteklemeyen istemcilerle geriye dönük uyumluluk için korunmaktadır.

Matris Aracı

Mapbox Matris API kullanarak birden çok nokta arasındaki seyahat sürelerini ve mesafeleri hesaplar. Özellikler şunları içerir:

• Verimli bire-çok, çoktan-bire veya çoktan-çok yönlendirme hesaplamaları
• Farklı seyahat profilleri için destek (trafikli-sürüş, sürüş, yürüyüş, bisiklet)
• Trafik bilinçli hesaplamalar için kalkış saati belirtimi
• Mesafe ve süre metrikleriyle rota özetleme
• Yaklaşım kontrolü (kaldırım/kısıtlamasız) ve izin verilen kalkış kerterizleri aralığı

Statik görüntü aracı

Mapbox statik görüntü API kullanarak statik harita görüntüleri oluşturur. Özellikler şunları içerir:

• Özel harita stilleri (sokaklar, açık hava, uydu vb.)
• Ayarlanabilir görüntü boyutları ve yakınlaştırma seviyeleri
• Özel renkler ve etiketlerle birden çok işaretçi desteği
• Çoklu çizgiler ve çokgenler dahil kaplama seçenekleri
• Belirtilen koordinatlara otomatik sığdırma

Kategori arama aracı

Mapbox Arama Kutusu kategori arama API kullanarak bir kategori araması gerçekleştirir. Özellikler şunları içerir:

• Kategoriye göre ilgi çekici noktaları arayın (restoranlar, oteller, benzin istasyonları vb.)
• Coğrafi yakınlığa göre filtreleme
• Özelleştirilebilir sonuç limitleri
• Her sonuç için zengin meta veriler
• Birden çok dil desteği

Ters coğrafi kodlama aracı

Mapbox coğrafi kodlama V6 API kullanarak ters coğrafi kodlama gerçekleştirir. Özellikler şunları içerir:

• Coğrafi koordinatları insan tarafından okunabilir adreslere dönüştürün
• Özelleştirilebilir ayrıntı seviyeleri (sokak, mahalle, şehir vb.)
• Türe göre sonuç filtreleme (adres, ilgi çekici nokta, mahalle vb.)
• Birden çok dil desteği
• Zengin konum bağlam bilgisi

Zemin konumu aracı

"Bu koordinatın yakınında ne var" sorularını tek çağrıda yanıtlar — yer adı, yakındaki ilgi çekici noktalar ve seyahat süresi erişilebilirliği — alıntılarla canlı Mapbox verilerinden alınır. Bunun yerine reverse_geocode_tool'i bir web aramasıyla zincirlemek yerine bunu kullanın.

Özellikler:

• Sorguyu sınıflandırır (yönlendirme, mahalle bağlamı, ilgi çekici nokta araması veya bölge/erişilebilirlik) ve yalnızca ilgili verileri getirir
• İstendiğinde kategoriye göre yakındaki ilgi çekici nokta araması
• Seyahat süresi erişilebilirlik özeti (izokron tabanlı)
• Temellendirilmiş konum ve yakındaki ilgi çekici noktaların çizildiği bir render_map_tool referansı döndürür

Örnek Kullanım: "Bu koordinat hangi mahallede ve yakınlarda kahve dükkanı var mı?"

Yer ayrıntıları aracı

Mapbox Kimliğini kullanarak belirli bir yer hakkında ayrıntılı bilgi alır — fotoğraflar, çalışma saatleri, puanlar, telefon numaraları ve web sitesi URL'leri. Belirli bir sonuç hakkında daha fazla ayrıntı almak için search_and_geocode_tool, category_search_tool veya reverse_geocode_tool sonrasında kullanın.

Örnek Kullanım: "Bana ilk kahve dükkanı sonucu hakkında daha fazla bilgi ver — saatler, telefon numarası ve web sitesi"

Yönler aracı

Mapbox Yönler API kullanarak yönlendirme talimatlarını getirir. Özellikler şunları içerir:

• Farklı yönlendirme profilleri için destek: sürüş (canlı trafik veya tipik), yürüyüş ve bisiklet
• Birden çok ara noktadan rota (2-25 koordinat çifti)
• Alternatif rota seçeneği
• Rota ek açıklamaları (mesafe, süre, hız, tıkanıklık)
• Planlama seçenekleri:
  • Sürüş ve trafikli-sürüş profilleri için gelecekteki kalkış saati (depart_at)
  • Yalnızca sürüş profili için istenen varış saati (arrive_by)
• Profile özel optimizasyonlar:
  • Sürüş: araç boyutu kısıtlamaları (yükseklik, genişlik, ağırlık)
• Yönlendirme için hariç tutma seçenekleri:
  • Yaygın hariç tutmalar: feribot rotaları, yalnızca nakit geçiş ücretleri
  • Sürüşe özel hariç tutmalar: geçiş ücretleri, otoyollar, asfaltlanmamış yollar, tüneller, ülke sınırları, eyalet sınırları
  • Özel nokta hariç tutmaları (kaçınılacak 50'ye kadar coğrafi nokta)
• GeoJSON geometri çıktı formatı

İzokron aracı

Mapbox İzokron API kullanarak bir konumdan belirli bir süre içinde ulaşılabilen alanları hesaplar. Özellikler şunları içerir:

• Farklı seyahat profilleri için destek (sürüş, yürüyüş, bisiklet)
• Özelleştirilebilir seyahat süreleri veya mesafeler
• Birden çok kontur oluşturma (ör. 15, 30, 45 dakikalık aralıklar)
• İsteğe bağlı kalkış veya varış saati belirtimi
• Görselleştirme için renk özelleştirme

Arama ve coğrafi kodlama aracı

Bu API tarafından desteklenen ilgi çekici noktaları, adresleri, yerleri ve diğer tüm türleri aramak ve coğrafi kodlamak için Mapbox Arama Kutusu Metin Arama API uç noktasını kullanır. Bu araç, daha önce bu MCP sunucusunun önceki sürümlerinde ForwardGeocodeTool ve PoiSearchTool tarafından sağlanan işlevselliği tek bir araçta birleştirir.

Harita eşleştirme aracı

Mapbox Harita Eşleştirme API kullanarak GPS izlerini yol ağına yaslar. Özellikler şunları içerir:

• Gürültülü GPS izlerini yol ağında temiz rotalara dönüştürün
• Farklı seyahat profilleri için destek (sürüş, trafikli-sürüş, yürüyüş, bisiklet)
• İstek başına 100'e kadar koordinat çiftini işleyin
• Hıza dayalı doğruluk için isteğe bağlı zaman damgaları
• Farklı GPS kalite seviyeleri için yapılandırılabilir yaslama yarıçapları
• Rota ek açıklamaları (hız limitleri, mesafe, süre, trafik tıkanıklığı)
• Birden çok geometri çıktı formatı (GeoJSON, çoklu çizgi)

Örnek Kullanım: "Bu GPS izini temizle ve yollara yasla: [zaman damgalı koordinatlar]"

Optimizasyon aracı

Mapbox Optimizasyon API kullanarak birden çok konum arasındaki en uygun rotayı bulur. Özellikler şunları içerir:

• 2-12 konum için gezgin satıcı problemini (TSP) çözün
• Farklı seyahat profilleri için destek (sürüş, trafikli-sürüş, yürüyüş, bisiklet)
• Esnek başlangıç ve bitiş noktası yapılandırması
• Gidiş-dönüş veya tek yönlü yolculuk optimizasyonu
• Dönüşümlü navigasyon talimatları (isteğe bağlı)
• Rota ek açıklamaları (mesafe, süre, hız)
• Birden çok geometri çıktı formatı (GeoJSON, çoklu çizgi)

Örnek Kullanım: "Bu 5 durağı ziyaret etmek için en uygun rotayı bul: [adres veya koordinat listesi]"

Not: Gelişmiş özelliklere sahip (zaman pencereleri, kapasite kısıtlamaları, birden çok araç) bir V2 API mevcuttur ancak beta erişimi gerektirir. V2 uygulaması kod tabanına dahildir ancak varsayılan olarak kayıtlı değildir.

Geliştirme

Sunucuyu inceleme

Node.js kullanarak

# Run the built image
npm run inspect:build

Docker kullanarak

# Build the Docker image
docker build -t mapbox-mcp-server .

# Run and inspect the server
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-server

Yeni araç oluştur

npx plop create-tool
# provide tool name without suffix (e.g. Search)

Yeni Sürüm Yayınlama

# 1. Bump version in package.json
npm version <new-version> --no-git-tag-version

# 2. Sync version to manifest.json and server.json
npm run sync-manifest

# 3. Prepare CHANGELOG (replaces "Unreleased" with version and date)
npm run changelog:prepare-release <new-version>

# 4. Update package-lock.json
npm install

# 5. Review changes, then commit and tag
git add package.json package-lock.json manifest.json server.json CHANGELOG.md
git commit -m "Release v<new-version>"
git tag v<new-version>
git push && git push --tags

Önemli: Yayıncı iş akışı, package.json ve server.json sürümlerinin yayın sürümüyle eşleştiğini doğrular. Sürüm artışını veya bildirim senkronizasyonunu atlamak yayın hatalarına neden olur.

OpenTelemetry İzleme

Bu MCP sunucusu, üretim gözlemlenebilirliği için kapsamlı OpenTelemetry izleme içerir:

Hızlı Demo

# 1. Copy the example configuration
cp .env.example .env

# 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing

# 3. Start Jaeger for local development
npm run tracing:jaeger:start

# 4. Run the server (it will automatically use .env configuration)
npm run inspect:build

# 5. View traces at http://localhost:16686

# 6. Stop Jaeger when done
npm run tracing:jaeger:stop

Not: Sunucu, başlangıçta yapılandırmayı otomatik olarak .env dosyanızdan yükler. .env.example dosyası, birden fazla gözlemlenebilirlik platformu için yapılandırma örnekleri içerir.

Desteklenen Gözlemlenebilirlik Platformları

.env.example içinde yer alan yapılandırma örnekleri:

Bulut Sağlayıcıları:

• ☁️ AWS X-Ray
• ☁️ Azure Monitor (Application Insights)
• ☁️ Google Cloud Trace

SaaS Platformları:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 OTLP uyumlu herhangi bir arka uç

Üretim Yapılandırması

Tam kurulum talimatları için docs/tracing.md bölümüne bakın:

• 🔧 Platforma özel yapılandırma kılavuzları
• 📊 Kimlik doğrulama ve uç nokta kurulumu
• 🎯 Özel izleme öznitelikleri ve bağlam
• 🚀 Performans optimizasyonu (minimum ek yük)
• 🔍 Sorun giderme ve hata ayıklama

İzleme Özellikleri:

• ✅ Yapılandırma yükleme izleme (.env dosyası yükleme)
• ✅ Otomatik araç yürütme izleme
• ✅ CloudFront korelasyon kimlikleriyle HTTP isteği enstrümantasyonu
• ✅ Yapılandırılabilir dışa aktarıcılar (konsol, OTLP)
• ✅ Güvenlik odaklı (veri koruma, JWT doğrulama)
• ✅ Üretime hazır (<%1 CPU ek yükü)

Katkıda Bulunma

Mapbox MCP Sunucusu'na katkılarınızı memnuniyetle karşılıyoruz! Bir çekme isteği göndermeden önce lütfen CONTRIBUTING.md dosyasını okuyun.

Tam standartlar ve yönergeler:

• CONTRIBUTING.md - Başlangıç, çekme isteği süreci, hızlı referans
• Mühendislik Standartları (docs/engineering_standards.md) - Eksiksiz kod kalitesi, test, dokümantasyon ve iş birliği standartları
• Claude Code Kılavuzu (CLAUDE.md) - Claude Code kullanan katkıda bulunanlar için standartlar ve desenler
• AI Ajan Talimatları (AGENTS.md) - Diğer AI kodlama asistanları için kılavuz (Cursor, Continue, Aider, vb.)
• GitHub Copilot Yönergeleri - GitHub Copilot'u sorumlu bir şekilde kullanmak için en iyi uygulamalar

Katkıda Bulunanlar için Hızlı Başlangıç

1. Depoyu çatallayın ve çatalınızı klonlayın
2. Bağımlılıkları yükleyin: npm install
3. Kodlama standartlarımıza uyarak değişikliklerinizi yapın
4. Testleri ve lint'i çalıştırın: npm test && npm run lint
5. Yeni işlevler için testler ekleyin
6. Net bir açıklamayla bir çekme isteği gönderin

Tüm katkılar CI kontrollerimizden ve kod inceleme sürecimizden geçmelidir. Ayrıntılı gereksinimler için docs/engineering_standards.md bölümüne bakın.

Veri Kullanımı ve Gizlilik

Mapbox API'lerine hangi veriler gönderilir

MCP sunucu araçlarını kullandığınızda, aşağıdaki veriler ortamınızdan doğrudan Mapbox API'lerine gönderilir:

• Coğrafi kodlama araçları: Adres/konum metni, koordinatlar, ülke/bölge filtreleri
• Arama araçları: Arama sorguları, yakınlık için konum koordinatları, kategori filtreleri
• Yönlendirme aracı: Başlangıç/bitiş koordinatları, ara noktalar, rota tercihleri, araç kısıtlamaları
• Matris aracı: Birden fazla koordinat çifti, seyahat profili, kalkış saatleri
• Statik harita aracı: Koordinatlar, yakınlaştırma düzeyi, stil tercihleri, işaretçi bilgileri
• Eşzamanlılık aracı: Başlangıç koordinatları, zaman/mesafe parametreleri, seyahat profili

Gizliliğiniz

• Yerel yürütme: Tüm API çağrıları ortamınızdan doğrudan Mapbox API'lerine yapılır
• Belirteç güvenliği: Mapbox API belirteciniz yerel makinenizde kalır ve bu MCP sunucusuna asla iletilmez veya bu sunucu tarafından saklanmaz
• Veri depolama yok: Bu MCP sunucusu verilerinizi veya API isteklerinizi saklamaz, günlüğe kaydetmez veya toplamaz
• Doğrudan iletişim: Sizinle Mapbox API'leri arasında aracı sunucu yoktur

Üçüncü taraf veri kullanımı

• Mapbox'ın gizlilik politikası, API'lerine gönderilen verileri yönetir: https://www.mapbox.com/legal/privacy/
• API kullanımı: Standart Mapbox API koşulları, bu araçlar aracılığıyla yapılan tüm istekler için geçerlidir
• Veri saklama: Veri saklama politikaları için Mapbox'ın dokümantasyonuna bakın

Destek ve İletişim

MCP Sunucu Sorunları İçin

• E-posta: mcp-feedback@mapbox.com
• GitHub Sorunları: Hataları ve özellik isteklerini bildirin

Mapbox API Soruları İçin

• Mapbox Desteği: https://support.mapbox.com/
• Dokümantasyon: https://docs.mapbox.com/
• API Durumu: https://status.mapbox.com/

Bakım Taahhüdü

Bu MCP sunucusu resmi olarak Mapbox, Inc. tarafından bakımı yapılmaktadır. Şunları sağlıyoruz:

• Yeni Mapbox API özellikleri için düzenli güncellemeler
• Hata düzeltmeleri ve güvenlik güncellemeleri
• En son MCP protokol sürümleriyle uyumluluk
• GitHub sorunları aracılığıyla topluluk desteği

---

MIT Lisansı