MCP Tools Reference: mapstools.googleapis.com

Tool: resolve_maps_urls

Löst eine Liste von Google Maps-URLs in kanonische Google Maps-Orts-IDs auf.

Wann dieses Tool aufgerufen werden sollte (WICHTIG):

  • Verwenden Sie dieses Tool, wenn der Nutzer einen oder mehrere Google Maps-Freigabelinks oder ‑URLs angibt (z.B. „https://maps.app.goo.gl/...“, „https://www.google.com/maps/place/...“ oder „https://maps.google.com/...“) und Sie müssen die zugrunde liegenden kanonischen Orts-IDs extrahieren.
  • Sie können bis zu 20 URLs angeben, die in einer einzelnen Batchanfrage aufgelöst werden sollen.

Eingabeanforderungen (WICHTIG):

  • urls (Array von Strings – ERFORDERLICH): Die Liste der aufzulösenden Google Maps-URLs. Jede URL muss eine gültige Google Maps-URL für einen einzelnen Ort sein.

In Google Maps speichern:

  • Die Antwort enthält das Feld save_to_maps_url, eine einzelne Google Maps-URL, die alle erfolgreich aufgelösten Orte enthält.
  • Wenn der Nutzer die aufgelösten Orte als Liste in Google Maps speichern, teilen oder öffnen möchte (z.B. um in einer Unterhaltung geteilte Orte zu sammeln), präsentiere ihm diesen Link. Erstellen Sie diesen Link NICHT selbst.

Fehlerbehandlung (KRITISCH):

  • Dies ist ein Tool für die Batchverarbeitung. Eine Anfrage kann „gemischte Ergebnisse“ zurückgeben (z.B. werden einige URLs erfolgreich aufgelöst, andere nicht).
  • Die Ausgabeliste von entities wird garantiert 1:1 den Eingabe-urls-Indizes zugeordnet. Eine fehlgeschlagene URL-Auflösung führt zu einer leeren Entity-Nachricht (keine Felder festgelegt) am entsprechenden Index in der entities-Liste.
  • Sie MÜSSEN das Kartenfeld failed_requests in der Antwort prüfen, um festzustellen, bei welchem URL-Index der Fehler aufgetreten ist. Der Schlüssel von failed_requests stellt den 0-basierten Index der fehlgeschlagenen URL in der Anfrage dar. Gehen Sie nicht davon aus, dass der gesamte Batchaufruf aufgrund eines Teilfehlers fehlgeschlagen ist.

Das folgende Codebeispiel zeigt, wie Sie mit curl das MCP-Tool resolve_maps_urls aufrufen.

Curl-Anfrage 
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
}'

Eingabeschema

Anfragenachricht für ResolveMapsUrls.

ResolveMapsUrlsRequest

JSON-Darstellung 
{
  "urls": [
    string
  ]
}
Felder
urls[]

string

Erforderlich. Die aufzulösenden Google Maps-URLs. Jede URL muss eine gültige Google Maps-URL sein, z. B. https://maps.app.goo.gl/..., https://www.google.com/maps/place/... oder https://maps.google.com/.... Derzeit werden nur URLs unterstützt, die auf einen einzelnen Ort verweisen. Sie können bis zu 20 URLs angeben.

Ausgabeschema

Antwortnachricht für ResolveMapsUrls.

ResolveMapsUrlsResponse

JSON-Darstellung 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Felder
entities[]

object (Entity)

Nur Ausgabe. Die Liste der aufgelösten Entitäten aus den Google Maps-URLs. Die Zuordnung zu den urls-Indizes der Anfrage ist garantiert 1:1. Eine leere Nachricht bei Index i (wenn kein entity festgelegt ist) gibt an, dass die Auflösung für diese URL fehlgeschlagen ist. Wenn die Auflösung fehlgeschlagen ist, prüfen Sie das Feld failed_requests auf den Fehlerstatus.
failedRequests

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

Nur Ausgabe. Eine Zuordnung, die teilweise Fehler für die Google Maps-URLs kommuniziert. Der Schlüssel ist der Index der fehlgeschlagenen Anfrage im Feld urls. Der Wert ist der Fehlerstatus, der angibt, warum die Auflösung fehlgeschlagen ist.

Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Nur Ausgabe. Ein Link zum Speichern aller erfolgreich aufgelösten Entitäten in Google Maps.

Entität

JSON-Darstellung 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Felder
Union-Feld entity. Der aufgelöste Entitätstyp. Für entity ist nur einer der folgenden Werte zulässig:
place

string

Der Ressourcenname des aufgelösten Orts.

FailedRequestsEntry

JSON-Darstellung 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Felder
key

integer
value

object (Status)

Status

