🤖 STREAMABLE HTTP MCP SERVER (`/api/mcp`)

KaifongMap Model Context Protocol (MCP) 接入指南

街坊地圖實作了符合最新 MCP 規範的無狀態 **Streamable HTTP Transport** (`/api/mcp`)，完美兼容 Vercel Serverless 環境（不依賴已棄用的 SSE）。AI 代理可即時查詢香港 18 區公共設施、實時交通及天氣鏡頭、分區 AQHI 健康風險及街坊收藏路線。

1. 快速連接設定 (Claude Desktop / Cursor / Custom Agent)

🔑 取得個人 API 密鑰

{
  "mcpServers": {
    "kaifongmap": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer kfm_live_your_personal_api_key"
      }
    }
  }
}

2. 內置 MCP 工具參考 (`src/lib/mcp/tools.js` 單一真相來源)

find_nearby_facilitiesScope: read

Find nearby Hong Kong public facilities (recycling bins, smart bins, food waste machines, public toilets, water fountains, sports centres, parks) and live traffic/weather cameras within a radius.

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "description": "Center WGS84 latitude (e.g. 22.3019)"
    },
    "longitude": {
      "type": "number",
      "description": "Center WGS84 longitude (e.g. 114.1742)"
    },
    "radius_meters": {
      "type": "number",
      "default": 500,
      "maximum": 5000,
      "description": "Search radius in meters (default 500, max 5000)"
    },
    "category": {
      "type": "string",
      "description": "Optional category code from catalog: RECYCLING, SMART_BIN, FOOD_WASTE, TOILET, WATER_FOUNTAIN, SPORTS, PARK, CCTV_TRAFFIC, CCTV_WEATHER, AIR_QUALITY"
    },
    "tag": {
      "type": "string",
      "description": "Optional capability tag filter (e.g. \"waste:Glass Bottles\", \"toilet:accessible\", \"cam:hd\")"
    },
    "public_only": {
      "type": "boolean",
      "description": "If true, exclude residents-only facilities"
    },
    "locale": {
      "type": "string",
      "enum": [
        "zh-HK",
        "en",
        "zh-CN"
      ],
      "default": "zh-HK"
    }
  },
  "required": [
    "latitude",
    "longitude"
  ]
}

get_facility_statusScope: read

Retrieve full metadata, opening hours, maintenance schedule, live camera snapshot URL, recent reviews, and 2-hour rolling crowdsourced availability reports for a facility.

{
  "type": "object",
  "properties": {
    "facility_id": {
      "type": "string",
      "description": "Facility CUID identifier"
    }
  },
  "required": [
    "facility_id"
  ]
}

report_facility_issueScope: write (需綁定註冊街坊密鑰)

Submit a crowdsourced real-time availability vote (AVAILABLE, FULL, or OUT_OF_ORDER) for a facility and refresh its 2-hour rolling status.

{
  "type": "object",
  "properties": {
    "facility_id": {
      "type": "string",
      "description": "Facility CUID identifier"
    },
    "status": {
      "type": "string",
      "enum": [
        "AVAILABLE",
        "FULL",
        "OUT_OF_ORDER"
      ],
      "description": "Current status observed by user or agent"
    },
    "note": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional brief note (max 200 chars)"
    }
  },
  "required": [
    "facility_id",
    "status"
  ]
}

get_district_weatherScope: read

Fetch nearest HKO weather station temperature, 18-district past-hour rainfall, UV index, EPD AQHI health risk, and active weather warnings.

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "description": "WGS84 latitude in Hong Kong"
    },
    "longitude": {
      "type": "number",
      "description": "WGS84 longitude in Hong Kong"
    },
    "locale": {
      "type": "string",
      "enum": [
        "zh-HK",
        "en",
        "zh-CN"
      ],
      "default": "zh-HK"
    }
  },
  "required": [
    "latitude",
    "longitude"
  ]
}

get_saved_mapScope: read

Fetch a curated public Saved Map by its URL slug, including map bounds, active category filters, and pinned facilities.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Public saved map slug (e.g. \"sheung-wan-green-route\")"
    }
  },
  "required": [
    "slug"
  ]
}

list_data_sourcesScope: read

List all active Hong Kong open data sources (code, provider, record count, freshness, health) plus the complete category and tag catalogs for discovery.

{
  "type": "object",
  "properties": {}
}