MCP Geocoder Rosetta

MCP Geocoder Rosetta

さまざまな言語とアプローチで実装された、Model Context Protocol（MCP）ジオコーダーのコレクションです。このリポジトリは、独自の MCP ツールを作成しようとしている開発者向けの「ロゼッタストーン」として機能します。

MCP とは？

Model Context Protocol（MCP）は、ツールが AI モデルとやり取りするためのプロトコルです。AI が API 呼び出しやデータベースへのアクセスなど、現実世界でアクションを実行できるようにします。MCP は、AI モデルがツールを使用するための標準化された方法と、開発者がツールを作成するための標準化された方法を提供します。

実装

このリポジトリには、Google Maps API を使用したジオコーディングツールの3種類の実装が含まれています。

1. Python + urllib - 追加の依存関係を使わず、Python の標準ライブラリを使用します
2. Python + Google Maps SDK - Google Maps の公式 Python クライアントを使用します
3. TypeScript + Google Maps SDK - TypeScript と Google Maps JavaScript クライアントを使用します

実装の比較

機能	Python + urllib	Python + Google Maps SDK	TypeScript + Google Maps SDK
依存関係	最小限（標準ライブラリ）	googlemaps, mcp	@googlemaps/google-maps-services-js, @mcp/sdk
セットアップの複雑さ	簡単	普通	普通
エラー処理	基本的	強化	強化
コードサイズ	小	中	中
SDK の利点	なし — API を直接呼び出します	型処理、検証	型安全性、Promise API

前提条件

• Google Maps API キー（こちらから取得）
• Python 3.13+（Python の実装用）
• Node.js 16+（TypeScript の実装用）
• MCP CLI ツール

セットアップ

1. リポジトリをクローンします：

git clone https://github.com/yourusername/mcp-geocoder-rosetta.git
cd mcp-geocoder-rosetta

2. Google Maps API キーを設定します：

# Set as environment variable
export GOOGLE_MAPS_API_KEY=your-api-key-here

# Or create .env files in each implementation directory
echo "GOOGLE_MAPS_API_KEY=your-api-key-here" > python-urllib/.env
echo "GOOGLE_MAPS_API_KEY=your-api-key-here" > python-googlemaps/.env
echo "GOOGLE_MAPS_API_KEY=your-api-key-here" > typescript-googlemaps/.env

3. MCP CLI をインストールします：

# Using pip
pip install mcp[cli]

# Or using uv
uv pip install mcp[cli]

4. デバッグスクリプトを実行して、環境を確認します：

chmod +x debug_mcp.sh
./debug_mcp.sh

クイックスタート

urllib を使った Python のテスト：

# Direct test with MCP client
python test_direct.py urllib

# Server CLI test
python test_server.py urllib

# Interactive client
python run_geocoder.py urllib

Google Maps SDK を使った Python のテスト：

# Direct test with MCP client
python test_direct.py googlemaps

# Server CLI test
python test_server.py googlemaps

# Interactive client
python run_geocoder.py googlemaps

TypeScript のテスト：

# Simply run the client which will handle dependencies and server startup
python run_geocoder.py typescript

# The script will:
# - Check for npm and install dependencies if needed
# - Start the TypeScript server automatically
# - Connect and let you query addresses

個別サービスのセットアップ

urllib を使った Python

cd python-urllib

# Method 1: Direct execution with dependencies
export GOOGLE_MAPS_API_KEY="your-api-key-here"
uv run --with mcp[cli] mcp run geocoder.py

# Method 2: Using virtual environment
uv venv -p 3.13 .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
mcp run geocoder.py

Google Maps SDK を使った Python

cd python-googlemaps

# Method 1: Direct execution with dependencies
export GOOGLE_MAPS_API_KEY="your-api-key-here"
uv run --with mcp[cli] --with googlemaps mcp run geocoder.py

