MCP Tools Reference: mapstools.googleapis.com

Tool: resolve_maps_urls

Wandelt eine Liste von Google Maps-URLs in kanonische Google Maps-Orts-IDs um.

Wann dieses Tool aufgerufen werden muss (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 in einer einzelnen Batchanfrage bis zu 20 URLs angeben, die aufgelöst werden sollen.

Eingabeanforderungen (WICHTIG):

  • urls (Array von Strings – ERFORDERLICH): Die Liste der Google Maps-URLs, die aufgelöst werden sollen. 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 mit allen erfolgreich aufgelösten Orten.
  • Wenn der Nutzer die aufgelösten Orte als Liste in Google Maps speichern, freigeben oder öffnen möchte (z.B. um in einer Unterhaltung freigegebene Orte zu sammeln), präsentieren Sie ihm diesen Link. Erstellen Sie diesen Link NICHT selbst.

Fehlerbehandlung (KRITISCH):

  • Es handelt sich um ein Tool für die Batchverarbeitung. Bei einer Anfrage können „gemischte Ergebnisse“ zurückgegeben werden, z.B. wenn einige URLs erfolgreich aufgelöst werden, während andere fehlschlagen.
  • Die Ausgabeliste von entities wird garantiert 1:1 den Eingabeindexen von urls zugeordnet. Wenn eine URL nicht aufgelöst werden kann, wird an der entsprechenden Stelle in der Liste entities eine leere Entity-Nachricht zurückgegeben (keine Felder festgelegt).
  • Sie MÜSSEN das Feld failed_requests in der Antwort prüfen, um herauszufinden, bei welchem spezifischen URL-Index ein Fehler aufgetreten ist. Der Schlüssel von failed_requests steht für den 0-basierten Index der fehlgeschlagenen URL in der Anfrage. Gehen Sie nicht davon aus, dass der gesamte Batchaufruf aufgrund eines teilweisen Fehlers 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 Einheiten aus den Google Maps-URLs. Die Zuordnung zu den urls-Indexen der Anfrage ist garantiert 1:1. Eine leere Nachricht am 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, sehen Sie im Feld failed_requests nach dem Fehlerstatus.
failedRequests

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

Nur Ausgabe. Eine Karte, die teilweise Fehler für die Google Maps-URLs enthält. 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, über den Sie alle erfolgreich aufgelösten Entitäten in Google Maps speichern können.

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 einem URI-Verweis an, der aus einem Präfix, das mit einem Schrägstrich endet, und dem voll qualifizierten Typnamen besteht.

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

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

Das Präfix ist beliebig. Protobuf-Implementierungen entfernen einfach alles bis zum letzten / (einschließlich), um den Typ zu ermitteln. type.googleapis.com/ ist ein häufiges 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, prozentual codierten Escape-Sequenzen und Zeichen aus der folgenden Menge bestehen darf (ohne die äußeren Backticks): /-.~_!$&()*+,;=. Obwohl wir Prozentcodierungen zulassen, sollten Implementierungen sie nicht decodieren, um Verwechslungen mit vorhandenen Parsern zu vermeiden. Beispiel: type.googleapis.com%2FFoo sollte abgelehnt werden.

Im ursprünglichen Design von Any wurde die Möglichkeit in Betracht gezogen, einen Dienst zur Typauflösung unter diesen Typ-URLs zu starten. Protobuf hat jedoch nie einen solchen Dienst implementiert und betrachtet das Kontaktieren dieser URLs als problematisch und als potenzielles Sicherheitsproblem. Versuchen Sie nicht, URLs zu kontaktieren.
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 ein Bestätigungs-Prompt an einen Nutzer gesendet werden soll.

Zusammen mit dem Titelstring werden die folgenden booleschen Hinweise so 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 Einheiten interagieren. Wenn „false“, kann das Tool nur mit internen Einheiten interagieren. Ein Tool für die Websuche wäre beispielsweise Open World, ein Tool für das Gedächtnis nicht.

Destruktiver Hinweis: ❌ | Idempotenter Hinweis: ❌ | Hinweis „Nur lesen“: ✅ | Hinweis „Offene Welt“: ❌