MCP Tools Reference: mapstools.googleapis.com

Narzędzie: resolve_names

Rozpoznaje listę zbiorczą konkretnych zapytań o lokalizację (nazwy punktów orientacyjnych lub dokładne adresy) i przekształca je w kanoniczne identyfikatory miejsc w Mapach Google.

Wymagania dotyczące danych wejściowych (KRYTYCZNE):

  1. queries (tablica obiektów – WYMAGANA): lista zapytań o lokalizację do rozwiązania. Możesz podać maksymalnie 20 zapytań.

    • Każdy obiekt zapytania musi zawierać:
      • text (ciąg tekstowy – WYMAGANY): zapytanie tekstowe reprezentujące konkretną nazwę miejsca lub adres do rozpoznania.
        • Przykłady: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (obiekt – OPCJONALNY): użyj tego parametru, aby nadać priorytet wynikom w pobliżu określonego obszaru geograficznego.

    • Format: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (ciąg znaków – OPCJONALNY): kod regionu Unicode CLDR (dwuliterowy kod kraju, np. US, CA) użytkownika, który ma być używany do filtrowania wyników.

Instrukcje dotyczące wywołania narzędzia:

  • Konkretność (KRYTYCZNA): zapytania muszą zawierać konkretną nazwę miejsca lub adres. Ogólne wyszukiwania, takie jak 'restaurants', lub nazwy sieci, takie jak 'Starbucks', nie są obsługiwane.
  • NIE wywołuj tego narzędzia, jeśli narzędzia, które planujesz wywołać, akceptują już bezpośrednio nieprzetworzone ciągi znaków adresu lub nazwy miejsca.

Zapisywanie w Mapach Google:

  • Odpowiedź zawiera pole save_to_maps_url: pojedynczy link do Map Google zawierający wszystkie miejsca, które udało się znaleźć.
  • Gdy użytkownik chce zapisać, udostępnić lub otworzyć znalezione miejsca jako listę w Mapach Google, wyświetl mu ten link. NIE twórz tego linku samodzielnie.

Obsługa błędów (KRYTYCZNE):

  • To narzędzie do przetwarzania wsadowego. Żądanie może zwrócić „mieszane wyniki” (np. niektóre zapytania zostaną rozwiązane, a inne nie).
  • Lista wyjściowa results jest gwarantowana do mapowania 1:1 z indeksami wejściowymi queries. Nieudane zapytanie spowoduje wyświetlenie pustego komunikatu Result (nie ustawiono entity) w odpowiednim indeksie na liście results.
  • MUSISZ sprawdzić pole mapy failed_requests w odpowiedzi, aby określić, który indeks zapytania nie został utworzony. Klucz failed_requests reprezentuje indeks nieudanego zapytania w żądaniu (liczony od 0). Nie zakładaj, że całe wywołanie zbiorcze nie powiodło się z powodu częściowego błędu.

Poniższy przykładowy kod pokazuje, jak używać curl do wywoływania narzędzia MCP resolve_names.

Żądanie Curl 
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
}'

Schemat wejściowy

Komunikat żądania dla ResolveNames.

ResolveNamesRequest

Zapis JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Pola
queries[]

object (LocationQuery)

Wymagane. Lista zapytań o lokalizację do rozwiązania. Możesz podać maksymalnie 20 zapytań.
locationBias

object (LocationBias)

Opcjonalnie: Opcjonalny region, który ma wpływać na wyniki rozpoznawania. Jeśli jest określony, wyniki rozpoznawania będą faworyzować elementy, które znajdują się bliżej tego regionu. Uwzględnienie location_bias lub region_code często daje lepsze wyniki, ponieważ zawęża zakres wyszukiwania.

Jeśli określono zarówno location_bias, jak i region_code, location_bias ma pierwszeństwo przed region_code.
regionCode

string

Opcjonalnie: Opcjonalny kod regionu, który wpływa na wyniki rozpoznawania. Jeśli podasz region, wyniki rozpoznawania będą faworyzować elementy, które znajdują się w podanym regionie lub w jego pobliżu. Powinien to być kod regionu CLDR. Na przykład „PL” lub „CA”. Uwzględnienie location_bias lub region_code często daje lepsze wyniki, ponieważ zawęża zakres wyszukiwania.

