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 文件。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。