MCP Tools Reference: mapstools.googleapis.com

Araç: resolve_names

Belirli konum sorgularının (önemli yer adları veya tam adresler) toplu listesini standart Google Haritalar yer kimliklerine dönüştürür.

Giriş Koşulları (ÇOK ÖNEMLİ):

  1. queries (nesne dizisi - ZORUNLU): Çözülecek konum sorgularının listesi. En fazla 20 sorgu belirtebilirsiniz.

    • Her sorgu nesnesi şunları içermelidir:
      • text (dize - ZORUNLU): Çözümlenecek belirli bir yer adını veya adresi temsil eden metin sorgusu.
        • Örnekler: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (object - İSTEĞE BAĞLI): Belirli bir coğrafi bölgenin yakınındaki sonuçlara öncelik vermek için kullanılır.

    • Biçim: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (dize - İSTEĞE BAĞLI): Sonuçları etkilemek için kullanıcının Unicode CLDR bölge kodu (iki harfli ülke kodu, ör. US, CA).

Araç Çağrısı Talimatları:

  • Belirginlik (CRITICAL): Sorgular, belirli bir yer adını veya adresi temsil etmelidir. 'restaurants' gibi genel aramalar veya 'Starbucks' gibi zincir adları desteklenmez.
  • Çağırmayı planladığınız aşağı akış araçları, ham adres veya yer adı dizelerini doğrudan kabul ediyorsa bu aracı ÇAĞIRMAYIN.

Google Haritalar'a kaydetme:

  • Yanıt, save_to_maps_url alanını içerir: Başarıyla çözümlenen tüm yerleri içeren tek bir Google Haritalar bağlantısı.
  • Kullanıcı, çözümlenen yerleri Google Haritalar'da liste olarak kaydetmek, paylaşmak veya açmak istediğinde bu bağlantıyı kullanıcıya gösterin. Bu bağlantıyı KENDİNİZ OLUŞTURMAYIN.

Hata İşleme (KRİTİK):

  • Bu bir toplu işleme aracıdır. Bir istek "karma sonuçlar" döndürebilir (ör. bazı sorgular başarıyla çözülürken diğerleri başarısız olur).
  • results çıkış listesinin, queries giriş dizinleriyle 1:1 eşleneceği garanti edilir. Başarısız bir sorgu, results listesindeki ilgili dizinde boş bir Result mesajıyla (entity ayarlanmamış) sonuçlanır.
  • Hangi sorgu dizininin başarısız olduğunu belirlemek için yanıttaki failed_requests harita alanını KONTROL ETMELİSİNİZ. failed_requests anahtarı, istekteki başarısız sorgunun 0 tabanlı dizinini temsil eder. Kısmi bir hata nedeniyle tüm toplu çağrının başarısız olduğunu varsaymayın.

Aşağıdaki kod örneğinde, resolve_names MCP aracını çağırmak için curl simgesinin nasıl kullanılacağı gösterilmektedir.

Curl İsteği 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Giriş Şeması

ResolveNames için istek mesajı.

ResolveNamesRequest

JSON gösterimi 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Alanlar
queries[]

object (LocationQuery)

Zorunlu. Çözümlenecek konum sorgularının listesi. En fazla 20 sorgu belirtebilirsiniz.
locationBias

object (LocationBias)

İsteğe bağlıdır. Çözünürlük sonuçlarını etkilemek için isteğe bağlı bir bölge. Belirtilmişse çözüm sonuçları, bu bölgeye daha yakın olan öğelerden yana olacaktır. location_bias veya region_code gibi karakterler eklemek, arama alanını daraltarak genellikle daha iyi sonuçlar sağlar.

Hem location_bias hem de region_code belirtilmişse location_bias, region_code'ye göre öncelikli olur.
regionCode

string

İsteğe bağlıdır. Çözümleme sonuçlarını etkilemek için isteğe bağlı bir bölge kodu. Belirtilmişse çözüm sonuçları, belirtilen bölgede veya bölgenin yakınında bulunan öğelerden yana olacaktır. Bu, bir CLDR bölge kodu olmalıdır. Örneğin, "US" veya "CA". location_bias veya region_code gibi karakterler eklemek, arama alanını daraltarak genellikle daha iyi sonuçlar sağlar.

