Docs - Twinkle Hub

取得 API key

/login → 使用 Google 或 GitHub 一鍵登入。首次登入將自動發放一支 virtual API key (sk-...)。新帳號預設餘額為 0 — 自助儲值功能即將開放。

curl（streamable-http transport）

步驟 1：initialize 以取得 session id（位於 response header 的 mcp-session-id）

text

curl -i -X POST https://api.twinkleai.tw/mcp/ \
  -H "Authorization: Bearer sk-..." \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

步驟 2：tools/call

text

curl -X POST https://api.twinkleai.tw/mcp/ \
  -H "Authorization: Bearer sk-..." \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <from-step-1>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"tw_list_domains","arguments":{}}}'

Response 採用 SSE-style framing——請尋找以 data: 開頭的最後一行，並解碼 JSON。

Python (fastmcp)

python

import asyncio
from fastmcp.client import Client
from fastmcp.client.auth import BearerAuth

async def main():
    async with Client(
        "https://api.twinkleai.tw/mcp/",
        auth=BearerAuth("sk-..."),
    ) as client:
        tools = await client.list_tools()
        print([t.name for t in tools])

        r = await client.call_tool(
            "tw_search_datasets",
            {"query": "AQI", "domain": "environment", "limit": 5},
        )
        # response 在 r.content[0].text — JSON string
        import json
        print(json.loads(r.content[0].text))

asyncio.run(main())

Tool 回傳 CallToolResult.content[0].text，內容為 JSON string。licence、citation 等 metadata 會透過 _meta 欄位透傳。

Tools reference

Tool	Arguments	回傳值（簡）
tw_list_domains	—	[{key, name_zh, scope, typical_questions}]
tw_search_datasets	{query, domain?, limit?}	[{dataset_id, title, score, license}]
tw_get_dataset	{dataset_id}	{schema, columns, license, source_url}
tw_query_rows	{dataset_id, where?, limit?}	[row, ...]
tw_materialize_dataset	{dataset_id, format?}	全表 CSV / JSON

呼叫 tools/list 即可取得所有 tool 的完整 schema，並自動生成 JSON Schema。

Authentication

Bearer token——header 設定為 Authorization: Bearer sk-...。這是 Twinkle Hub 發行的 virtual key，每位 user 專屬。Key 請至 /dashboard 取得。
無 OAuth flow——客戶端無需 PKCE 或 refresh token，僅需一支 long-lived bearer。
Rate limit——Free 方案由滾動額度控管（每 5 小時 50 credits，滾動回補，另有每週 500 上限），非 USD 預算或 per-key RPM/TPM。

計費

即將開放

核心工具現已免費——每 5 小時 50 credits，滾動回補（另有每週 500 上限）。免費方案 query_rows 每次最多回傳 10 筆。深度語意搜尋與全文件取回保留給即將推出的 Pro；Pro 定價將於計費前公佈。

Free 方案：每 5 小時 50 credits，滾動回補（另有每週 500 上限）；免費方案 query_rows 每次最多回傳 10 筆；深度語意搜尋與全文件取回為 Pro 專屬。額度控管已生效（可能有輕微非同步延遲）。