AI导哈

地理编码服务

提供本地搜索、地理编码和反向地理编码功能的HTTP服务器，支持Model Context Protocol (MCP)工具。

  • by agts86
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 agts86/yahoo-developer-mcp

使用说明

Yahoo Developer MCP Server

Yahoo!ローカルサーチ / ジオコーダ / リバースジオコーダ API を Model Context Protocol (MCP) ツールとして公開する HTTP サーバー。

機能

  • ローカルサーチ: キーワード or 座標ベース検索 + 10件ページング
  • ジオコーダ: 住所テキストから座標取得
  • リバースジオコーダ: 座標から住所取得
  • ページング: 初回10件、同条件連続呼び出しで次10件。reset でリセット。

システム要件

  • Node.js >= 24
  • pnpm (推奨) または npm

主要依存関係

  • @modelcontextprotocol/sdk: MCP フレームワーク
  • @nestjs/core: NestJS フレームワーク
  • @nestjs/platform-fastify: Fastify プラットフォーム
  • typescript: TypeScript コンパイラ
  • jest: テストフレームワーク

起動

pnpm install
pnpm build
pnpm start

または開発モード:

pnpm dev

Docker で開発する

開発用コンテナを使えば Node のバージョンや依存を気にせず手元のエディタで編集できます（ファイル変更は自動リロード）。

# ビルド＆起動
docker compose up --build

# 別ターミナルでテストなど実行
docker compose exec app pnpm test
  • ./docker-compose.yml は Dockerfile.dev を利用します。初回ビルド時にコンテナ内へ pnpm install 済み。
  • リポジトリ全体を /app にバインドし、node --watch でソース変更時にサーバーを再起動します。

MCP クライアントでの使用

HTTP モード（推奨）

  1. HTTPサーバーを起動:

    pnpm start

  2. MCP クライアントで以下を設定:

    GitHub Copilot (VS Code) の場合:

    mcp.json (Windows: %APPDATA%\Code\User\mcp.json, macOS/Linux: ~/.config/Code/User/mcp.json) に以下を追加:

    {
  "servers": {
    "yahoo-developer-local": {
      "type": "http",
      "url": "http://localhost:3000/mcp/stream",
      "tools": ["*"],
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {取得済みトークン}"
      }
    }
  }
}

    codex (VS Code) の場合:

    config.toml (macOS/Linux: ~/.codex/config.toml) に以下を追加:

     [mcp_servers.yahoo-developer]
 url = "http://localhost:3000/mcp/stream"
 enabled = true
 http_headers = { "Authorization" = "Bearer {取得済みトークン}" }

  3. MCP クライアントを再起動して MCP ツールを使用開始

Vercel デプロイ先を使う場合

Vercel 上の URL を MCP クライアントへ設定する場合も、エンドポイントは /mcp/stream です。

[mcp_servers.yahoo-developer]
url = "https://your-deployment.vercel.app/mcp/stream"
enabled = true
http_headers = { "Authorization" = "Bearer {取得済みトークン}" }

Codex で Unexpected content type: text/html が出る場合、MCP サーバーではなく Vercel の保護ページや別アプリの HTML に到達している可能性があります。以下を確認してください。

  • URL が /mcp/stream で終わっていること
  • curl -i https://your-deployment.vercel.app/mcp が JSON を返すこと
  • Preview Deployment などで Deployment Protection が有効な場合は、Vercel の Protection Bypass for Automation を発行し、x-vercel-protection-bypass ヘッダーを追加すること
[mcp_servers.yahoo-developer]
url = "https://your-deployment.vercel.app/mcp/stream"
enabled = true
http_headers = { "Authorization" = "Bearer {取得済みトークン}", "x-vercel-protection-bypass" = "{Vercel の bypass secret}" }

stdio モード

HTTPサーバーを立てずに、MCP クライアントからプロセスを直接起動する方式です。Yahoo App ID はリクエストヘッダーではなく環境変数 YAHOO_APP_ID から解決されます（プロセス全体で単一のキーを使用）。

  1. プロジェクトをビルド:

    pnpm build

  2. .env に YAHOO_APP_ID を設定（.env.example を参照）:

    YAHOO_APP_ID=your_app_id_here

  3. MCP クライアントの設定に以下を追加（Claude Desktop の claude_desktop_config.json 等）:

    {
  "mcpServers": {
    "yahoo-developer": {
      "command": "node",
      "args": ["--env-file=.env", "dist/main.js"],
      "cwd": "/path/to/yahoo-developer-mcp",
      "env": {
        "MCP_MODE": "stdio"
      }
    }
  }
}

    動作確認だけしたい場合は pnpm start:stdio（開発時は pnpm dev:stdio）でも起動できます。

MCP ツール概要

Tool Name Params 説明
Local Search localSearch query? lat? lng? sessionId? reset? offset? results? キーワードまたは座標検索。ページングは内部管理。
Geocode geocode query 住所->座標
Reverse Geocode reverseGeocode lat lng 座標->住所

ページング仕様

  • 内部 sessionId + 検索条件ハッシュで前回 offset を保持
  • 明示的に offset 指定可能 (上書き)
  • reset=true で最初のページに戻る

テスト

pnpm test

差し替え

HTTPクライアントは抽象化済み。fetch 実装から将来 axios へ容易に差し替え可能。

API詳細ドキュメント

Local Search Tool

パラメータ:

  • query (string, optional): キーワード検索文字列
  • lat (number, optional): 座標検索の緯度
  • lng (number, optional): 座標検索の経度
  • sessionId (string, optional): ページング継続用セッションID
  • offset (number, optional): 明示的オフセット指定 (0-based)
  • reset (boolean, optional): ページングリセット
  • results (number, optional): カスタムページサイズ (デフォルト: 10)

レスポンス例:

{
  "items": [
    {
      "name": "スターバックス 新宿店",
      "address": "東京都新宿区新宿3-38-1",
      "lat": 35.689521,
      "lng": 139.691706,
      "category": "カフェ",
      "tel": "03-1234-5678"
    }
  ],
  "nextOffset": 10
}

Geocode Tool

パラメータ:

  • query (string, required): 住所文字列

レスポンス例:

{
  "items": [
    {
      "address": "東京都新宿区新宿3-38-1",
      "lat": 35.689521,
      "lng": 139.691706,
      "name": "新宿駅前"
    }
  ]
}

Reverse Geocode Tool

パラメータ:

  • lat (number, required): 緯度
  • lng (number, required): 経度

レスポンス例:

{
  "items": [
    {
      "address": "東京都新宿区新宿3-38-1",
      "name": "東京都新宿区新宿"
    }
  ]
}

相关 MCP