placeguide

placeguide

placeguide は、119 の旅行先にある場所を掲載する、itsnum のホスト型 places MCP サーバーへの小規模なローカルブリッジです。プーケットで食事をする場所、ロサンゼルスで今営業している場所、施設が公開しているメニューの内容、認証済みの利用者による評価などを尋ねると、回答はすべてディレクトリ自体が管理する掲載情報に基づきます。ディレクトリに掲載されていない場所を、情報の穴を埋めるために作り出すことはありません。

このパッケージは、独自のディレクトリを保持しません。ライブエンドポイントから取得した内容をそのまま使って、ツール一覧への応答をローカルで行い、各ツール呼び出しをアップストリームに転送し、返ってきた内容を変更せずに返します。アップストリームの応答には attribution 文字列を含むものがいくつかあります。これらの結果を表示する際は、取得したツールの説明に従って、その文字列を表示してください。

9 つのツールのうち 3 つは、無料の無料枠で利用できるとアップストリームで説明されています。対象は get_menu、get_reviews、directory_feed です。このインターフェースでは、予約の確定、料金の請求、アカウントの作成は行われません。booking_link は、人数、日付、時刻が入力済みの、施設独自のプラットフォーム上にある予約ページを返します。旅行者はそこで予約を完了しますが、応答の booked: false は常に変わりません。

ツール

• search_places — 旅行先で実際に営業中の場所を検索します。レストラン、バー、ビーチ、スパ、展望スポット、寺院などが対象です。必須：destination（スラッグまたは都市名）。任意：category、near（距離順の結果を得る場合は "lat,lng" 形式の座標ペアを指定します。対象範囲は約 5 km 以内です。地域名を指定するとエリアで絞り込めます）、query（自由入力テキスト）、limit（1～20、デフォルトは 8）。評価（レビュー件数を加味）による品質順、または座標が指定されている場合は品質と距離を組み合わせた順に並びます。判明している場合は、店名、カテゴリー、エリア、評価、レビュー件数、電話番号、住所、営業時間を返します。
• concierge_answer — 旅行者が尋ねるような旅行に関する質問（「今夜、カタ近くで食事をするならどこがおすすめですか？」など）をすると、検証済みディレクトリに基づく簡潔な回答と、名前の挙がった場所の構造化データを返します。必須：question。任意：destination、near、language（BCP-47 タグ。デフォルトは質問の言語）。質問された場所について回答し、別の都市に置き換えることはありません。対象の場所がカバーされていない場合は、推測せずにその旨を伝えます。
• list_destinations — ディレクトリがカバーする旅行先と、それぞれの検証済みスポット数を返します。引数はありません。都市が対応しているか不明な場合は、最初に呼び出してください。
• place_details — search_places で取得した place_id を使って、1 つの場所に関するすべての情報を取得します。必須：place_id。施設自身の掲載情報にある公開連絡先、営業時間、評価、レビュー件数、エリア、カテゴリー、料理の種類、施設自身による短い説明、座標、旅行先のタイムゾーンに基づいて計算された open_now（null は営業時間が未検証であることを示し、休業中という意味ではありません）、予約プラットフォーム、検証済みのオーナーが選択した場合に限り施設自身の予約ページ、記録がある場合は最近確認された公開価格の記載、およびそれぞれの帰属情報付きの写真を返します。
• open_places — 旅行先の現地タイムゾーンに基づき、現在営業中の場所を返します。必須：destination。任意：category、near、bookable_only、limit（1～50、デフォルトは 20）。営業時間が検証済みの施設のみが表示されるため、件数が少ない場合は都市内のスポットが少ないのではなく、営業時間のカバー範囲が限られていることを意味します。
• booking_link — 人数、日付、時刻を入力済みの、1 つの場所の予約ページを返します。必須：place_id。任意：party（1～20）、date（YYYY-MM-DD）、time（HH:MM、24 時間表記、施設の現地時間）。予約は行われず、テーブルも確保されません。応答には必ず booked: false と mode: "deeplink" が含まれます。施設に予約プラットフォームがない場合は、その旨と電話番号を返します。
• get_menu — 施設自身が公開しているメニューまたは提供品目一覧を、施設内のセクションごとに、施設の並び順で返します。必須：place_id。価格は施設が設定したとおりの金額で、施設の現地通貨で表示されます。価格がない品目の price は null です。メニューが公開されていない場合は、sections が空になり、note にその旨が示されます。無料です。
• get_reviews — 1 つの場所の評価概要を返します。必須：place_id。external（掲載情報にある公開評価と件数、およびその情報源）と、num_verified（検証済みの利用客による平均評価、件数、1～5 星の分布）を返します。レビュー本文とレビュアーの身元情報は一切返しません。検証済み評価が 5 件未満の場合は、検証済みの数値はすべて null となり、その理由が note に示されます。無料です。
• directory_feed — 1 回の呼び出しで最大 200 件を取得できる、旅行先ごとの全掲載スポットの一括ページ分割同期機能です。place_id 順に並びます。必須：destination。任意：cursor（返された next_cursor を渡して、null になるまで続けます）、limit（パートナーキーがある場合は 1～200、デフォルトは 100。キーがない場合は最大 50）。各項目には search_places のフィールドに加えて、料理の種類、座標、予約プラットフォームが含まれます。メニュー、レビュー、写真は含まれません。無料です。

