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
| Ferramenta | API | Ferramenta MCP |
|---|---|---|
| Localizador de DID | GET /api/v1/tools/did-finder?handle=… | find_did |
| Localizador de handle | GET /api/v1/tools/handle-finder?did=… | find_handle |
| Whois | GET /api/v1/tools/whois?actor=… | whois_lookup |
| Idade de uma conta | GET /api/v1/tools/account-age?actor=… | check_account_age |
| Conversor de AT URI | GET /api/v1/tools/at-uri-converter?uri=… | convert_at_uri |
| Descodificador de TID | GET /api/v1/tools/tid-decoder?tid=… | decode_tid |
| Contador de caracteres | GET /api/v1/tools/character-counter?text=…&numbered=true | count_post_characters |
| Gerador de facetas de texto rico | GET /api/v1/tools/facet-builder?text=…&langs=en | build_post_facets |
| Verificador de handles de domínio próprio | GET /api/v1/tools/custom-handle-checker?domain=…&expected=… | check_custom_handle |
| Verificador de disponibilidade de handles | GET /api/v1/tools/handle-availability?name=… | check_handle_availability |
| Histórico PLC | GET /api/v1/tools/plc-history?q=…&limit=50&page=1&include_raw=false | plc_history |
| Analisador de starter packs | GET /api/v1/tools/starter-pack-analyser?q=… | analyse_starter_pack |
| Leitor de publicações e fios | GET /api/v1/tools/post-viewer?post=…&embed=false | view_bluesky_post |
| Inspetor de feeds | GET /api/v1/tools/feed-inspector?feed=…&check=false | inspect_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.
{
"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 respondem401. - Acima de um limite, a resposta é
429com um cabeçalhoRetry-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:
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: 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: 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']}")O texto viaja no endereço de um pedido GET, que os servidores cortam por
volta dos 8 KB. Para um texto longo, use o servidor MCP: envia a entrada no
corpo do pedido.
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:
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp/connectNo 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/mcpcontinua a funcionar sem iniciar sessão.
No Claude Code:
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcpNo Cursor (.cursor/mcp.json), no VS Code (.vscode/mcp.json, com
"servers" em vez de "mcpServers") e na maioria dos outros clientes:
{
"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.