MCP Tools Reference: mapstools.googleapis.com

Narzędzie: resolve_maps_urls

Rozpoznaje listę adresów URL Map Google i przekształca je w kanoniczne identyfikatory miejsc w Mapach Google.

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

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

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

  • urls (tablica ciągów znaków – WYMAGANE): lista adresów URL Map Google do rozpoznania. Każdy adres URL musi być prawidłowym adresem URL Map Google wskazującym jedno miejsce.

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 (np. zbierając miejsca udostępnione w rozmowie), 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 adresy URL zostaną rozwiązane, a inne nie).
  • Lista wyjściowa entities jest gwarantowana do mapowania 1:1 z indeksami wejściowymi urls. Niepowodzenie rozpoznania adresu URL spowoduje wyświetlenie pustego komunikatu Entity (nie ustawiono żadnych pól) w odpowiednim indeksie na liście entities.
  • MUSISZ sprawdzić pole mapy failed_requests 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 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_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

Komunikat żądania dla ResolveMapsUrls.

ResolveMapsUrlsRequest

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

string

Wymagane. Adresy URL Map Google do rozpoznania. 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 rozpoznanych elementów z adresów URL Map Google. Gwarantowane mapowanie 1:1 z indeksami urls żądania. Pusta wiadomość w indeksie i (gdzie nie ustawiono entity) oznacza, że nie udało się rozwiązać problemu z tym adresem URL. 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 błędach adresów URL Map Google. Kluczem jest indeks nieudanego żądania w polu urls. 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.

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.

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: ❌