ドキュメント - Twinkle Hub

API キーを取得

/login → Google または GitHub でサインイン。初回ログインで自動的に仮想 API キー（sk-...）を発行。新規アカウントは残高 $0 から — セルフサービスの入金は近日対応。

curl（streamable-http トランスポート）

ステップ 1：initialize して mcp-session-id レスポンスヘッダーから 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":"opendata-list_domains","arguments":{}}}'

レスポンスは SSE スタイルのフレーミング — 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(
            "opendata-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())

ツールは CallToolResult.content[0].text を JSON 文字列として返します。ライセンス、引用、その他のメタデータは _meta フィールドで透過。

ツールリファレンス

ツール	引数	戻り値（簡潔）
opendata-list_domains	—	[{key, name_zh, scope, typical_questions}]
opendata-search_datasets	{query, domain?, limit?}	[{dataset_id, title, score, license}]
opendata-get_dataset	{dataset_id}	{schema, columns, license, source_url}
opendata-query_rows	{dataset_id, where?, limit?}	[row, ...]
opendata-materialize_dataset	{dataset_id, format?}	全表 CSV / JSON

完全なスキーマは tools/list 経由 — JSON Schema として自動生成。

認証

Bearer トークン — ヘッダー Authorization: Bearer sk-...。Twinkle Hub 発行の仮想キー、ユーザー 1 人につき 1 つ。/dashboard から取得してください。
OAuth フローなし — PKCE / リフレッシュトークン不要；長期 bearer 一本。
レート制限 — 現時点でキーごとの RPM/TPM 制限なし；max_budget のみ強制（spend > max_budget でゲートウェイが拒否）。

料金

近日対応

アルファ期間中はすべてのツールが無料。課金開始前にツール単位の料金を発表し、既存ユーザーには移行割引期間を提供します。

アルファ期間中は無料。spend 追跡パイプラインは動作（5〜15 秒の非同期ラグ、ゲートウェイは DB 書き込みをバッチ）；課金開始後はクォータ強制が次のリクエストでリアルタイム適用。