MCP Tools Reference: mapstools.googleapis.com

Narzędzie: resolve_maps_urls

Rozwiązuje listę adresów URL Map Google na kanoniczne identyfikatory miejsc w Mapach Google.

Kiedy wywołać to narzędzie (KLUCZOWE):

  • Użyj tego narzędzia, gdy użytkownik poda co najmniej 1 link lub adres URL do udostępniania w Mapach Google (np. „https://maps.app.goo.gl/...”, „https://www.google.com/maps/place/…” lub „https://maps.google.com/…”), a musisz wyodrębnić podstawowe kanoniczne identyfikatory miejsc.
  • W jednym żądaniu zbiorczym możesz określić do 20 adresów URL do rozwiązania.

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

  • urls (tablica ciągów znaków – WYMAGANE): lista adresów URL Map Google do rozwiązania. Każdy adres URL musi być prawidłowym adresem URL Map Google dla jednego miejsca.

Zapisz w Mapach Google:

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

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

  • Jest to narzędzie do przetwarzania wsadowego. Żądanie może zwrócić „mieszane wyniki” (np. niektóre adresy URL zostaną rozpoznane, a inne nie).
  • Lista wyjściowa entities jest gwarantowana do mapowania 1:1 z indeksami wejściowymi urls. Nieudane rozwiązanie adresu URL spowoduje wyświetlenie pustego komunikatu Entity (bez ustawionych pól) w odpowiednim indeksie na liście entities.
  • MUSISZ sprawdzić pole failed_requests map w odpowiedzi, aby określić, który indeks adresu URL nie został utworzony. Klucz failed_requests reprezentuje indeks nieudanego adresu URL 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ładowy kod pokazuje, jak używać curl do wywoływania narzędzia MCP resolve_maps_urls.

Żą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_maps_urls",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schemat wejściowy

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

ResolveMapsUrlsRequest

Zapis JSON 
{
  "urls": [
    string
  ]
}
Pola
urls[]

string

Wymagane. Adresy URL Map Google do rozwiązania. Każdy adres URL powinien być prawidłowym adresem URL Map Google, np. https://maps.app.goo.gl/..., https://www.google.com/maps/place/... lub https://maps.google.com/.... Obecnie obsługiwane są tylko adresy URL wskazujące jedno miejsce. Możesz podać maksymalnie 20 adresów URL.

Schemat wyjściowy

Wiadomość z odpowiedzią dla ResolveMapsUrls.

ResolveMapsUrlsResponse

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

object (Entity)

Tylko dane wyjściowe. Lista rozwiązanych podmiotów z adresów URL w Mapach Google. Gwarantowane mapowanie 1:1 z indeksami żądania urls. Pusty komunikat w indeksie i (gdzie nie ustawiono entity) oznacza, że w przypadku tego adresu URL nie udało się uzyskać rozdzielczości. 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 informująca o częściowych błędach w przypadku adresów URL Map Google. Kluczem jest indeks nieudanej prośby w polu urls. Wartość to stan błędu, który zawiera 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" }
saveToMapsUrl

string

Tylko dane wyjściowe. link do zapisania wszystkich prawidłowo rozwiązanych encji w Mapach Google;

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 elementu. 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ć prawidłowe odwołania URI z dodatkowym ograniczeniem (w przypadku formatu tekstowego), że zawartość odwołania musi składać się tylko ze znaków alfanumerycznych, znaków ucieczki zakodowanych w procentach i znaków z tego zestawu (bez zewnętrznych apostrofów): /-.~_!$&()*+,;=. Mimo że zezwalamy na kodowanie procentowe, implementacje nie powinny go dekodować, aby uniknąć nieporozumień z istniejącymi analizatorami. Na przykład type.googleapis.com%2FFoo powinna zostać odrzucona.

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 kontakt.
value

string (bytes format)

Zawiera serializację Protobuf typu opisanego przez type_url.

Ciąg znaków zakodowany w formacie Base64.

Adnotacje do narzędzi

Adnotacje narzędzia są wysyłane do klientów MCP w celu opisania podstawowego ryzyka związanego z danym narzędziem. Większość klientów traktuje te wskazówki jako niezaufane, ale można ich używać do określania, kiedy użytkownikowi może zostać wysłany monit o potwierdzenie.

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

  • readOnlyHint: jeśli wartość jest prawdziwa, narzędzie nie modyfikuje środowiska. Wartość domyślna: fałsz.
  • destructiveHint: jeśli ma wartość Prawda, narzędzie może wykonywać działania destrukcyjne. Jeśli wartość to „false”, narzędzie może wykonywać tylko działania dodające. 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: fałsz.
  • openWorldHint: jeśli wartość to „true”, narzędzie może wchodzić w interakcje z „otwartym światem” podmiotów zewnętrznych. Jeśli wartość jest fałszywa, narzędzie może wchodzić w interakcje tylko z podmiotami wewnętrznymi. Na przykład narzędzie do wyszukiwania w internecie byłoby narzędziem typu otwarty świat, a narzędzie do zapamiętywania nie.

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