MCP Tools Reference: mapstools.googleapis.com

Tool: resolve_names

Löst eine Batchliste mit bestimmten Standortabfragen (Namen von Sehenswürdigkeiten oder genaue Adressen) in kanonische Google Maps-Orts-IDs auf.

Eingabeanforderungen (WICHTIG):

  1. queries (Array von Objekten – ERFORDERLICH): Eine Liste von Standortabfragen, die aufgelöst werden sollen. Sie können bis zu 20 Abfragen angeben.

    • Jedes Abfrageobjekt muss Folgendes enthalten:
      • text (String – ERFORDERLICH): Die Textanfrage, die einen bestimmten Ortsnamen oder eine bestimmte Adresse darstellt, die aufgelöst werden soll.
        • Beispiele: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'

  2. location_bias (Objekt – OPTIONAL): Damit können Sie Ergebnisse in der Nähe eines bestimmten geografischen Bereichs priorisieren.

    • Format: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (String – OPTIONAL): Der Unicode-CLDR-Regionscode (zweistelliger Ländercode, z.B. US, CA) des Nutzers, um die Ergebnisse zu beeinflussen.

Anleitung für den Toolaufruf:

  • Spezifität (WICHTIG): Suchanfragen müssen einen bestimmten Ortsnamen oder eine bestimmte Adresse enthalten. Allgemeine Suchanfragen wie 'restaurants' oder Kettennamen wie 'Starbucks' werden nicht unterstützt.
  • Rufen Sie dieses Tool NICHT auf, wenn die nachgelagerten Tools, die Sie aufrufen möchten, bereits Rohadressen oder Ortsnamenstrings direkt akzeptieren.

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, präsentieren Sie 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 Abfragen erfolgreich aufgelöst, während andere fehlschlagen).
  • Die Ausgabeliste von results wird garantiert 1:1 den Eingabe-queries-Indizes zugeordnet. Eine fehlgeschlagene Abfrage führt zu einer leeren Result-Nachricht (es wird kein entity festgelegt) am entsprechenden Index in der results-Liste.
  • Sie MÜSSEN das Zuordnungsfeld failed_requests in der Antwort prüfen, um festzustellen, welcher Abfrageindex fehlgeschlagen ist. Der Schlüssel von failed_requests stellt den 0-basierten Index der fehlgeschlagenen Abfrage 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_names 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_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Eingabeschema

Anfragenachricht für ResolveNames.

ResolveNamesRequest

JSON-Darstellung 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Felder
queries[]

object (LocationQuery)

Erforderlich. Eine Liste der aufzulösenden Standortabfragen. Sie können bis zu 20 Abfragen angeben.
locationBias

object (LocationBias)

Optional. Eine optionale Region, um die Auflösungsergebnisse zu beeinflussen. Wenn angegeben, werden die Auflösungsergebnisse auf die Entitäten ausgerichtet, die sich näher an dieser Region befinden. Wenn Sie location_bias oder region_code angeben, erhalten Sie oft bessere Ergebnisse, da der Suchbereich eingeschränkt wird.

Wenn sowohl location_bias als auch region_code angegeben sind, hat location_bias Vorrang vor region_code.
regionCode

string

Optional. Ein optionaler Regionscode, um die Auflösungsergebnisse zu beeinflussen. Falls angegeben, werden die Auflösungsergebnisse auf die Entitäten ausgerichtet, die sich in oder in der Nähe der angegebenen Region befinden. Dies sollte ein CLDR-Regionscode sein. Beispiel: „DE“ oder „AT“. Wenn Sie location_bias oder region_code angeben, erhalten Sie oft bessere Ergebnisse, da der Suchbereich eingeschränkt wird.

Wenn sowohl location_bias als auch region_code angegeben sind, hat location_bias Vorrang vor region_code.

LocationQuery

JSON-Darstellung 
{
  "text": string
}
Felder
text

string

Erforderlich. Die Textanfrage, die in ein bestimmtes Georaumobjekt in Google Maps aufgelöst werden soll, z. B. einen Ort oder eine Adresse. Je genauer die Anfrage, desto genauer die Lösung. Beispiele: „San Francisco“, „Googleplex, Mountain View, CA“, „1600 Amphitheatre Parkway, Mountain View, CA“ oder „Eiffelturm, Paris“. Suchanfragen müssen eine bestimmte Adresse oder ein bestimmter Ortsname sein. Ungefähre Orte wie der Name einer Kette (z.B. Starbucks) oder eine Suchanfrage wie „Restaurants“ werden nicht unterstützt.

LocationBias

JSON-Darstellung 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Felder
Union-Feld type. Der Typ der Standortgewichtung. Für type ist nur einer der folgenden Werte zulässig:
viewport

object (Viewport)

Ein Darstellungsbereich, der durch einen Begrenzungsrahmen definiert ist.

Darstellungsbereich

JSON-Darstellung 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Felder
low

object (LatLng)

Erforderlich. Der Tiefpunkt des Darstellungsbereichs.
high

object (LatLng)

Erforderlich. Der höchste Punkt des Darstellungsbereichs.

LatLng

JSON-Darstellung 
{
  "latitude": number,
  "longitude": number
}
Felder
latitude

number

Der Breitengrad in Grad. Er muss im Bereich [-90,0, +90,0] liegen.
longitude

number

Der Längengrad in Grad. Er muss im Bereich [-180,0, +180,0] liegen.

Ausgabeschema

Antwortnachricht für ResolveNames.

ResolveNamesResponse

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

object (Result)

Nur Ausgabe. Die Liste der aufgelösten Entitäten aus den Standortabfragen. Wird garantiert 1:1 den queries-Indizes der Anfrage zugeordnet. Ein leerer String bei Index i gibt an, dass die Auflösung für diese Abfrage 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 Karte, die teilweise fehlgeschlagene Vorgänge zeigt. Der Schlüssel ist der Index der fehlgeschlagenen Anfrage im Feld queries. 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.

Ergebnis

JSON-Darstellung 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Felder
entity

object (Entity)

Nur Ausgabe. Die aufgelöste Entität aus der Standortabfrage.
confidence

enum (Confidence)

Nur Ausgabe. Das Konfidenzniveau für die Auflösung.

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 Ortes.

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.

Zuverlässigkeit

Das Konfidenzniveau für die Auflösung.

Enums
CONFIDENCE_UNSPECIFIED Standardwert. Dieser Wert wird nicht verwendet.
MEDIUM Eine mittlere Konfidenz bedeutet, dass die Auflösung wahrscheinlich korrekt ist, es aber auch andere Kandidaten geben kann.
HIGH Eine hohe Konfidenz bedeutet, dass die Auflösung korrekt ist und ein bestimmtes geografisches Objekt (z.B. einen bestimmten Ort) darstellt.

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