문서 - 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":"tw_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(
            "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())

도구는 CallToolResult.content[0].text를 JSON 문자열로 반환. 라이선스, 인용, 기타 메타데이터는 _meta 필드로 투과.

도구 레퍼런스

도구	인자	반환 값 (간략)
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를 통해 — JSON Schema로 자동 생성.

인증

Bearer 토큰 — 헤더 Authorization: Bearer sk-.... Twinkle Hub 발행 가상 키, 사용자당 1 개. /dashboard에서 받으세요.
OAuth 플로우 없음 — PKCE / 리프레시 토큰 불필요; 장기 bearer 하나.
레이트 제한 — Free 플랜은 롤링 방식 credits 한도(5시간마다 50, 서서히 회복, 주간 500 상한 별도)로 관리되며, USD 예산이나 키당 RPM/TPM 이 아닙니다.

요금

곧 제공

핵심 도구는 현재 무료입니다 — 5시간마다 50 credits, 서서히 회복(주간 500 상한 별도). Free 플랜에서는 query_rows 가 호출당 최대 10 건을 반환합니다. 일부 심층 코퍼스 검색과 전체 문서 조회는 곧 출시될 Pro 플랜 전용이며, 과금 시작 전에 Pro 가격을 공지합니다.

Free 플랜: 5시간마다 50 credits, 서서히 회복(주간 500 상한 별도); query_rows 는 호출당 최대 10 건을 반환합니다; 일부 심층 코퍼스 검색과 전체 문서 조회는 Pro 전용입니다. 한도 제어는 현재 적용 중입니다 (약간의 비동기 지연 있음).