Setup en 10 minutes

Une fois connecté, votre agent voit trois outils. Les régions et les jeux de données ne sont pas des centaines d'outils : ce sont l'argument tool_id de execute_tool — ajouter une région n'allonge donc jamais votre contexte.

1. 1discover_toolsDécrivez en langage naturel les données cherchées ; il renvoie les tool_id adaptés.
2. 2inspect_toolEn cas de doute sur les paramètres, consultez d'abord la définition complète et sa tarification.
3. 3execute_toolExécutez. Facturation, droits et limites de débit sont inchangés.

L'appel externe a toujours cette forme

execute_tool({
  tool_id: "tw_query_dataset",
  arguments: {
    dataset_id: "pcc-tender",
    filters: [{ field: "agency", operator: "contains", value: "交通部" }],
    limit: 10
  }
})

L'appel externe ne comporte que deux clés, tool_id et arguments. Tout le reste va dans arguments — aplatir les paramètres au niveau externe est l'erreur la plus fréquente.

D'où vient ce dataset_id ? Chaque page régionale du catalogue de données les liste. La répartition : là-bas l'identité des données, ici la façon de les appeler.

Étape 1 : initialiser et capturer le session id depuis l'en-tête de réponse mcp-session-id

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"}}}'

Étape 2 : tools/call

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":"execute_tool",
        "arguments":{
          "tool_id":"tw_search_datasets",
          "arguments":{"query":"空氣品質","limit":5}
        }}}'

La réponse utilise un framing style SSE — trouvez la dernière ligne commençant par data: et parsez le JSON.

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])

        # 外層一定是 execute_tool，tool_id 與 arguments 兩個鍵
        r = await client.call_tool(
            "execute_tool",
            {
                "tool_id": "tw_query_dataset",
                "arguments": {
                    "dataset_id": "pcc-tender",
                    "filters": [
                        {"field": "agency", "operator": "contains", "value": "交通部"}
                    ],
                    "limit": 10,
                },
            },
        )
        # response 在 r.content[0].text — JSON string
        import json
        print(json.loads(r.content[0].text))

asyncio.run(main())

Les outils retournent CallToolResult.content[0].text sous forme de chaîne JSON. Licence, citation et autres métadonnées passent dans le champ _meta.

Ces trois-là sont tout ce que renvoie tools/list. Déterminer lequel convient à une région ou à un jeu de données est le travail de discover_tools ; inspect_tool vous donne le JSON Schema complet de l'outil et sa tarification.

• Bearer token — en-tête Authorization: Bearer sk-.... Une clé virtuelle émise par Twinkle Hub, une par utilisateur. Récupérez la vôtre depuis /dashboard.
• Pas de flux OAuth — pas besoin de PKCE / refresh tokens ; juste un bearer long-terme.
• Rate limit — encadré par un volume de crédits glissant selon le forfait, pas par un budget en USD ni un RPM/TPM par clé. Les chiffres de chaque forfait sont sur la page Tarifs.

Allocation gratuite, limites de débit et différences entre les forfaits : tout est sur la page Tarifs. Une fois l’allocation épuisée, la gateway refuse les appels jusqu’à ce qu’elle se recharge, puis reprend d’elle-même — rien à réinitialiser.