JSON-Darstellung 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Felder
code

integer

Der Statuscode, der idealerweise ein ENUM-Wert von google.rpc.Code ist.
message

string

Eine an Entwickler gerichtete Fehlermeldung, die englischsprachig sein sollte. Jede für Nutzer sichtbare Fehlermeldung sollte lokalisiert und im Feld google.rpc.Status.details gesendet werden. Sie kann auch clientseitig lokalisiert werden.
details[]

object

Eine Auflistung aller Meldungen, die die Fehlerdetails enthalten. Es gibt einen gemeinsamen Satz von Nachrichtentypen, die APIs verwenden können.

Ein Objekt, das Felder eines beliebigen Typs enthält. Ein zusätzliches Feld "@type" enthält einen URI zur Identifizierung des Typs. Beispiel: { "id": 1234, "@type": "types.example.com/standard/id" }.

Alle

JSON-Darstellung 
{
  "typeUrl": string,
  "value": string
}
Felder
typeUrl

string

Gibt den Typ der serialisierten Protobuf-Nachricht mit einer URI-Referenz an, die aus einem Präfix, das mit einem Schrägstrich endet, und dem vollständig qualifizierten Typnamen besteht.

Beispiel: type.googleapis.com/google.protobuf.StringValue

Dieser String muss mindestens ein /-Zeichen enthalten und der Inhalt nach dem letzten / muss der vollständig qualifizierte Name des Typs in kanonischer Form ohne führenden Punkt sein. Geben Sie für diese URI-Referenzen kein Schema an, damit Clients nicht versuchen, sie zu kontaktieren.

Das Präfix ist beliebig und Protobuf-Implementierungen entfernen einfach alles bis einschließlich des letzten /, um den Typ zu identifizieren. type.googleapis.com/ ist ein gängiges Standardpräfix, das für einige Legacy-Implementierungen erforderlich ist. Dieses Präfix gibt nicht den Ursprung des Typs an und URIs, die es enthalten, reagieren voraussichtlich nicht auf Anfragen.

Alle Typ-URL-Strings müssen gültige URI-Referenzen sein. Für das Textformat gilt die zusätzliche Einschränkung, dass der Inhalt der Referenz nur aus alphanumerischen Zeichen, prozentcodierten Escapes und Zeichen aus dem folgenden Satz (ohne die äußeren Backticks) bestehen darf: /-.~_!$&()*+,;=. Obwohl wir die Prozentcodierung zulassen, sollten Implementierungen sie nicht entfernen, um Verwechslungen mit vorhandenen Parsern zu vermeiden. Beispielsweise sollte type.googleapis.com%2FFoo abgelehnt werden.

Im ursprünglichen Design von Any wurde die Möglichkeit in Betracht gezogen, einen Typauflösungsdienst unter diesen Typ-URLs zu starten. Protobuf hat jedoch nie einen solchen Dienst implementiert und betrachtet die Kontaktaufnahme mit diesen URLs als problematisch und als potenzielles Sicherheitsrisiko. Versuchen Sie nicht, URLs einzugeben.
value

string (bytes format)

Enthält eine Protobuf-Serialisierung des Typs, der durch „type_url“ beschrieben wird.

Ein base64-codierter String.

Tool-Annotationen

Tool-Anmerkungen werden an MCP-Clients gesendet, um das grundlegende Risiko eines bestimmten Tools zu beschreiben. Die meisten Clients behandeln diese Hinweise als nicht vertrauenswürdig, sie können aber verwendet werden, um zu entscheiden, wann eine Bestätigungsaufforderung an einen Nutzer gesendet werden soll.

Zusätzlich zum Titelstring werden die folgenden booleschen Hinweise definiert:

  • readOnlyHint: Wenn „true“, ändert das Tool seine Umgebung nicht. Standardeinstellung: false.
  • destructiveHint: Wenn „true“, kann das Tool destruktive Aktionen ausführen. Wenn „false“, kann das Tool nur additive Aktionen ausführen. Standardeinstellung: true.
  • idempotentHint: Wenn „true“, hat das wiederholte Aufrufen des Tools mit denselben Argumenten keine zusätzlichen Auswirkungen auf die Umgebung. Standardeinstellung: false.
  • openWorldHint: Wenn „true“, kann das Tool mit einer „offenen Welt“ externer Entitäten interagieren. Wenn „false“, kann das Tool nur mit internen Entitäten interagieren. Ein Tool für die Websuche wäre beispielsweise ein Open-World-Tool, ein Tool für gemerkte Informationen dagegen nicht.

Destruktiver Hinweis: ❌ | Idempotenter Hinweis: ❌ | Lesezugriff-Hinweis: ✅ | Hinweis „Open World“: ❌