MCP Grabmaps

🚀 GrabMaps MCP Server

このGrabMaps MCP Serverは、Model Context Protocol (MCP) サーバーであり、AWS Location Serviceを通じてGrabMapsサービスにアクセスできるようにします。

なお、このMCPサーバーは、Grab、GrabMaps、またはAWS Location Serviceと公式に関連するものでは ありません。

⚠️ 重要提示

GrabMapsは東南アジアの8か国のみをサポートしています。

• 🇲🇾 マレーシア (MYS)
• 🇸🇬 シンガポール (SGP)
• 🇹🇭 タイ (THA)
• 🇲🇲 ミャンマー (MMR)
• 🇰🇭 カンボジア (KHM)
• 🇻🇳 ベトナム (VNM)
• 🇵🇭 フィリピン (PHL)
• 🇮🇩 インドネシア (IDN)

これらの国以外の検索リクエストは、正確な結果を返さない場合があります。

✨ 主な機能

このMCPサーバーは、2つの主要なカテゴリを通じてGrabMapsの機能にアクセスできるようにします。

場所関連のアクション (MCP経由で利用可能)

• SearchPlaceIndexForText：名前または住所で場所を検索する前方ジオコーディング
• SearchPlaceIndexForPosition：座標で場所を検索する逆ジオコーディング
• SearchPlaceIndexForSuggestions：入力時に場所の候補を取得
• GetPlace：特定の場所の詳細情報を取得

ルート関連のアクション (MCP経由で利用可能)

• CalculateRoute：経由地点を含む地点間のルートを計算
• CalculateRouteMatrix：複数の出発地と目的地間のルート行列を計算

マップ機能 (AWSコンソールが必要)

注意：マップのレンダリング機能は、MCPサーバーを通じて直接利用できません。マップを表示および使用するには：

1. AWS Location Serviceコンソールにアクセスします。
2. マップセクションを探し、「試す」ボタンをクリックします。
3. プロバイダーとして「Grab」が選択されていることを確認します。

AWSにログインせずにGrabMapsのデータカバレッジを調べ、マップを動作させるには、次のURLを訪問してください。 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は東南アジアの以下の8か国のみをサポートしています。

• マレーシア (MYS)
• シンガポール (SGP)
• タイ (THA)
• ミャンマー (MMR)
• カンボジア (KHM)
• ベトナム (VNM)
• フィリピン (PHL)
• インドネシア (IDN)

AIモデルは、これらの国以外の場所でGrabMapsを使用しないでください。結果は不正確または存在しない場合があります。

国コードの要件

場所API関数を使用する場合、AIモデルはユーザーのクエリを分析して適切な国を決定し、すべてのリクエストに3文字の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サーバーは、Model Context ProtocolをサポートするAIモデルと統合できます。AIモデルとの統合の例：

// AIモデルがこのMCPサーバーを使用する方法の例
const result = await mcpClient.call('grabmaps', 'searchPlaceIndexForText', {
  query: 'KLCC, Kuala Lumpur',
  country: 'my'
});

// AIモデルは結果をレスポンスで使用できます
console.log(`KLCCの座標は: ${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ディレクトリには、MapLibre GLとの公式GrabMaps統合を使用した包括的なデモが含まれています。このデモは、すべてのGrabMapsコンポーネントの完全なテストインターフェースを提供します。

• 場所API：前方/逆ジオコーディングおよび場所の詳細
• マップAPI：マップタイル、スタイル記述子、スプライト、およびグリフ
• ルートAPI：ルート計算およびルート行列

デモには、異なるコンポーネントを簡単にテストできるタブ付きインターフェースがあり、各API呼び出しに詳細なフィードバックを提供します。

主要機能

• MapLibre GLを介して公式GrabMapsマップタイルを使用するインタラクティブなマップ
• 異なるGrabMapsコンポーネントをテストするためのタブ付きインターフェース
• すべてのAPIエンドポイントの包括的なテスト
• 設定可能なAPIキー、リージョン、およびリソース名
• ルート、検索結果、およびマップコンポーネントの視覚表示

デモを実行するには：

# MCPサーバーを起動します
npm start

# 次に、ブラウザでexamples/official-map-demo/index.htmlを開きます

設定および使用方法については、公式マップデモREADMEを参照してください。

テスト

testsディレクトリには、すべてのエンドポイントが正しく動作していることを検証するための包括的なテストスイートが含まれています。詳細なテスト手順、例、およびトラブルシューティングのヒントについては、TESTING.mdファイルを参照してください。

テストを実行するには：

# 1つのターミナルでMCPサーバーを起動します
npm start

# 別のターミナルでテストスイートを実行します
node tests/test-suite.js

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。