MCP Tools Reference: mapstools.googleapis.com

เครื่องมือ: resolve_names

แปลงรายการคำค้นหาตำแหน่งที่เฉพาะเจาะจง (ชื่อสถานที่สำคัญหรือที่อยู่ที่แน่นอน) เป็นรหัสสถานที่ของ Google Maps ที่เป็น Canonical

ข้อกำหนดของอินพุต (สำคัญ):

  1. queries (อาร์เรย์ของออบเจ็กต์ - ต้องระบุ): รายการคำค้นหาตำแหน่งที่จะแก้ไข คุณระบุคำค้นหาได้สูงสุด 20 รายการ

    • ออบเจ็กต์การค้นหาแต่ละรายการต้องมี
      • text (สตริง - ต้องระบุ): คำค้นหาข้อความที่แสดงชื่อสถานที่หรือที่อยู่ที่เฉพาะเจาะจงเพื่อแก้ไข
        • ตัวอย่าง: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'

  2. location_bias (ออบเจ็กต์ - ไม่บังคับ): ใช้เพื่อจัดลำดับความสำคัญของผลลัพธ์ที่อยู่ใกล้พื้นที่ทางภูมิศาสตร์ที่เฉพาะเจาะจง

    • รูปแบบ: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (สตริง - ไม่บังคับ): รหัสภูมิภาค Unicode CLDR (รหัสประเทศแบบ 2 ตัวอักษร เช่น US, CA) ของผู้ใช้เพื่อปรับผลลัพธ์

วิธีการสำหรับการเรียกใช้เครื่องมือ:

  • ความเฉพาะเจาะจง (สำคัญ): คำค้นหาต้องแสดงชื่อสถานที่หรือที่อยู่ที่เฉพาะเจาะจง ระบบไม่รองรับการค้นหาทั่วไป เช่น 'restaurants' หรือชื่อเชน เช่น 'Starbucks'
  • อย่าเรียกใช้เครื่องมือนี้หากเครื่องมือปลายทางที่คุณวางแผนจะเรียกใช้ยอมรับสตริงที่อยู่หรือชื่อสถานที่แบบดิบโดยตรงอยู่แล้ว

บันทึกลงใน Google Maps:

  • การตอบกลับจะมีฟิลด์ save_to_maps_url ซึ่งเป็นลิงก์ Google Maps รายการเดียวที่มีสถานที่ทั้งหมดที่แก้ไขสำเร็จ
  • เมื่อผู้ใช้ต้องการบันทึก แชร์ หรือเปิดสถานที่ที่แก้ไขแล้วเป็นรายการใน Google Maps ให้แสดงลิงก์นี้แก่ผู้ใช้ อย่าสร้างลิงก์นี้ด้วยตนเอง

การจัดการข้อผิดพลาด (วิกฤต):

  • นี่คือเครื่องมือประมวลผลแบบกลุ่ม คำขออาจแสดง "ผลลัพธ์แบบผสม" (เช่น การค้นหาบางอย่างทำงานได้สำเร็จ แต่บางอย่างล้มเหลว)
  • รับประกันว่ารายการเอาต์พุตของ results จะแมปแบบ 1:1 กับดัชนีอินพุต queries คำค้นหาที่ไม่สำเร็จจะส่งผลให้มีข้อความ Result ว่างเปล่า (ไม่ได้ตั้งค่า entity) ที่ดัชนีที่เกี่ยวข้องในรายการ results
  • คุณต้องตรวจสอบฟิลด์แผนที่ failed_requests ในการตอบกลับเพื่อระบุดัชนีการค้นหาที่เฉพาะเจาะจงซึ่งล้มเหลว คีย์ของ failed_requests แสดงดัชนีที่อิงตาม 0 ของการค้นหาที่ล้มเหลวในคำขอ อย่าคิดว่าการเรียกใช้แบบกลุ่มทั้งหมดล้มเหลวเนื่องจากล้มเหลวบางส่วน

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้ curl เพื่อเรียกใช้เครื่องมือ resolve_names MCP

คำขอ 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_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

สคีมาอินพุต

ข้อความคำขอสำหรับ ResolveNames

ResolveNamesRequest

การแสดง JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
ช่อง
queries[]

object (LocationQuery)

