MCP Tools Reference: mapstools.googleapis.com

도구: resolve_names

특정 위치 쿼리 (랜드마크 이름 또는 정확한 주소)의 일괄 목록을 표준 Google 지도 장소 ID로 변환합니다.

입력 요구사항 (중요):

  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 (문자열 - 선택사항): 결과를 편향시키기 위한 사용자의 유니코드 CLDR 지역 코드 (두 글자 국가 코드, 예: US, CA)입니다.

도구 호출 안내:

  • 구체성 (심각): 질문은 특정 장소 이름이나 주소를 나타내야 합니다. 'restaurants'와 같은 일반 검색이나 'Starbucks'와 같은 체인 이름은 지원되지 않습니다.
  • 호출하려는 다운스트림 도구가 이미 원시 주소 또는 장소 이름 문자열을 직접 허용하는 경우 이 도구를 호출하지 마세요.

Google 지도에 저장:

  • 응답에는 성공적으로 확인된 모든 장소가 포함된 단일 Google 지도 링크인 save_to_maps_url 필드가 포함됩니다.
  • 사용자가 확인된 장소를 Google 지도에서 목록으로 저장, 공유 또는 열려고 하면 이 링크를 사용자에게 표시합니다. 이 링크를 직접 구성하지 마세요.

오류 처리 (심각):

  • 이는 일괄 처리 도구입니다. 요청에서 '혼합된 결과' (예: 일부 쿼리는 성공적으로 해결되지만 다른 쿼리는 실패함)가 반환될 수 있습니다.
  • results의 출력 목록은 입력 queries 색인과 1:1로 매핑됩니다. 실패한 쿼리는 results 목록의 해당 색인에 빈 Result 메시지 (entity이 설정되지 않음)를 생성합니다.
  • 응답에서 failed_requests 맵 필드를 확인하여 실패한 특정 쿼리 색인을 식별해야 합니다(MUST). 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 지도에서 장소나 주소와 같은 특정 지리 공간 항목으로 확인되는 텍스트 쿼리입니다. 질문이 구체적일수록 더 정확한 해결 방법을 얻을 수 있습니다. 예를 들어 '샌프란시스코', 'Googleplex, Mountain View, CA', '1600 Amphitheatre Parkway, Mountain View, CA', '에펠탑, 파리'와 같이 입력합니다. 질문은 구체적인 주소 또는 장소 이름이어야 합니다. 체인 이름 (예: 스타벅스) 또는 '레스토랑'과 같은 검색어와 같은 일반적인 위치는 지원되지 않습니다.

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.
}
필드
통합 필드 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 지도에서 해결된 모든 항목을 저장하는 링크

결과

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.
}
필드
통합 필드 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

상태 코드로, 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

슬래시로 끝나는 접두사와 정규화된 유형 이름으로 구성된 URI 참조를 사용하여 직렬화된 Protobuf 메시지의 유형을 식별합니다.

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

이 문자열에는 / 문자가 하나 이상 포함되어야 하며 마지막 / 뒤의 콘텐츠는 선행 점이 없는 표준 형식의 유형의 정규화된 이름이어야 합니다. 클라이언트가 이러한 URI 참조에 연결을 시도하지 않도록 스킴을 작성하지 마세요.

접두사는 임의적이며 Protobuf 구현은 유형을 식별하기 위해 마지막 /까지 포함한 모든 항목을 삭제해야 합니다. type.googleapis.com/는 일부 기존 구현에 필요한 일반적인 기본 접두사입니다. 이 접두사는 유형의 출처를 나타내지 않으며 이를 포함하는 URI는 요청에 응답하지 않을 것으로 예상됩니다.

모든 유형 URL 문자열은 참조의 콘텐츠가 영숫자 문자, 퍼센트 인코딩된 이스케이프, 다음 집합의 문자(외부 백틱 제외)로만 구성되어야 한다는 추가 제한사항이 있는 합법적인 URI 참조여야 합니다. /-.~_!$&()*+,;= 백분율 인코딩이 허용되지만 기존 파서와의 혼동을 방지하기 위해 구현에서 이를 이스케이프 해제해서는 안 됩니다. 예를 들어 type.googleapis.com%2FFoo는 거부되어야 합니다.

Any의 원래 설계에서는 이러한 유형 URL에서 유형 확인 서비스를 실행할 가능성이 고려되었지만 Protobuf는 이를 구현하지 않았으며 이러한 URL에 연결하는 것을 문제이자 잠재적인 보안 문제로 간주합니다. 연락처 유형 URL을 시도하지 마세요.
value

string (bytes format)

type_url로 설명된 유형의 Protobuf 직렬화를 보유합니다.

base64 인코딩 문자열입니다.

신뢰도

해결 방법의 신뢰도 수준입니다.

열거형
CONFIDENCE_UNSPECIFIED 기본값 이 값은 사용되지 않습니다.
MEDIUM 신뢰도가 중간이면 해결 방법이 올바를 가능성이 높지만 다른 후보가 있을 수 있음을 나타냅니다.
HIGH 신뢰도가 높으면 해상도가 올바르고 특정 지리 공간 항목 (예: 특정 장소)을 나타냅니다.

도구 주석

도구 주석은 MCP 클라이언트에 전송되어 특정 도구의 기본 위험을 설명합니다. 대부분의 클라이언트는 이러한 힌트를 신뢰할 수 없는 것으로 취급하지만, 확인 메시지를 사용자에게 전송할 시점을 결정하는 데 사용할 수 있습니다.

제목 문자열과 함께 다음 불리언 힌트는 다음과 같이 정의됩니다.

  • readOnlyHint: true인 경우 도구가 환경을 수정하지 않습니다. 기본값: false.
  • destructiveHint: true인 경우 도구가 파괴적인 작업을 실행할 수 있습니다. false인 경우 도구는 추가 작업만 실행할 수 있습니다. 기본값은 true입니다.
  • idempotentHint: true인 경우 동일한 인수로 도구를 반복적으로 호출해도 환경에 추가적인 영향을 미치지 않습니다. 기본값: false.
  • openWorldHint: true인 경우 도구가 외부 엔티티의 '오픈 월드'와 상호작용할 수 있습니다. false인 경우 도구는 내부 항목과만 상호작용할 수 있습니다. 예를 들어 웹 검색 도구는 오픈 월드이지만 메모리 도구는 오픈 월드가 아닙니다.

파괴적 힌트: ❌ | 동일한 힌트: ❌ | 읽기 전용 힌트: ✅ | 오픈 월드 힌트: ❌