MCP Tools Reference: mapstools.googleapis.com

Tool: resolve_names

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

Eingabeanforderungen (WICHTIG):

  1. queries (Array von Objekten – ERFORDERLICH): Eine Liste der Standortanfragen, 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 zum Auflösen darstellt.
        • Beispiele: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (object – 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 gewichten.

Anleitung für Toolaufruf:

  • Spezifität (KRITISCH): Anfragen müssen einen bestimmten Ortsnamen oder eine bestimmte Adresse enthalten. Allgemeine Suchanfragen wie 'restaurants' oder Namen von Ketten wie 'Starbucks' werden nicht unterstützt.
  • Rufen Sie dieses Tool NICHT auf, wenn die Downstream-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 mit allen erfolgreich aufgelösten Orten.
  • Wenn der Nutzer die aufgelösten Orte als Liste in Google Maps speichern, freigeben oder öffnen möchte, präsentieren Sie ihm diesen Link. Erstellen Sie diesen Link NICHT selbst.

Fehlerbehandlung (KRITISCH):

  • Es handelt sich um ein Tool für die Batchverarbeitung. Eine Anfrage kann „gemischte Ergebnisse“ zurückgeben, z.B. wenn einige Anfragen erfolgreich aufgelöst werden, andere jedoch fehlschlagen.
  • Die Ausgabeliste von results wird garantiert 1:1 den Eingabeindexen von queries zugeordnet. Bei einer fehlgeschlagenen Abfrage wird am entsprechenden Index in der Liste results eine leere Result-Nachricht (kein entity festgelegt) zurückgegeben.
  • Sie MÜSSEN das Feld failed_requests in der Antwort prüfen, um herauszufinden, welcher bestimmte Abfrageindex fehlgeschlagen ist. Der Schlüssel von failed_requests stellt den 0-basierten Index der fehlgeschlagenen Anfrage in der Anfrage dar. 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_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 Ortsanfragen, die aufgelöst werden sollen. Sie können bis zu 20 Abfragen angeben.
locationBias

object (LocationBias)

Optional. Eine optionale Region, um die Auflösungsergebnisse zu beeinflussen. Falls angegeben, werden die Auflösungsergebnisse auf die Einheiten ausgerichtet, die sich näher an dieser Region befinden. Wenn Sie location_bias oder region_code einfügen, werden oft bessere Ergebnisse erzielt, da der Suchbereich eingegrenzt 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 Einheiten ausgerichtet, die sich in oder in der Nähe der angegebenen Region befinden. Dies sollte ein CLDR-Regionscode sein. Beispiel: „US“ oder „CA“. Wenn Sie location_bias oder region_code einfügen, werden oft bessere Ergebnisse erzielt, da der Suchbereich eingegrenzt 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 Google Maps in eine bestimmte geografische Einheit wie einen Ort oder eine Adresse aufgelöst werden soll. Je spezifischer die Anfrage, desto genauer die Lösung. Beispiele: „San Francisco“, „Googleplex, Mountain View, CA“, „1600 Amphitheatre Parkway, Mountain View, CA“ oder „Eiffelturm, Paris“. Anfragen müssen eine bestimmte Adresse oder einen bestimmten Ortsnamen enthalten. Allgemeine Standorte wie ein Kettenname (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 des Standort-Bias. Für type ist nur einer der folgenden Werte zulässig:
viewport

object (Viewport)

Ein Darstellungsbereich, der durch einen Begrenzungsrahmen definiert wird.

Darstellungsbereich

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

object (LatLng)

Erforderlich. Der unterste Punkt 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. Die Zuordnung zu den queries-Indexen der Anfrage ist garantiert 1:1. Ein leerer String am Index i gibt an, dass die Auflösung für diese Anfrage 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, auf der teilweise fehlgeschlagene Vorgänge dargestellt werden. 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, über den Sie alle erfolgreich aufgelösten Entitäten in Google Maps speichern können.

Ergebnis

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

object (Entity)

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

enum (Confidence)

Nur Ausgabe. Das Konfidenzniveau für die Lö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 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.

Zuverlässigkeit

Das Konfidenzniveau für die Lösung.

Enums
CONFIDENCE_UNSPECIFIED Standardwert. Dieser Wert wird nicht verwendet.
MEDIUM Bei mittlerer Wahrscheinlichkeit ist die Lösung wahrscheinlich richtig, es kann aber auch andere Kandidaten geben.
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 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“: ❌