# Method 2: Using virtual environment
uv venv -p 3.13 .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install googlemaps
uv pip install -e .
mcp run geocoder.py

Google Maps SDK を使った TypeScript

# Method 1: Using run_geocoder.py (recommended)
# This automatically handles dependencies and server startup
python run_geocoder.py typescript

# Method 2: Manual setup
cd typescript-googlemaps

# Install dependencies
npm install

# Set up environment with your Google Maps API key
echo "GOOGLE_MAPS_API_KEY=your-api-key-here" > .env

# Run the MCP server directly (only if needed)
npm start

利用可能なスクリプト

メインスクリプト

• run_geocoder.py：すべての実装でクライアントとサーバーを実行します
• test_direct.py：サーバーとの MCP 通信を直接テストします
• test_server.py：Python を直接使用してサーバーをテストします
• debug_mcp.sh：問題のトラブルシューティングに使用するデバッグスクリプト

実行オプション

• 通常モード：python run_geocoder.py <implementation>
• サーバーのみのモード：python run_geocoder.py <implementation> --server-only
• クライアントのみのモード：python run_geocoder.py <implementation> --client-only

クライアントとサーバーの接続のデバッグ

クライアントがサーバーに接続できない場合、いくつかの方法でデバッグできます。

方法 1：サーバーとクライアントを別々に実行する

一方のターミナルでサーバーを実行します：

python run_geocoder.py urllib --server-only

次に、別のターミナルでクライアントを実行します：

python run_geocoder.py urllib --client-only

これにより、問題がサーバー、クライアント、または両者間の通信のどこにあるのかを切り分けやすくなります。

方法 2：サーバーを直接テストする

テストスクリプトを使って、クライアント全体を介さずにサーバーを直接テストします：

# Test with a direct MCP connection:
python test_direct.py urllib

# Or test the server with direct Python:
python test_server.py urllib

これらのスクリプトはサーバーを起動し、基本的な接続をテストして、サンプルのジオコードリクエストを実行します。

よくある問題

1. API キーが見つからない：各実装ディレクトリの .env ファイル、または環境変数に Google Maps API キーが設定されていることを確認してください。

2. モジュールが見つからない：「Module not found」エラーが表示される場合は、必要な依存関係をインストールしてください：

   pip install googlemaps mcp[cli]
   

3. 接続の問題：クライアントとサーバーは標準入力／出力を介して通信します。問題が発生した場合は、以下を確認してください：

   • Python のバージョン互換性（Python 3.13 以降を推奨）
   • MCP SDK のバージョン互換性
   • スクリプトの実行権限

4. デバッグガイド：詳しい情報が必要な場合は、付属のデバッグガイドを実行してください：

   ./debug_mcp.sh
   

   デバッグスクリプトでは、以下を行います：

   • Python のインストールを確認する
   • MCP モジュールのインストールを確認する
   • Google Maps API キーの設定を確認する
   • urllib の実装をテストする
   • トラブルシューティング用のコマンドを案内する

Claude Desktop との統合

設定ファイルへのアクセス

1. Claude Desktop アプリケーションを開きます
2. 設定にアクセス：左下隅の歯車アイコンをクリックします
3. Developer タブを開く：サイドバーの「Developer」をクリックします
4. 設定を編集：ページ下部の「Edit Config」ボタンをクリックし、既定のテキストエディターで設定ファイルを開きます

MCP ツールを設定に追加する

claude_desktop_config.json ファイルには、MCP ツールの最上位キーとして mcpServers を含む JSON オブジェクトが記述されています。このセクションにジオコーダーの実装を追加してください：

{
  "mcpServers": {
    "existing-server-1": {
      // existing configuration
    },
    "existing-server-2": {
      // existing configuration
    },
    
    // Add your geocoder implementations here
  }
}

⚠️ 重要：ツールの識別に関する注意 ⚠️

