API das ferramentas e servidor MCP

Todas as ferramentas do Bluesky.bot também podem ser usadas gratuitamente a partir de código e de agentes de IA: como API REST e como ferramentas do nosso servidor MCP. Sem registo nem chave: basta chamá-las. Cada resposta aponta para a página da ferramenta.

Endpoints

FerramentaAPIFerramenta MCP
Localizador de DIDGET /api/v1/tools/did-finder?handle=…find_did
Localizador de handleGET /api/v1/tools/handle-finder?did=…find_handle
WhoisGET /api/v1/tools/whois?actor=…whois_lookup
Idade de uma contaGET /api/v1/tools/account-age?actor=…check_account_age
Conversor de AT URIGET /api/v1/tools/at-uri-converter?uri=…convert_at_uri
Descodificador de TIDGET /api/v1/tools/tid-decoder?tid=…decode_tid
Contador de caracteresGET /api/v1/tools/character-counter?text=…&numbered=truecount_post_characters
Gerador de facetas de texto ricoGET /api/v1/tools/facet-builder?text=…&langs=enbuild_post_facets
Verificador de handles de domínio próprioGET /api/v1/tools/custom-handle-checker?domain=…&expected=…check_custom_handle
Verificador de disponibilidade de handlesGET /api/v1/tools/handle-availability?name=…check_handle_availability
Histórico PLCGET /api/v1/tools/plc-history?q=…&limit=50&page=1&include_raw=falseplc_history
Analisador de starter packsGET /api/v1/tools/starter-pack-analyser?q=…analyse_starter_pack
Leitor de publicações e fiosGET /api/v1/tools/post-viewer?post=…&embed=falseview_bluesky_post
Inspetor de feedsGET /api/v1/tools/feed-inspector?feed=…&check=falseinspect_bluesky_feed

O URL base é https://bluesky.bot/api/v1. Os parâmetros e a resposta de cada ferramenta estão na referência da API e no documento OpenAPI, /api/v1/openapi.json.

Uma resposta tem sempre a mesma forma: o slug da ferramenta, o URL da sua página e o seu result.

json
{
  "tool": "character-counter",
  "url": "https://bluesky.bot/tools/character-counter",
  "result": { "graphemes": 16, "bytes": 19, "over": false, "parts": [] }
}

