MCP Grabmaps

🚀 GrabMaps MCP 服務器

GrabMaps MCP 服務器用於集成 GrabMaps API，可通過 AWS Location Service 訪問 GrabMaps 服務。

請注意，此 MCP 服務器並非與 Grab、GrabMaps 或 AWS Location Service 官方關聯。

重要提示：GrabMaps 僅支持東南亞的八個國家。

• 🇲🇾 馬來西亞（MYS）
• 🇸🇬 新加坡（SGP）
• 🇹🇭 泰國（THA）
• 🇲🇲 緬甸（MMR）
• 🇰🇭 柬埔寨（KHM）
• 🇻🇳 越南（VNM）
• 🇵🇭 菲律賓（PHL）
• 🇮🇩 印度尼西亞（IDN）

對這些國家以外的搜索請求將無法返回準確結果。

🚀 快速開始

GrabMaps MCP 服務器可通過 AWS Location Service 訪問 GrabMaps 服務。在使用前，請確保你已瞭解 GrabMaps 的支持範圍，僅支持東南亞的八個國家。

✨ 主要特性

此 MCP 服務器通過兩個主要類別提供對 GrabMaps 功能的訪問：

地點操作（可通過 MCP 訪問）

• SearchPlaceIndexForText：正向地理編碼，通過名稱或地址查找地點
• SearchPlaceIndexForPosition：反向地理編碼，通過座標查找地點
• SearchPlaceIndexForSuggestions：在輸入時獲取地點建議
• GetPlace：檢索特定地點的詳細信息

路線操作（可通過 MCP 訪問）

• CalculateRoute：計算包含途經點的兩點之間的路線
• CalculateRouteMatrix：計算多個起點和終點之間的路線矩陣

地圖功能（需要 AWS 控制檯）

注意：地圖渲染功能無法直接通過 MCP 服務器使用。若要查看和使用地圖，請按以下步驟操作：

1. 前往 AWS Location Service 控制檯
2. 找到地圖部分並點擊“試用”按鈕
3. 確保選擇“Grab”作為提供商

若要在不登錄 AWS 的情況下探索 GrabMaps 數據覆蓋範圍並查看地圖，請訪問： https://grabmaps.grab.com/explore-data-coverage

📦 安裝指南

從 NPM 安裝

npm install mcp-grabmaps

從源代碼安裝

git clone https://github.com/hithereiamaliff/mcp-grabmaps.git
cd mcp-grabmaps
npm install

📚 詳細文檔

配置

在根目錄下創建一個 .env 文件，並設置以下變量：

# GrabMaps API 憑證
GRABMAPS_API_KEY=your_grabmaps_api_key_here

# AWS Location Service 的 AWS 憑證
AWS_ACCESS_KEY_ID=your_aws_access_key_id_here
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key_here
AWS_REGION=ap-southeast-5  # 馬來西亞的默認區域（新加坡為 ap-southeast-1）

# 地點索引名稱（GrabMaps 的默認名稱）
PLACE_INDEX_NAME=explore.place.Grab

# 地圖名稱（用於地圖渲染）
MAP_NAME=explore.map.Grab

# 路線計算器名稱
ROUTE_CALCULATOR_NAME=explore.route-calculator.Grab

# 服務器端口
PORT=3000

使用方法

本地運行

# 開發模式
npm run dev

# 生產模式
npm run build
npm start

與 Smithery 一起使用

# 在開發模式下運行
npm run smithery:dev

# 為生產環境構建
npm run smithery:build

# 部署到 Smithery
npm run smithery:deploy

在 Smithery 遊樂場中測試

為了獲得測試地點和路線 API 的最佳體驗，建議使用 Smithery 遊樂場：

1. 在本地啟動 MCP 服務器：npm run dev
2. 打開 Smithery 遊樂場：https://smithery.ai/playground
3. 連接到本地 MCP 服務器：http://localhost:3000
4. 使用 SMITHERY_TESTING.md 中提供的示例測試地點和路線 API 調用

對 AI 模型的重要說明

支持的國家

GrabMaps 僅支持東南亞的以下八個國家：

• 馬來西亞（MYS）
• 新加坡（SGP）
• 泰國（THA）
• 緬甸（MMR）
• 柬埔寨（KHM）
• 越南（VNM）
• 菲律賓（PHL）
• 印度尼西亞（IDN）

AI 模型不應嘗試對這些國家以外的地點使用 GrabMaps，因為結果將不準確或不存在。