Jeśli określono zarówno location_bias, jak i region_code, location_bias ma pierwszeństwo przed region_code.

LocationQuery

Zapis JSON 
{
  "text": string
}
Pola
text

string

Wymagane. Zapytanie tekstowe, które ma zostać przekształcone w konkretny element geoprzestrzenny w Mapach Google, np. miejsce lub adres. Im bardziej szczegółowe zapytanie, tym dokładniejsze rozwiązanie. Na przykład „Warszawa”, „Googleplex, Mountain View, CA”, „1600 Amphitheatre Parkway, Mountain View, CA” lub „Wieża Eiffla, Paryż”. Zapytania muszą zawierać konkretny adres lub nazwę miejsca. Ogólne lokalizacje, takie jak nazwa sieci (np.Starbucks) lub zapytanie, np. „restauracje”, nie są obsługiwane.

LocationBias

Zapis JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Pola
Pole zbiorcze type. Typ lokalizacji. type może mieć tylko jedną z tych wartości:
viewport

object (Viewport)

Widoczny obszar zdefiniowany przez ramkę ograniczającą.

Widoczny obszar

Zapis JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Pola
low

object (LatLng)

Wymagane. Dolny punkt widocznego obszaru.
high

object (LatLng)

Wymagane. Najwyższy punkt widocznego obszaru.

LatLng

Zapis JSON 
{
  "latitude": number,
  "longitude": number
}
Pola
latitude

number

Szerokość geograficzna w stopniach. Musi mieścić się w zakresie [-90,0, +90,0].
longitude

number

Długość geograficzna w stopniach. Musi mieścić się w zakresie [-180,0, +180,0].

Schemat wyjściowy

Wiadomość z odpowiedzią dla ResolveNames.

ResolveNamesResponse

Zapis JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Pola
results[]

object (Result)

Tylko dane wyjściowe. Lista rozpoznanych elementów z zapytań o lokalizację. Gwarantowane mapowanie 1:1 z indeksami żądania queries. Pusty ciąg znaków w indeksie i wskazuje, że nie udało się rozpoznać tego zapytania. Jeśli rozpoznanie się nie powiodło, sprawdź pole failed_requests, aby poznać stan błędu.
failedRequests

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

Tylko dane wyjściowe. Mapa zawierająca informacje o częściowych niepowodzeniach. Klucz to indeks nieudanego żądania w polu queries. Wartość to stan błędu, który szczegółowo opisuje, dlaczego rozpoznanie się nie powiodło.

Obiekt zawierający listę par "key": value. Przykład: { "name": "wrench", "mass": "1.3kg", "count": "3" }
saveToMapsUrl

string

Tylko dane wyjściowe. link do zapisania wszystkich prawidłowo rozpoznanych podmiotów w Mapach Google.

Wynik

Zapis JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Pola
entity

object (Entity)

Tylko dane wyjściowe. Rozpoznana encja z zapytania o lokalizację.
confidence

enum (Confidence)

Tylko dane wyjściowe. Poziom ufności dla rozwiązania.

Jednostka

Zapis JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Pola
Pole zbiorcze entity. Rozpoznany typ encji. entity może mieć tylko jedną z tych wartości:
place

string

Nazwa zasobu rozpoznanego miejsca.

FailedRequestsEntry

Zapis JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Pola
key

integer
value

object (Status)

Stan

Zapis JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Pola
code

integer

Kod stanu, który powinien być wartością wyliczeniową google.rpc.Code.
message

string

Komunikat o błędzie widoczny dla programisty, który powinien być w języku angielskim. Wszelkie komunikaty o błędach dla użytkowników powinny być zlokalizowane i wysyłane w polu google.rpc.Status.details lub zlokalizowane przez klienta.
details[]

object

Lista wiadomości zawierających szczegóły błędu. Na potrzeby interfejsów API dostępny jest wspólny zestaw typów wiadomości.

Obiekt zawierający pola dowolnego typu. Dodatkowe pole "@type" zawiera identyfikator URI określający typ. Przykład: { "id": 1234, "@type": "types.example.com/standard/id" }

Dowolna

Zapis JSON 
{
  "typeUrl": string,
  "value": string
}
Pola
typeUrl

string

