Taiwan Garbage Truck Map

台湾ごみ収集車マップ — MCP サーバー

garbage.yukai.dev を支えるごみ収集車データセット向けの読み取り専用 Model Context Protocol サーバーです。mcp-handler 2.x と @modelcontextprotocol/server 2.x を基盤として構築されており、MCP プロトコルバージョン 2025-11-25、2025-06-18、2025-03-26 に対応する、ステートレスな Streamable HTTP エンドポイントを 1 つ公開します。

このサーバーはウェブアプリの市区町村アダプター（../src/cities）を再利用し、サイトと MCP の応答でフィールドのマッピングを統一しています。データは公開済みの JSON ファイルから取得され（DATA_BASE_URL。デフォルトは https://garbage.yukai.dev）、ウォームインスタンスごとにメモリ上で 1 時間キャッシュされます。市区町村のデータは必要に応じて遅延読み込みされます（注：台中市のデータセットは約 50 MB で、初回読み込みに約 1 秒、メモリ上で約 400 MB の RSS を使用します）。

ツール

ツール	目的
list_cities	対応している市区町村、その ID、地理的な境界ボックスを一覧表示します
find_nearby_points	座標から 50～2,000 m 以内の停留所を、近い順に検索します
search_points	市区町村内の停留所を、行政区、里、道路、路線のキーワードで検索します
get_schedule	停留所と、その路線上にあるすべての停留所を到着順で取得します

すべてのツールには読み取り専用の注釈が付いており、プレーンテキストの概要に加えて structuredContent を返します。時刻はすべて Asia/Taipei です。

新北市と台中市（オープンデータに曜日別のスケジュールが含まれる市区町村）では、各停留所に週間の schedule（collectionType → ISO 曜日、1=月曜日 … 7=日曜日）と、台湾時間で計算された servesToday のブール値が含まれます。台北市と高雄市では曜日別のスケジュールが公開されていないため、これらのフィールドは省略されます。台中市ではウェブアプリのデフォルト表示が「今日のみ」ですが、エージェントが週の任意の曜日について回答できるよう、MCP サーバーはアダプターを allDays モードで読み込みます。

開発

cd mcp
bun install
bun test            # query logic + adapter schedule tests
bun run typecheck
bun dev.ts          # http://localhost:3939/api/mcp

MCP Inspector で対話的にテストします：

npx @modelcontextprotocol/inspector

その後、http://localhost:3939/api/mcp に接続します。

デプロイ（Vercel）

このディレクトリは、GitHub Pages のウェブアプリとは別の独立した Vercel プロジェクト（taipei-trash-mcp）としてデプロイされます。サーバーレス関数はビルド時に esbuild でバンドルされるため（bun run build → api/mcp.js）、../src/cities 内の拡張子を省略した TypeScript のインポートを Node ESM で正しく解決できます。

リポジトリのルートからデプロイする場合（.vercelignore によりアップロード内容が最小限に抑えられます）：

1. Vercel にリポジトリをインポートし、Root Directory を mcp に設定します。
2. ビルドで ../src/cities をインポートできるように、Include source files outside of the Root Directory を有効のままにします（デフォルト）。
3. カスタムドメイン（vercel api /v10/projects/<id>/domains -X POST -F name=mcp.garbage.yukai.dev）を追加し、DNS プロバイダーで CNAME と _vercel の TXT レコードを設定します。
4. 任意の環境変数：DATA_BASE_URL、MCP_ALLOWED_ORIGINS（ブラウザークライアント向けのカンマ区切り許可リスト）。
5. レート制限は Vercel Firewall ルール（mcp-rate-limit：/api/mcp と /mcp で IP ごとに毎分 60 リクエスト）によって適用されます。

本番エンドポイント：**https://mcp.garbage.yukai.dev/mcp**（`/api/mcp` からもアクセス可能。フォールバックは https://taipei-trash-mcp.vercel.app）。stdio のみをサポートするクライアントでは、npx mcp-remote https://mcp.garbage.yukai.dev/mcp を使用してください。

ディスカバリーエンドポイント

• /mcp/server-card — MCP Server Card（SEP-2127）。public/server-card.json から application/mcp-server-card+json として提供されます。
• /.well-known/ai-catalog.json — Server Card を参照する AI Catalog エントリー（https://garbage.yukai.dev でもホストされています）。
• /llms.txt — LLM 向けのプレーンテキストガイド。

ディレクトリへの掲載

• server.json — このリモート専用サーバーの公式 MCP Registry用マニフェストです。public/server-card.jsonと同じname、version、title、description、リポジトリ、リモート URL を反映しているため、両者の内容が食い違うことはありません。

• 公式 CLI で公開します（名前空間dev.yukai/*には、yukai.devの DNS または HTTP による検証が必要です。GitHub OAuth で取得できるのはio.github.*/*のみです）。

  mcp-publisher validate server.json
  mcp-publisher login dns --domain yukai.dev --private-key "$PRIVATE_KEY"
  mcp-publisher publish server.json
  

• 公式レジストリ、Smithery、Glama、PulseMCP、mcp.so、awesome-remote-mcp-servers への登録手順（貼り付ける内容と手動でのアカウント作成／DNS 設定手順を含む）は、docs/mcp-directory-submission.mdをご覧ください。

セキュリティに関する注意事項

• 認証なし：基盤となるデータはすべて政府が公開するオープンデータであり、すべてのツールは厳密に読み取り専用です。
• オリジンのチェック：Originヘッダーを含むリクエストは、MCP トランスポート仕様に従い、オリジンがMCP_ALLOWED_ORIGINSに記載されていない限り403で拒否されます。ネイティブクライアントおよびサーバーサイドクライアントはOriginヘッダーを送信しません。