Limites

  • Gratuito e anónimo: 60 chamadas por minuto e 2000 por dia por endereço IP. Uma ferramenta que envia vários pedidos nos bastidores conta como mais de uma chamada; a referência da API indica-o.
  • Com um token de API: 10 vezes ambos, contados por conta. Os criadores com pelo menos um bot no Bluesky.bot criam um no painel, em Definições → Acesso à API e à CLI; um token da ferramenta de linha de comandos também serve. Envie-o em Authorization: Bearer <token>. Um token dura 30 dias; mantenha-o fora de código público.
  • O que pode fazer um token do painel: chamar as ferramentas, mais nada. Tem o âmbito tools: não pode gerir os seus bots, reservar ou libertar um handle, nem usar as rotas /api/v1/me/* da CLI, que lhe respondem 401.
  • Acima de um limite, a resposta é 429 com um cabeçalho Retry-After, em segundos.
  • Um token desconhecido, expirado ou revogado recebe 401: retire o cabeçalho para chamar de forma anónima.

Os erros usam a forma habitual da API, { "error": { "code", "message" } }, com bad_request (e o parameter), unauthorized, not_found, rate_limited e upstream_error (o serviço que uma ferramenta consulta não respondeu). As respostas trazem cabeçalhos CORS, para que uma página web as possa chamar, e um cabeçalho de cache: um cálculo puro, como o contador, fica em cache de vez.

Exemplos

Com curl, que codifica o texto por si:

bash
curl -G "https://bluesky.bot/api/v1/tools/character-counter" \
  --data-urlencode "text=Hello Bluesky! 👋"

Em JavaScript ou TypeScript (Node.js 18 ou posterior, Deno, Bun ou um navegador):

tools-api.ts
// tools-api.ts: conta uma publicação com a API gratuita das ferramentas.
// Sem chave.
const url = new URL("https://bluesky.bot/api/v1/tools/character-counter");
url.searchParams.set("text", "Hello Bluesky! 👋");

// Um token de API criado nas definições do painel
// multiplica os limites por dez.
const token = process.env.BSBOT_TOKEN;
const response = await fetch(url, {
  headers: token ? { Authorization: `Bearer ${token}` } : {},
});
if (response.status === 429) {
  const wait = response.headers.get("Retry-After");
  throw new Error(`Rate limited: retry in ${wait} s.`);
}
const answer = (await response.json()) as {
  url: string;
  result: { graphemes: number; graphemesLeft: number; over: boolean };
};

const { graphemes, graphemesLeft } = answer.result;
console.log(`${graphemes} graphemes, ${graphemesLeft} left. ${answer.url}`);

// Torna este ficheiro um módulo ES, de que o await de nível superior precisa.
export {};

Em Python, com requests:

tools-api.py
# tools_api.py: conta uma publicação com a API gratuita das ferramentas.
# Sem chave.
import os

import requests

# Um token de API criado nas definições do painel
# multiplica os limites por dez.
token = os.environ.get("BSBOT_TOKEN")
headers = {"Authorization": f"Bearer {token}"} if token else {}

response = requests.get(
    "https://bluesky.bot/api/v1/tools/character-counter",
    params={"text": "Hello Bluesky! 👋"},
    headers=headers,
    timeout=10,
)
if response.status_code == 429:
    wait = response.headers["Retry-After"]
    raise SystemExit(f"Rate limited: retry in {wait} s.")
response.raise_for_status()

answer = response.json()
result = answer["result"]
print(f"{result['graphemes']} graphemes, {result['graphemesLeft']} left. {answer['url']}")

Servidor MCP

O servidor MCP lista as mesmas ferramentas, com os seus esquemas de entrada e de saída, para agentes de IA e editores: https://bluesky.bot/api/mcp (Streamable HTTP, sem sessão). Todas as ferramentas são só de leitura. Aplicam-se os mesmos limites; um token no cabeçalho Authorization aumenta-os.

Ligação num clique

Prefere iniciar sessão a colar um token? Adicione https://bluesky.bot/api/mcp/connect em vez disso. A sua app de IA abre uma página do Bluesky.bot: inicie sessão com a sua conta Bluesky (nunca pedimos a sua palavra-passe), verifique o nome da app e o endereço para onde ela o leva de volta, e autorize. A app recebe então o seu próprio token e renova-o sozinha.

No Claude Code:

bash
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp/connect

No Claude Desktop ou em claude.ai, adicione um conector personalizado com esse URL e escolha Ligar. No Cursor ou no VS Code, use-o como url da configuração abaixo e inicie sessão quando o editor pedir.

  • A app recebe o âmbito tools: as ferramentas, com os limites mais altos da sua conta se tiver um bot no Bluesky.bot. Não pode publicar, gerir os seus bots nem reservar um handle.
  • Uma app que autorizou fica memorizada. Revogue-a quando quiser em Definições → Apps ligadas; Terminar sessão em todo o lado e eliminar a sua conta revogam todas as apps.
  • Só algumas apps bem conhecidas aparecem como Verificada. Para as outras, verifique o endereço para onde o levam de volta antes de autorizar.
  • https://bluesky.bot/api/mcp continua a funcionar sem iniciar sessão.

No Claude Code:

bash
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp

No Cursor (.cursor/mcp.json), no VS Code (.vscode/mcp.json, com "servers" em vez de "mcpServers") e na maioria dos outros clientes:

json
{
  "mcpServers": {
    "bluesky-bot": { "url": "https://bluesky.bot/api/mcp" }
  }
}

No Claude Desktop ou no claude.ai, adicione-o como conector personalizado com o mesmo URL. Com um token, adicione um cabeçalho: --header "Authorization: Bearer $BSBOT_TOKEN" no Claude Code, ou "headers": { "Authorization": "Bearer …" } ao lado de url numa configuração JSON. Nunca envie para um repositório um ficheiro de configuração que contenha um token: guarde-o numa variável de ambiente ou nas definições privadas do seu cliente.

O que é enviado, o que é guardado

O que envia a uma ferramenta serve apenas para responder: nunca é guardado e é retirado dos nossos relatórios de erros. Uma chamada à API leva-o no seu endereço: os registos de pedidos do nosso servidor ignoram esses endereços, mas passam pela rede da Cloudflare que transporta o tráfego do site. O MCP envia-o no corpo do pedido, que nenhum registo de pedidos guarda: pode preferi-lo para um texto sensível. As estatísticas contam apenas que ferramenta foi chamada, de onde (uma página, a API ou MCP) e como terminou. Uma ferramenta que procura algo envia a entrada aos serviços públicos de que precisa, tal como a sua página. Consulte a política de privacidade.