これらのジオコーダー実装は、一度に 1 つだけインストールしてください。類似した機能を持つ複数の MCP サーバーがあると、ツールの識別で問題が発生し、リクエストの処理時に Claude がどのジオコーディングツールを使用すべきか判断できなくなる場合があります。

各実装を設定に追加する方法は以下のとおりです：

Google Maps SDK を使用する TypeScript

"mcpServers": {
  "GeocoderNode": {
    "command": "npx",
    "args": [
      "tsx",
      "/path/to/mcp-geocoder-rosetta/typescript-googlemaps/geocoder.ts"
    ],
    "env": {
      "GOOGLE_MAPS_API_KEY": "your-api-key-here"
    }
  }
}

Google Maps SDK を使用する Python

"mcpServers": {
  "GeocoderGoogle": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "mcp[cli]",
      "--with",
      "googlemaps",
      "mcp",
      "run",
      "/path/to/mcp-geocoder-rosetta/python-googlemaps/geocoder.py"
    ],
    "env": {
      "GOOGLE_MAPS_API_KEY": "your-api-key-here"
    }
  }
}

注：この実装を正しく動作させるには、--with googlemaps パラメーターが不可欠です。

urllib を使用する Python

"mcpServers": {
  "GeocoderREST": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "mcp[cli]",
      "mcp",
      "run",
      "/path/to/mcp-geocoder-rosetta/python-urllib/geocoder.py"
    ],
    "env": {
      "GOOGLE_MAPS_API_KEY": "your-api-key-here"
    }
  }
}

設定後

1. 変更を加えたらファイルを保存します
2. Claude Desktop に戻ります。アプリケーションが設定を自動的に再読み込みします
3. 設定で確認：Developer タブに、追加したジオコーダーツールが MCP サーバーのリストに表示されていることを確認します
4. ステータスインジケーター：サーバーが正常に起動すると、実行中を示すステータスインジケーターが表示されます

設定のトラブルシューティング

• JSON が有効であること（末尾のコンマがないこと、適切にネストされていること）を確認してください
• 実装ファイルには絶対パスを使用してください
• 環境変数が正しく設定されていることを確認してください
• サーバーが起動しない場合は、そのサーバーの「Advanced options」ドロップダウンを開き、エラーログを確認してください

ライセンス

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

プロジェクト構成に関する注意

一時ディレクトリ

このリポジトリには、テストスクリプトとデバッグスクリプトを動的に生成するために使用される temp/ ディレクトリが複数含まれています：

• /temp/：メインのテストスクリプト用のルート一時ディレクトリ
• python-urllib/temp/：urllib の実装をテストするスクリプトを格納します
• python-googlemaps/temp/：Google Maps API の実装をテストするスクリプトを格納します
• typescript-googlemaps/temp/：TypeScript のテストユーティリティを格納します

これらのディレクトリはテストスクリプトによって作成・使用され、MCP サーバーへの接続、接続の問題の診断、ツールの利用可能性の確認、機能のテストを行うユーティリティスクリプトを生成します。これらは .gitignore に追加されているため、リポジトリにコミットしないでください。

MCP クライアントディレクトリ

mcp-client/ ディレクトリには、以前のクライアント実装が含まれています。現在は run_geocoder.py での MCP との直接通信にほぼ置き換えられています。一部のケースでは引き続き参照され、フォールバックとして使用されますが、現在はより信頼性の高い通信を実現するため、主な機能で MCP ライブラリを直接使用しています。

既知の問題

• インタラクティブ入力は、Claude Code のような非インタラクティブ環境ではうまく動作しません
• 実装を動作させるには、環境のセットアップ（API キー、依存関係）が必要です
• 現在の MCP CLI のバージョンでは mcp tools コマンドを利用できないため、test_server.py では Python を直接使用する方法を採用しています
• 実装によって利用できるツールが異なります（debug_info があるのは urllib のみです）
• 非インタラクティブ環境では、長時間実行されるプロセスがタイムアウトする場合があります（特に TypeScript の起動時）