國家代碼要求

使用地點 API 功能時，AI 模型必須分析用戶的查詢以確定合適的國家，並在所有請求中包含三位 ISO 國家代碼：

{
  "query": "City Square Mall",
  "country": "SGP"  // 新加坡為 SGP，馬來西亞為 MYS，泰國為 THA 等
}

國家代碼示例：

• 新加坡：SGP
• 馬來西亞：MYS
• 泰國：THA
• 印度尼西亞：IDN
• 菲律賓：PHL
• 越南：VNM

包含國家代碼對於返回準確的搜索結果至關重要。

這種方法允許你在無需設置地圖可視化組件的情況下測試地點和路線功能。

示例 API 調用

正向地理編碼

const response = await fetch('http://localhost:3000/searchPlaceIndexForText', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'KLCC, Kuala Lumpur',
    country: 'my',
    maxResults: 5
  })
});

const data = await response.json();
console.log(data);

計算路線

const response = await fetch('http://localhost:3000/calculateRoute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    origin: {
      longitude: 101.6942371,
      latitude: 3.1516964
    },
    destination: {
      longitude: 101.7113,
      latitude: 3.1421
    },
    travelMode: 'Car'
  })
});

const data = await response.json();
console.log(data);

與 AI 模型集成

此 MCP 服務器可與支持模型上下文協議的 AI 模型集成。以下是與 AI 模型集成的示例：

// AI 模型使用此 MCP 服務器的示例
const result = await mcpClient.call('grabmaps', 'searchPlaceIndexForText', {
  query: 'KLCC, Kuala Lumpur',
  country: 'my'
});

// AI 模型可以在其響應中使用結果
console.log(`The coordinates of KLCC are: ${result.results[0].coordinates.latitude}, ${result.results[0].coordinates.longitude}`);

AWS Location Service 設置

在使用此 MCP 服務器之前，你需要在 AWS Location Service 中設置以下資源：

1. 創建一個以 GrabMaps 為數據提供商的地點索引
2. 創建一個以 GrabMaps 為數據提供商的地圖
3. 創建一個以 GrabMaps 為數據提供商的路線計算器

地圖組件限制和推薦方法

通過 MCP 服務器使用地圖 API 組件存在一定限制：

• getMapTile 端點返回的地圖圖塊是編碼為 base64 字符串的二進制數據
• getMapGlyphs 的字體堆棧必須與通過 AWS Location Service 支持的 GrabMaps 字體堆棧匹配
• getMapSprites 的精靈文件名必須遵循特定的正則表達式模式
• 最大縮放級別受到限制（通常最大縮放級別為 14）

推薦方法：

• 對於地圖：使用通過 MapLibre GL 和 AWS Location Service 與 GrabMaps 的直接集成，如官方演示所示
• 對於地點和路線：通過 Smithery 遊樂場或直接 API 調用使用 MCP 服務器

這種分離方式可以在利用 MCP 服務器的地點和路線功能的同時，實現最佳性能和可視化效果。

官方 GrabMaps MapLibre GL 演示

examples/official-map-demo 目錄中包含了一個使用官方 GrabMaps 與 MapLibre GL 集成的綜合演示。此演示為所有 GrabMaps 組件提供了完整的測試界面：

• 地點 API：正向/反向地理編碼和地點詳細信息
• 地圖 API：地圖圖塊、樣式描述符、精靈和字形
• 路線 API：路線計算和路線矩陣

該演示具有一個標籤式界面，便於測試不同組件，併為每個 API 調用提供詳細反饋。

主要特性

• 使用官方 GrabMaps 地圖圖塊通過 MapLibre GL 實現交互式地圖
• 用於測試不同 GrabMaps 組件的標籤式界面
• 對所有 API 端點進行全面測試
• 可配置的 API 密鑰、區域和資源名稱
• 路線、搜索結果和地圖組件的可視化顯示

若要運行演示，請執行以下操作：

# 啟動 MCP 服務器
npm start

# 然後在瀏覽器中打開 examples/official-map-demo/index.html

有關設置和使用說明，請參閱 官方地圖演示 README。

測試

tests 目錄中包含了一個全面的測試套件，用於驗證所有端點是否正常工作。有關詳細的測試說明、示例和故障排除提示，請參閱 TESTING.md 文件。

若要運行測試，請執行以下操作：

# 在一個終端中啟動 MCP 服務器
npm start

# 在另一個終端中運行測試套件
node tests/test-suite.js

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。