Hem location_bias hem de region_code belirtilmişse location_bias, region_code'ye göre öncelikli olur.

LocationQuery

JSON gösterimi 
{
  "text": string
}
Alanlar
text

string

Zorunlu. Google Haritalar'da belirli bir coğrafi varlığa (ör. yer veya adres) çözümlenecek metin sorgusu. Sorgu ne kadar ayrıntılı olursa çözüm o kadar doğru olur. Örneğin, "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" veya "Eiffel Tower, Paris". Sorgular belirli bir adres veya yer adı olmalıdır. Zincir adı (ör. Starbucks) gibi genel konumlar veya "restoranlar" gibi arama sorguları desteklenmez.

LocationBias

JSON gösterimi 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Alanlar
type birleşik alanı. Konum yanlılığının türü. type aşağıdakilerden yalnızca biri olabilir:
viewport

object (Viewport)

Sınırlayıcı kutuyla tanımlanan bir görüntü alanı.

Görüntü alanı

JSON gösterimi 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Alanlar
low

object (LatLng)

Zorunlu. Görüntü alanının en alt noktası.
high

object (LatLng)

Zorunlu. Görüntü alanının en yüksek noktası.

LatLng

JSON gösterimi 
{
  "latitude": number,
  "longitude": number
}
Alanlar
latitude

number

Enlem (derece). [-90.0, +90.0] aralığında olmalıdır.
longitude

number

Derece cinsinden boylam. [-180.0, +180.0] aralığında olmalıdır.

Çıkış şeması

ResolveNames için yanıt mesajı.

ResolveNamesResponse

JSON gösterimi 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Alanlar
results[]

object (Result)

Yalnızca çıkış. Konum sorgularından elde edilen çözümlenmiş varlıkların listesi. İsteğin queries dizinleriyle 1:1 eşleşeceği garanti edilir. i dizinindeki boş dize, bu sorgu için çözümlemenin başarısız olduğunu gösterir. Çözüm başarısız olduysa lütfen hata durumu için failed_requests alanını kontrol edin.
failedRequests

map (key: integer, value: object (Status))

Yalnızca çıkış. Kısmi hataları gösteren bir harita. Anahtar, queries alanındaki başarısız isteğin dizinidir. Değer, çözümün neden başarısız olduğunu ayrıntılı olarak açıklayan hata durumudur.

"key": value çiftlerinin listesini içeren bir nesne. Örnek: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Yalnızca çıkış. Başarıyla çözülen tüm öğeleri Google Haritalar'a kaydetme bağlantısı.

Sonuç

JSON gösterimi 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Alanlar
entity

object (Entity)

Yalnızca çıkış. Konum sorgusundan elde edilen çözümlenmiş öğe.
confidence

enum (Confidence)

Yalnızca çıkış. Çözümün güven düzeyi.

Varlık

JSON gösterimi 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Alanlar
entity birleşik alanı. Çözümlenen varlık türü. entity aşağıdakilerden yalnızca biri olabilir:
place

string

Çözümlenen yerin kaynak adı.

FailedRequestsEntry

JSON gösterimi 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Alanlar
key

integer
value

object (Status)

Durum

JSON gösterimi 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Alanlar
code

integer

Durum kodu, google.rpc.Code enum değeri olmalıdır.
message

string

Geliştiriciye yönelik hata mesajı (İngilizce olmalıdır). Kullanıcıya gösterilen tüm hata mesajları yerelleştirilmiş olup google.rpc.Status.details alanında gönderilmeli veya istemci tarafından yerelleştirilmelidir.
details[]

object

Hata ayrıntılarını içeren mesajların listesi. API'lerin kullanabileceği ortak bir mesaj türleri kümesi vardır.

Herhangi türde alanlar içeren bir nesne. Ek bir "@type" alanı, türü tanımlayan bir URI içerir. Örnek: { "id": 1234, "@type": "types.example.com/standard/id" }.

Tümü

JSON gösterimi 
{
  "typeUrl": string,
  "value": string
}
Alanlar
typeUrl

