# Twinkle Hub

> 政府開放資料的 MCP 服務平台，涵蓋 28 個國家／地區的官方開放資料，全部開放查詢，
> 合計 1,100,000+ 筆可查 dataset（另有美國聯邦 API 與韓國法規
> 判例 API 型來源）。一支 virtual API key 接通 Claude Desktop / Claude Code /
> GitHub Copilot CLI / OpenAI Codex CLI / 任何 MCP client。台灣最深
> （data.gov.tw 全量目錄）；部分地區另有專屬前綴工具（tw_ / hk_ / jp_ / kr_ /
> us_ / sg_ / uk_）。

Twinkle Hub 提供一個 MCP (Model Context Protocol) endpoint：
- URL: https://api.twinkleai.tw/mcp/
- Transport: streamable-http (HTTP POST + SSE-style framed responses)
- Auth: OAuth 2.1（Claude 連接器目錄走這條，使用者不必自備金鑰）或
  Bearer token（Twinkle Hub virtual key — get one at /dashboard）
- Tools: 依國別前綴分組 — tw_*（台灣）、us_*（美國）、hk_*（香港）、uk_*（英國）、jp_*（日本）、kr_*（韓國）、sg_*（新加坡）（台灣含驗證/日曆/地理等在地小工具）。
  例：tw_search_datasets, tw_validate_taiwan_id_number, hk_rt_air_quality,
  us_get_fred_series_observations, sg_search_datasets, uk_search_bills
- 計費: Free 方案每 5 小時滾動 50 credits + 每週 200 credits；部分深度語料檢索與全文件取回為 Pro 方案

## Docs

- [接上 Claude](https://hub.twinkleai.tw/docs?aud=claude): 桌面版一鍵裝 (.mcpb) 或 Claude Code 一行指令
- [接上 Codex](https://hub.twinkleai.tw/docs?aud=codex): OpenAI Codex CLI
- [API 文件](https://hub.twinkleai.tw/docs?aud=api): curl, Python fastmcp, tools reference, auth
- [Marketplace](https://hub.twinkleai.tw/data): 資料 + 工具 兩塊

## API Discovery

- Claude Connector Directory（Anthropic verified）: https://claude.com/marketplace/connectors/twinkle-hub
- MCP Server Card: https://hub.twinkleai.tw/.well-known/mcp.json
- Agent Card (A2A): https://hub.twinkleai.tw/.well-known/agent-card.json
- Agent Skills: https://hub.twinkleai.tw/.well-known/agent-skills.json
- API Catalog (RFC 9727): https://hub.twinkleai.tw/.well-known/api-catalog
- OAuth Protected Resource (RFC 9728): https://hub.twinkleai.tw/.well-known/oauth-protected-resource

## 怎麼最快接通

**最快**：在 Claude 的連接器目錄直接加入（Anthropic verified）—
https://claude.com/marketplace/connectors/twinkle-hub

按「Add to Claude」→ 用 Twinkle Hub 帳號登入授權 → 完成。
走 OAuth，不必自己申請或貼上 API key。

**Claude Code（CLI）**：一行 `claude mcp add`，需要一把 API key
（從 https://hub.twinkleai.tw/dashboard 取得）。

其他 client（GitHub Copilot CLI / OpenAI Codex CLI / curl / SDK）
完整安裝路徑見 https://hub.twinkleai.tw/docs

## 授權

- 程式碼: https://github.com/lianghsun/twinkle-hub
- 資料授權: 各筆 dataset 的 license metadata 全程透傳，來源授權不被破壞。
  各地授權（OGDL-Taiwan-1.0 / HK DPO Terms / 日本政府標準利用規約 v2.0 /
  KOGL Type 1 / US 聯邦公有領域 / SG ODL v1（不得再授權）/ OGL-UK-3.0）
  詳見 https://hub.twinkleai.tw/licenses
