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 ツール概要

ページング仕様

• 内部 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": "東京都新宿区新宿"
    }
  ]
}