MCP Tools Reference: mapstools.googleapis.com

Narzędzie: resolve_names

Rozwiązuje listę zapytań o konkretne lokalizacje (nazwy charakterystycznych obiektów lub dokładne adresy) na kanoniczne identyfikatory miejsc w Mapach Google.

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

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

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

  2. location_bias (obiekt – OPCJONALNIE): 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 CLDR w Unicode (dwuliterowy kod kraju, np. US, CA) użytkownika, który ma wpłynąć na wyniki.

Instrukcje dotyczące wywołania narzędzia:

  • Szczegółowość (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 podrzędne, których zamierzasz użyć, akceptują już bezpośrednio ciągi znaków z adresem lub nazwą miejsca.

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

  • 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 w relacji 1:1 z indeksami wejściowymi queries. Nieudane zapytanie spowoduje, że w odpowiednim indeksie na liście results pojawi się pusty komunikat Result (bez ustawionego parametru entity).
  • MUSISZ sprawdzić pole mapy failed_requests w odpowiedzi, aby określić, który konkretny indeks zapytania nie działa. Klucz failed_requests reprezentuje indeks nieudanego zapytania w żądaniu (liczony od zera). Nie zakładaj, że całe wywołanie wsadowe nie powiodło się z powodu częściowej awarii.

Poniższy przykład pokazuje, jak za pomocą curl wywołać narzędzie resolve_names MCP.

Żą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 tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schemat danych wejściowych

Wiadomość z prośbą o wywołanie funkcji ResolveNames.

ResolveNamesRequest

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

object (LocationQuery)

Wymagane. Lista zapytań o lokalizację, które mają zostać rozwiązane. Możesz określić maksymalnie 20 zapytań.
locationBias

object (LocationBias)

Opcjonalnie. Opcjonalny region, który ma wpływać na wyniki rozdzielczości. Jeśli zostanie określony, wyniki rozpoznawania będą bardziej ukierunkowane na jednostki znajdujące się bliżej tego regionu. Użycie symbolu location_bias lub region_code często daje lepsze wyniki, ponieważ zawęża przestrzeń wyszukiwania.

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

string

Opcjonalnie. Opcjonalny kod regionu, który ma wpływać na wyniki rozpoznawania. Jeśli zostanie określony region, wyniki rozpoznawania będą bardziej ukierunkowane na jednostki znajdujące się w tym regionie lub w jego pobliżu. Powinien to być kod regionu CLDR. np. „PL” lub „US”. Użycie symbolu location_bias lub region_code często daje lepsze wyniki, ponieważ zawęża przestrzeń wyszukiwania.

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

LocationQuery

Zapis JSON 
{
  "text": string
}
Pola
text

string

Wymagane. Zapytanie tekstowe, które ma zostać przekształcone w konkretny obiekt geoprzestrzenny w Mapach Google, np. miejsce lub adres. Im bardziej szczegółowe zapytanie, tym dokładniejsze rozwiązanie. Na przykład „San Francisco”, „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 wyszukiwania, 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 odchylenia 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. Najniższy punkt widocznego obszaru.
high

object (LatLng)

Wymagane. Najwyższy punkt obszaru widocznego.

LatLng

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

number

Szerokość geograficzna w stopniach. Musi mieścić się w zakresie od –90,0 do +90,0.
longitude

number

Długość geograficzna w stopniach. Musi mieścić się w zakresie od –180,0 do +180,0.

Schemat wyjściowy

Wiadomość z odpowiedzią dla ResolveNames.

ResolveNamesResponse

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

object (Result)

Tylko dane wyjściowe. Lista rozpoznanych podmiotów z zapytań o lokalizację. Gwarantowane mapowanie 1:1 z indeksami żądania queries. Pusty ciąg w indeksie i oznacza, że w przypadku tego zapytania nie udało się uzyskać rozwiązania. Jeśli rozpoznanie się nie powiodło, sprawdź pole failed_requests pod kątem stanu błędu.
failedRequests

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

Tylko dane wyjściowe. Mapa pokazująca częściowe niepowodzenia. Kluczem jest indeks nieudanego żądania w polu queries. Wartość to stan błędu zawierający szczegółowe informacje o tym, dlaczego rozpoznanie się nie powiodło.

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

Wynik

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

object (Entity)

Tylko dane wyjściowe. Rozwiązana encja z zapytania o lokalizację.
confidence

enum (Confidence)

Tylko dane wyjściowe. Poziom ufności 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. Rozwiązany 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

Określa typ serializowanego komunikatu Protobuf za pomocą odwołania URI składającego się z prefiksu kończącego się ukośnikiem i pełnej 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 formie kanonicznej bez kropki na początku. Nie wpisuj schematu w tych odwołaniach do URI, aby klienci nie próbowali się z nimi skontaktować.

Prefiks jest dowolny, a implementacje Protobuf powinny po prostu usuwać wszystko aż do ostatniego znaku / włącznie, aby zidentyfikować typ. type.googleapis.com/ to typowy domyślny prefiks, który jest wymagany w przypadku niektórych starszych implementacji. Ten prefiks nie wskazuje pochodzenia typu, a identyfikatory URI, które go zawierają, nie powinny odpowiadać na żadne żądania.

Wszystkie ciągi URL typu muszą być zgodnymi odwołaniami do URI z dodatkowym ograniczeniem (w przypadku formatu tekstowego), że treść odwołania musi składać się wyłącznie ze znaków alfanumerycznych, znaków ucieczki zakodowanych w procentach i znaków z tego zbioru (bez zewnętrznych apostrofów): /-.~_!$&()*+,;=. Mimo że zezwalamy na kodowanie procentowe, implementacje nie powinny dekodować znaków ucieczki, aby uniknąć nieporozumień z istniejącymi analizatorami. Na przykład ciąg type.googleapis.com%2FFoo powinien zostać odrzucony.

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 kontaktowanie się z tymi adresami URL za problematyczne i potencjalnie niebezpieczne. Nie próbuj kontaktować się z adresami URL typu.
value

string (bytes format)

Zawiera serializację Protobuf typu opisanego przez type_url.

Ciąg tekstowy zakodowany w formacie Base64.

Poziom ufności

Poziom ufności rozwiązania.

Wartości w polu enum
CONFIDENCE_UNSPECIFIED Wartość domyślna. Ta wartość nie jest używana.
MEDIUM Średni poziom ufności oznacza, że rozwiązanie jest prawdopodobnie prawidłowe, ale mogą istnieć inne kandydatury.
HIGH Wysoki poziom ufności oznacza, że rozdzielczość jest prawidłowa i odnosi się do konkretnego obiektu geoprzestrzennego (np. konkretnego miejsca).

Adnotacje do narzędzi

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