ต้องระบุ รายการคำค้นหาตำแหน่งที่จะได้รับการแก้ไข คุณระบุคำค้นหาได้สูงสุด 20 รายการ
locationBias

object (LocationBias)

ไม่บังคับ ภูมิภาคที่ไม่บังคับเพื่อกำหนดแนวโน้มของผลลัพธ์ความละเอียด หากระบุไว้ ผลลัพธ์การแก้ปัญหาจะเอนเอียงไปทางเอนทิตีที่อยู่ใกล้กับภูมิภาคนี้มากกว่า การใส่ location_bias หรือ region_code มักจะให้ผลลัพธ์ที่ดีกว่าเนื่องจากจะจำกัดขอบเขตการค้นหา

หากระบุทั้ง location_bias และ region_code ไว้ location_bias จะมีความสำคัญเหนือกว่า region_code
regionCode

string

ไม่บังคับ รหัสภูมิภาคที่ไม่บังคับเพื่อกำหนดค่าผลลัพธ์การแก้ไข หากระบุไว้ ผลลัพธ์ความละเอียดจะเอนเอียงไปทางเอนทิตีที่อยู่ในหรือใกล้กับภูมิภาคที่ระบุ ควรเป็นรหัสภูมิภาค CLDR เช่น "US" หรือ "CA" การใส่ location_bias หรือ region_code มักจะให้ผลลัพธ์ที่ดีกว่าเนื่องจากจะจำกัดขอบเขตการค้นหา

หากระบุทั้ง location_bias และ region_code ไว้ location_bias จะมีความสำคัญเหนือกว่า region_code

LocationQuery

การแสดง JSON 
{
  "text": string
}
ช่อง
text

string

ต้องระบุ ข้อความค้นหาเพื่อระบุเอนทิตีเชิงพื้นที่ที่เฉพาะเจาะจงใน Google Maps เช่น สถานที่หรือที่อยู่ ยิ่งคำค้นหาเจาะจงมากเท่าใด การแก้ไขก็จะยิ่งแม่นยำมากขึ้นเท่านั้น เช่น "ซานฟรานซิสโก" "Googleplex, Mountain View, CA" "1600 Amphitheatre Parkway, Mountain View, CA" หรือ "หอไอเฟล ปารีส" คำค้นหาต้องเป็นที่อยู่หรือชื่อสถานที่ที่เฉพาะเจาะจง ระบบไม่รองรับสถานที่ทั่วไป เช่น ชื่อเชน (เช่น Starbucks) หรือคำค้นหา เช่น "ร้านอาหาร"

LocationBias

การแสดง JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
ช่อง
ฟิลด์ Union type ประเภทของอคติทางภูมิศาสตร์ type ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
viewport

object (Viewport)

วิวพอร์ตที่กำหนดโดยกรอบล้อมรอบ

วิวพอร์ต

การแสดง JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
ช่อง
low

object (LatLng)

ต้องระบุ จุดต่ำสุดของวิวพอร์ต
high

object (LatLng)

ต้องระบุ จุดสูงสุดของวิวพอร์ต

LatLng

การแสดง JSON 
{
  "latitude": number,
  "longitude": number
}
ช่อง
latitude

number

ละติจูดเป็นองศา ต้องอยู่ในช่วง [-90.0, +90.0]
longitude

number

ลองจิจูดเป็นองศา ต้องอยู่ในช่วง [-180.0, +180.0]

สคีมาเอาต์พุต

ข้อความตอบกลับสำหรับ ResolveNames

ResolveNamesResponse

การแสดง JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
ช่อง
results[]

object (Result)

เอาต์พุตเท่านั้น รายการเอนทิตีที่แก้ไขแล้วจากการค้นหาสถานที่ รับประกันว่าจะแมปกับqueriesดัชนีคำขอแบบ 1:1 สตริงที่ว่างเปล่าที่ดัชนี i แสดงว่าการแก้ปัญหาคำค้นหานั้นไม่สำเร็จ หากการแก้ปัญหาล้มเหลว โปรดตรวจสอบช่อง failed_requests เพื่อดูสถานะข้อผิดพลาด
failedRequests

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