string

Serileştirilmiş Protobuf mesajının türünü, eğik çizgiyle biten bir önek ve tam nitelikli tür adından oluşan bir URI referansıyla tanımlar.

Örnek: type.googleapis.com/google.protobuf.StringValue

Bu dize en az bir / karakteri içermelidir ve son / karakterinden sonraki içerik, türün tam nitelikli adı olmalıdır. Bu ad, başında nokta olmadan kanonik biçimde olmalıdır. İstemcilerin bunlarla iletişime geçmeye çalışmaması için bu URI referanslarına şema yazmayın.

Önek rastgeledir ve Protobuf uygulamalarının, türü belirlemek için son / dahil olmak üzere her şeyi kaldırması beklenir. type.googleapis.com/, bazı eski uygulamaların gerektirdiği yaygın bir varsayılan önektir. Bu önek, türün kaynağını belirtmez ve bu öneki içeren URI'lerin herhangi bir isteğe yanıt vermesi beklenmez.

Tüm tür URL dizeleri, ek kısıtlamalarla (metin biçimi için) yasal URI referansları olmalıdır. Referansın içeriği yalnızca alfanümerik karakterler, yüzde kodlu kaçışlar ve aşağıdaki kümedeki karakterlerden (dış ters tırnaklar hariç) oluşmalıdır: /-.~_!$&()*+,;=. Yüzde kodlamalarına izin vermemize rağmen, mevcut ayrıştırıcılarla karışıklığı önlemek için uygulamalar bunları koddan çıkarmamalıdır. Örneğin, type.googleapis.com%2FFoo reddedilmelidir.

Any'nın orijinal tasarımında, bu tür URL'lerde bir tür çözümleme hizmeti başlatma olasılığı göz önünde bulundurulmuştu ancak Protobuf hiçbir zaman böyle bir hizmet uygulamadı ve bu URL'lere ulaşmanın sorunlu ve olası bir güvenlik sorunu olduğunu düşünüyor. URL'leri yazmaya çalışmayın.
value

string (bytes format)

type_url tarafından açıklanan türün Protobuf serileştirilmiş halini içerir.

Base64 kodlu bir dize.

Güven

Çözümün güven düzeyi.

Sıralamalar
CONFIDENCE_UNSPECIFIED Varsayılan değer. Bu değer kullanılmıyor.
MEDIUM Orta güven düzeyi, çözümün büyük olasılıkla doğru olduğunu ancak başka adayların da olabileceğini gösterir.
HIGH Yüksek güven, çözünürlüğün doğru olduğunu ve belirli bir coğrafi varlığı (ör. belirli bir yer) temsil ettiğini gösterir.

Araç Açıklamaları

Araç açıklamaları, belirli bir aracın temel riskini açıklamak için MCP istemcilerine gönderilir. Çoğu istemci bu ipuçlarını güvenilmeyen olarak değerlendirir ancak onay isteminin kullanıcıya ne zaman gönderileceğine karar vermek için kullanılabilirler.

Başlık dizesinin yanı sıra aşağıdaki Boole ipuçları şu şekilde tanımlanır:

  • readOnlyHint: Doğruysa araç, ortamını değiştirmez. Varsayılan: false.
  • destructiveHint: Doğruysa araç, yıkıcı işlemler gerçekleştirebilir. Yanlış ise araç yalnızca ekleme işlemleri gerçekleştirebilir. Varsayılan: true.
  • idempotentHint: Doğruysa aynı bağımsız değişkenlerle aracı tekrar tekrar çağırmanın ortamı üzerinde ek bir etkisi olmaz. Varsayılan: false.
  • openWorldHint: Doğruysa araç, harici öğelerin bulunduğu bir "açık dünya" ile etkileşim kurabilir. Yanlışsa araç yalnızca dahili öğelerle etkileşim kurabilir. Örneğin, bir web arama aracı açık dünya olurken bir bellek aracı açık dünya olmaz.

Yok Edici İpucu: ❌ | İdempotent İpucu: ❌ | Salt Okunur İpucu: ✅ | Açık Dünya İpucu: ❌