設定

• ITSNUM_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://app.itsnum.com/api/partner/mcp です。（この 上書きフックは、この再構築版独自の明示的な 再現です。）
• ITSNUM_PARTNER_KEY（任意）— 設定すると、上流へのすべての リクエストに呼び出し元自身のパートナーキーを含む X-Partner-Key: <value> ヘッダーが付与されます。設定しない場合、 キーヘッダーは送信されず、サーフェスは引き続き応答します。ツール リストはキーなしで取得されており、複数のツールはキー不要の無料 ツールとして説明されています。（ヘッダー名は、シークレットの X-Partner-Key ヘッダーを宣言するオリジナルのレジストリレコードで 固定されています。このレコードではパッケージの環境変数名が固定 されていないため、この環境変数からキーを転送するのは明示的な 再現です。） 取得した説明によると、キーを設定すると directory_feed の ページサイズ上限が50から200に引き上げられます。

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーム可能な HTTP セッションを開きます。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name placeguide）を送信し、続いて notifications/initialized 通知を送信してから、呼び出し元の引数を 変更せずに含めた tools/call リクエストを送信します。上流が initialize に Mcp-Session-Id ヘッダーを付けて応答した場合、その値は セッションの後続のすべてのリクエストに付与され、プロセスの実行中は 同じセッションが再利用されます。応答はプレーンな JSON または サーバー送信イベントで届く場合があり、どちらも読み取られます。

上流で成功した結果は、上流が設定した isError フラグも含め、 そのまま渡されます。JSON-RPC エラー、2xx 以外のステータス、 読み取り不能な応答、完了できないリクエストなどの失敗は、 テキストが placeguide error: で始まる isError 結果として返されます （この形式は、この再構築版独自の明示的な再現です）。

CLI

各ツールは、JSON 引数文字列を1つ受け取るサブコマンドとしても 実行できます。

npx @reneturcios/placeguide search_places '{"destination":"phuket","category":"restaurant"}'
npx @reneturcios/placeguide list_destinations '{}'
npx @reneturcios/placeguide get_menu '{"place_id":"..."}'
npx @reneturcios/placeguide --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法に 誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/placeguide mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "placeguide": {
      "command": "npx",
      "args": ["-y", "@reneturcios/placeguide", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/placeguide
docker run --rm ghcr.io/cloudcorprecords/placeguide --version

コンテナのデフォルトコマンドは mcp であるため、最初の形式では stdio MCP サーバーとして動作します。それ以外の引数は通常どおり CLI に 渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべてスタブ化された JSON-RPC 上流に対して実行され、 実際のネットワーク呼び出しは行いません。

ライセンス

MIT — LICENSE を参照してください。