เอาต์พุตเท่านั้น แผนที่ที่แสดงความล้มเหลวบางส่วน คีย์คือดัชนีของคำขอที่ไม่สำเร็จในฟิลด์ queries ค่านี้คือสถานะข้อผิดพลาดที่ให้รายละเอียดว่าเหตุใดการแก้ปัญหาจึงล้มเหลว

ออบเจ็กต์ที่มีรายการคู่ "key": value เช่น { "name": "wrench", "mass": "1.3kg", "count": "3" }
saveToMapsUrl

string

เอาต์พุตเท่านั้น ลิงก์เพื่อบันทึกเอนทิตีทั้งหมดที่แก้ไขสำเร็จใน Google Maps

ผลลัพธ์

การแสดง JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
ช่อง
entity

object (Entity)

เอาต์พุตเท่านั้น เอนทิตีที่แก้ไขแล้วจากการค้นหาสถานที่
confidence

enum (Confidence)

เอาต์พุตเท่านั้น ระดับความเชื่อมั่นสำหรับความละเอียด

เอนทิตี

การแสดง JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
ช่อง
ฟิลด์ Union entity ประเภทเอนทิตีที่แก้ไขแล้ว entity ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
place

string

ชื่อทรัพยากรของสถานที่ที่แก้ไขแล้ว

FailedRequestsEntry

การแสดง JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
ช่อง
key

integer
value

object (Status)

สถานะ

การแสดง JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
ช่อง
code

integer

รหัสสถานะซึ่งควรเป็นค่า enum ของ google.rpc.Code
message

string

ข้อความแสดงข้อผิดพลาดที่ส่งถึงนักพัฒนาแอป ซึ่งควรเป็นภาษาอังกฤษ ข้อความแสดงข้อผิดพลาดที่ผู้ใช้เห็นควรได้รับการแปลและส่งในช่อง google.rpc.Status.details หรือแปลโดยไคลเอ็นต์
details[]

object

รายการข้อความที่มีรายละเอียดข้อผิดพลาด API จะใช้ชุดประเภทข้อความทั่วไป

ออบเจ็กต์ที่มีฟิลด์ประเภทใดก็ได้ ฟิลด์เพิ่มเติม "@type" มี URI ที่ระบุประเภท เช่น { "id": 1234, "@type": "types.example.com/standard/id" }

ตามแต่ละประเทศ

การแสดง JSON 
{
  "typeUrl": string,
  "value": string
}
ช่อง
typeUrl

string

ระบุประเภทของข้อความ Protobuf ที่แปลงเป็นอนุกรมด้วยการอ้างอิง URI ซึ่งประกอบด้วยคำนำหน้าที่ลงท้ายด้วยเครื่องหมายทับและชื่อประเภทที่สมบูรณ์ในตัวเอง

ตัวอย่าง: type.googleapis.com/google.protobuf.StringValue

สตริงนี้ต้องมีอักขระ / อย่างน้อย 1 ตัว และเนื้อหาหลัง / ตัวสุดท้ายต้องเป็นชื่อที่สมบูรณ์ของประเภทในรูปแบบ Canonical โดยไม่มีจุดนำหน้า อย่าเขียนรูปแบบในข้อมูลอ้างอิง URI เหล่านี้เพื่อไม่ให้ไคลเอ็นต์พยายามติดต่อ

คำนำหน้าเป็นแบบกำหนดเอง และการใช้งาน Protobuf คาดว่าจะตัดทุกอย่างออกจนถึงและรวมถึง / สุดท้ายเพื่อระบุประเภท type.googleapis.com/ เป็นคำนำหน้าเริ่มต้นทั่วไปที่การติดตั้งใช้งานเดิมบางอย่างกำหนดให้ใช้ คำนำหน้านี้ไม่ได้ระบุแหล่งที่มาของประเภท และ URI ที่มีคำนำหน้านี้ไม่คาดว่าจะตอบสนองต่อคำขอใดๆ