Identyfikuje typ zserializowanej wiadomości Protobuf za pomocą odwołania do identyfikatora URI składającego się z prefiksu kończącego się ukośnikiem i pełnej i jednoznacznej nazwy typu.

Przykład: type.googleapis.com/google.protobuf.StringValue

Ten ciąg znaków musi zawierać co najmniej 1 znak /, a treść po ostatnim znaku / musi być w pełni kwalifikowaną nazwą typu w postaci kanonicznej, bez kropki na początku. Nie zapisuj schematu w tych odwołaniach do identyfikatorów URI, aby klienci nie próbowali się z nimi kontaktować.

Prefiks jest dowolny, a implementacje Protobuf powinny po prostu usuwać wszystko do ostatniego znaku / (włącznie z nim), aby zidentyfikować typ. type.googleapis.com/ to typowy domyślny prefiks, którego wymagają niektóre starsze implementacje. Ten prefiks nie wskazuje źródła typu, a identyfikatory URI, które go zawierają, nie powinny odpowiadać na żadne żądania.

Wszystkie ciągi adresów URL typów muszą być prawidłowymi odwołaniami do identyfikatorów URI z dodatkowym ograniczeniem (w przypadku formatu tekstowego), zgodnie z którym treść odwołania może składać się tylko ze znaków alfanumerycznych, znaków ucieczki zakodowanych procentowo i znaków z tego zestawu (bez zewnętrznych ukośników lewych): /-.~_!$&()*+,;=. Mimo że zezwalamy na kodowanie procentowe, implementacje nie powinny ich odkodowywać, aby uniknąć nieporozumień z istniejącymi parserami. Na przykład type.googleapis.com%2FFoo należy odrzucić.

W pierwotnym projekcie Any rozważano możliwość uruchomienia usługi rozpoznawania typów pod tymi adresami URL, ale Protobuf nigdy jej nie wdrożył i uważa, że kontaktowanie się z tymi adresami URL jest problematyczne i może stanowić zagrożenie dla bezpieczeństwa. Nie próbuj kontaktować się z adresami URL typu kontakt.
value

string (bytes format)

Zawiera serializację Protobuf typu opisanego przez type_url.

Ciąg znaków zakodowany w formacie base64.

Poziom ufności

Poziom ufności dla rozwiązania.

Wartości w polu enum
CONFIDENCE_UNSPECIFIED Wartość domyślna. Ta wartość nie jest używana.
MEDIUM Średni poziom pewności oznacza, że rozwiązanie jest prawdopodobnie prawidłowe, ale mogą istnieć inne możliwości.
HIGH Wysoki poziom ufności oznacza, że rozwiązanie jest prawidłowe i reprezentuje konkretny element geoprzestrzenny (np. konkretne miejsce).

Adnotacje dotyczące narzędzi

Adnotacje narzędzi są wysyłane do klientów MCP, aby opisać podstawowe ryzyko związane z danym narzędziem. Większość klientów traktuje te wskazówki jako niezaufane, ale można ich użyć do określenia, kiedy wysłać użytkownikowi prośbę o potwierdzenie.

Oprócz ciągu tytułu zdefiniowane są te wskazówki logiczne:

  • readOnlyHint: jeśli ma wartość „true”, narzędzie nie modyfikuje swojego środowiska. Wartość domyślna: false.
  • destructiveHint: jeśli ma wartość „true”, narzędzie może wykonywać działania destrukcyjne. Jeśli ma wartość false, narzędzie może wykonywać tylko działania dodawania. Wartość domyślna: true.
  • idempotentHint: jeśli ma wartość „true”, wielokrotne wywoływanie narzędzia z tymi samymi argumentami nie będzie miało dodatkowego wpływu na jego środowisko. Wartość domyślna: false.
  • openWorldHint: jeśli ma wartość true, narzędzie może wchodzić w interakcje z „otwartym światem” elementów zewnętrznych. Jeśli ma wartość false, narzędzie może wchodzić w interakcje tylko z elementami wewnętrznymi. Na przykład narzędzie do wyszukiwania w internecie jest narzędziem typu Otwarty świat, ale narzędzie do zapamiętywania już nie.

Wskazówka dotycząca destrukcyjności: ❌ | Wskazówka dotycząca idempotencji: ❌ | Wskazówka dotycząca tylko do odczytu: ✅ | Wskazówka dotycząca otwartego świata: ❌