A maior parte da documentação de SDK é escrita para uma pessoa que a lê às duas da tarde de uma terça-feira. Cada vez mais, o primeiro leitor é um assistente de programação, e ele tem outro problema: precisa ter certeza, e texto corrido não dá certeza.
Eu resolvia isso publicando a referência inteira do SDK num único arquivo de texto puro, para o assistente baixar de uma vez. Era uma ideia razoável que envelheceu mal. Um bloco único de texto corrido continua sendo texto corrido: o assistente lê, resume, e algumas centenas de linhas depois escreve o nome de um método que nunca esteve no arquivo. E um documento mantido ao lado do código se afasta do código, e essa é a única falha que uma referência não pode ter.
Duas coisas tomaram o lugar dele, e as duas são mais rígidas.
Os tipos são a referência
O @kookee/sdk vem com declarações TypeScript. Instale o pacote e a referência está no disco, no contexto do assistente, numa forma que ele não tem como lembrar errado:
npm install @kookee/sdkAgora o prompt é curto, porque a precisão está nos tipos, não no prompt:
Crie um blog com o pacote
@kookee/sdk, que já está instalado. Uma página de listagem (/blog) com filtro por tags, busca e paginação, e uma página de detalhe (/blog/:slug) com o conteúdo HTML renderizado e reações com emoji. Next.js App Router, buscando os dados em server components. Leia a chave deprocess.env.KOOKEE_API_KEY.
O assistente escreve kookee.blog.list({ page, limit, tags, search, locale }) porque essa é a assinatura, não porque lembrou de um parágrafo. E quando eu mudo um método, as declarações mudam na mesma versão, sem um segundo artefato para esquecer de atualizar. Esse era o argumento de verdade contra o arquivo de texto: ele podia estar errado, e uma referência que pode estar errada é pior do que nenhuma, porque ninguém desconfia dela.
A resposta que ele espera tem o mesmo formato da que você recebe:
const response = await kookee.blog.list({ page: 1, limit: 10, tags: ['engineering'] });
response.data; // BlogEntryListItem[]
response.total; // 25
response.totalPages; // 3Se você prefere colocar páginas prontas em vez de gerá-las, o @kookee/react tem componentes de blog renderizados no servidor: veja Criar um blog com os componentes React.
O conteúdo é a outra metade
Os tipos dizem a um assistente o que ele pode chamar. Não dizem nada sobre o que existe no seu projeto, e metade dos erros de uma primeira integração vem dessa lacuna: um slug de categoria que não existe, um campo que o código nunca lê, uma página vazia que no fim era um projeto vazio.
Por isso, conecte o assistente ao seu projeto de verdade:
claude mcp add --transport http kookee https://api.kookee.dev/api/mcp \
--header "Authorization: Bearer $KOOKEE_MCP_TOKEN"Agora o prompt muda de natureza. “Crie uma página de registro de alterações” vira:
Leia as entradas do meu registro de alterações e depois crie uma página que as renderize do jeito que elas estão estruturadas de fato.
E ele lê mesmo. Descobre que o tipo da mudança fica num array fields, e não na própria entrada, que duas entradas não têm versão, que as suas categorias seguem um padrão de nome e as tags outro. A página que ele escreve corresponde aos seus dados, não a um exemplo genérico. E como ele também pode escrever no projeto, ele mesmo corrige a primeira coisa que perceber que está faltando.
O que você ainda precisa
Um projeto no Kookee com pelo menos um post publicado. Um projeto vazio gera uma página vazia, e é difícil distinguir isso de um bug.
Uma chave de API em Conexões → Chaves de API para a aplicação. Ela só dá acesso a conteúdo publicado, então pode ir no bundle do cliente sem risco.
Um token MCP pessoal em Conexões → Servidor MCP, se você quer que o assistente leia o seu conteúdo real. Somente leitura basta para isso. Mesmo assim, mantenha o token fora do código: ele lê os seus rascunhos.
Além do blog
O mesmo formato serve para as outras seções:
Crie uma central de ajuda com navegação por categorias, busca semântica e páginas de artigo.
Crie uma página de registro de alterações agrupada por tipo de mudança, com reações com emoji.
Crie uma de cada vez. Três ao mesmo tempo geram um diff que ninguém revisa com cuidado, e é assim que um bug plausível chega à produção.
O fio condutor: pare de pedir a um assistente que lembre a sua API e dê a ele algo que não tem como ser lembrado errado. Os tipos e os próprios dados.