สตริง URL ของประเภททั้งหมดต้องเป็นการอ้างอิง URI ที่ถูกต้องตามกฎหมาย โดยมีข้อจำกัดเพิ่มเติม (สำหรับรูปแบบข้อความ) ว่าเนื้อหาของการอ้างอิงต้องประกอบด้วยอักขระที่เป็นตัวอักษรและตัวเลขคละกัน การหลีกเลี่ยงที่เข้ารหัสเปอร์เซ็นต์ และอักขระในชุดต่อไปนี้เท่านั้น (ไม่รวมเครื่องหมายแบ็กทิกด้านนอก) /-.~_!$&()*+,;= แม้ว่าเราจะอนุญาตการเข้ารหัสเปอร์เซ็นต์ แต่การใช้งานไม่ควรยกเลิกการหลีกเลี่ยงเพื่อป้องกันความสับสนกับตัวแยกวิเคราะห์ที่มีอยู่ เช่น type.googleapis.com%2FFoo ควรถูกปฏิเสธ

ในการออกแบบดั้งเดิมของ Any เราได้พิจารณาความเป็นไปได้ในการเปิดตัวบริการการแก้ปัญหาประเภทที่ URL ประเภทเหล่านี้ แต่ Protobuf ไม่เคยใช้บริการดังกล่าว และถือว่าการติดต่อ URL เหล่านี้เป็นปัญหาและอาจเป็นปัญหาด้านความปลอดภัย อย่าพยายามติดต่อ URL ประเภท
value

string (bytes format)

มี Protobuf serialization ของประเภทที่อธิบายโดย type_url

สตริงที่เข้ารหัส Base64

ความเชื่อมั่น

ระดับความเชื่อมั่นสำหรับความละเอียด

Enum
CONFIDENCE_UNSPECIFIED ค่าเริ่มต้น ค่านี้ไม่ได้ใช้
MEDIUM ความน่าจะเป็นปานกลางแสดงว่าความละเอียดน่าจะถูกต้อง แต่อาจมีความละเอียดอื่นๆ ที่เป็นไปได้
HIGH ความเชื่อมั่นสูงบ่งบอกว่าความละเอียดถูกต้องและแสดงถึงเอนทิตีเชิงพื้นที่ที่เฉพาะเจาะจง (เช่น สถานที่ที่เฉพาะเจาะจง)

คำอธิบายประกอบเครื่องมือ

คำอธิบายประกอบเครื่องมือจะส่งไปยังไคลเอ็นต์ MCP เพื่ออธิบายความเสี่ยงพื้นฐานของเครื่องมือที่ระบุ ไคลเอ็นต์ส่วนใหญ่จะถือว่าคำแนะนำเหล่านี้ไม่น่าเชื่อถือ แต่สามารถใช้เพื่อตัดสินใจว่าจะส่งข้อความแจ้งการยืนยันให้ผู้ใช้เมื่อใด

นอกจากสตริงชื่อแล้ว คำใบ้บูลีนต่อไปนี้จะได้รับการกำหนดดังนี้

  • readOnlyHint: หากเป็นจริง เครื่องมือจะไม่แก้ไขสภาพแวดล้อม ค่าเริ่มต้น: เท็จ
  • destructiveHint: หากเป็นจริง เครื่องมือจะดำเนินการที่ทำลายล้างได้ หากเป็นเท็จ เครื่องมือจะดำเนินการได้เฉพาะการดำเนินการเพิ่มเติมเท่านั้น ค่าเริ่มต้น: จริง
  • idempotentHint: หากเป็นจริง การเรียกใช้เครื่องมือซ้ำๆ ด้วยอาร์กิวเมนต์เดียวกันจะไม่มีผลเพิ่มเติมต่อสภาพแวดล้อมของเครื่องมือ ค่าเริ่มต้น: เท็จ
  • openWorldHint: หากเป็นจริง เครื่องมือจะโต้ตอบกับ "โอเพนเวิลด์" ของเอนทิตีภายนอกได้ หากเป็นเท็จ เครื่องมือจะโต้ตอบกับเอนทิตีภายในเท่านั้น ตัวอย่างเช่น เครื่องมือค้นหาเว็บจะเป็นแบบโอเพนเวิลด์ แต่เครื่องมือความทรงจำจะไม่ใช่แบบโอเพนเวิลด์

คำแนะนำที่ทำลายล้าง: ❌ | คำแนะนำที่ทำซ้ำได้: ❌ | คำแนะนำแบบอ่านอย่างเดียว: ✅ | คำแนะนำแบบโลกเปิด: ❌