Casi toda la documentación de un SDK está escrita para una persona que la lee un martes a las dos de la tarde. Cada vez más, el primer lector es un asistente de programación, y su problema es otro: necesita certeza, y la prosa no se la da.
Antes lo resolvía publicando toda la referencia del SDK como un único archivo de texto plano, para que el asistente lo descargara de una vez. Era una idea razonable que envejeció mal. Un volcado de prosa sigue siendo prosa: el asistente la lee, la resume y, unos cientos de líneas después, escribe un nombre de método que nunca estuvo en el archivo. Además, un documento que se mantiene en paralelo al código acaba desfasándose respecto a él, y ese es justo el fallo que una referencia no se puede permitir.
Lo sustituyeron dos cosas, y las dos son más estrictas.
Los tipos son la referencia
@kookee/sdk incluye declaraciones de TypeScript. Instala el paquete y la referencia queda en disco, en el contexto del asistente, en una forma que no puede recordar mal:
npm install @kookee/sdkAhora el prompt es corto, porque la precisión está en los tipos y no en el prompt:
Crea un blog con el paquete
@kookee/sdk, que ya está instalado. Una página de listado (/blog) con filtro por etiquetas, búsqueda y paginación, y una página de detalle (/blog/:slug) con el contenido HTML renderizado y reacciones con emoji. Next.js App Router, con la carga de datos en server components. Lee la clave deprocess.env.KOOKEE_API_KEY.
El asistente escribe kookee.blog.list({ page, limit, tags, search, locale }) porque esa es la firma, no porque haya recordado un párrafo. Y cuando cambio un método, las declaraciones cambian en la misma versión: no hay un segundo artefacto que se me pueda olvidar actualizar. Ese era el verdadero argumento contra el archivo de texto: podía estar equivocado, y una referencia que puede estar equivocada es peor que no tener ninguna, porque la gente se fía de ella.
La forma de la respuesta con la que trabaja es la misma que recibes tú:
const response = await kookee.blog.list({ page: 1, limit: 10, tags: ['engineering'] });
response.data; // BlogEntryListItem[]
response.total; // 25
response.totalPages; // 3Si prefieres usar páginas ya hechas en lugar de generarlas, @kookee/react incluye componentes de blog renderizados en el servidor: consulta Crear un blog con los componentes de React.
El contenido es la otra mitad
Los tipos le dicen al asistente qué puede llamar. No dicen nada de lo que hay en tu proyecto, y la mitad de los errores de una primera integración salen de ese hueco: un slug de categoría que no existe, un campo que el código nunca lee, una página vacía que resulta ser un proyecto vacío.
Así que conecta el asistente a tu contenido real:
claude mcp add --transport http kookee https://api.kookee.dev/api/mcp \
--header "Authorization: Bearer $KOOKEE_MCP_TOKEN"Ahora el prompt cambia de naturaleza. «Crea una página de registro de cambios» se convierte en:
Lee mis entradas del registro de cambios y luego crea una página que las muestre tal como están estructuradas en realidad.
Y las lee de verdad. Descubre que el tipo de lanzamiento está en un array fields y no en la propia entrada, que dos entradas no tienen versión, que tus categorías siguen un criterio de nombres y tus etiquetas otro. La página que escribe se ajusta a tus datos y no a un ejemplo genérico. Y como también puede escribir, lo primero que vea que falta lo puede corregir.
Lo que sigue haciendo falta
Un proyecto de Kookee con al menos una entrada publicada. Un proyecto vacío da una página vacía, y eso cuesta distinguirlo de un error.
Una clave de API de Conexiones → Claves de API para la aplicación. Solo accede al contenido publicado, así que puede ir sin riesgo en el bundle del cliente.
Un token MCP personal de Conexiones → Servidor MCP, si quieres que el asistente lea tu contenido real. Para eso basta con Solo lectura. Aun así, no lo pongas en tu código: lee tus borradores.
Más allá del blog
La misma fórmula sirve para cada sección:
Crea un centro de ayuda con navegación por categorías, búsqueda semántica y páginas de artículos.
Crea una página de registro de cambios agrupada por tipo de lanzamiento, con reacciones con emoji.
Créalas de una en una. Las tres a la vez producen un diff que nadie revisa con cuidado, y así es como llega a producción un bug que parecía correcto.
La idea de fondo: deja de pedirle al asistente que recuerde tu API y dale algo que no se pueda recordar mal. Los tipos y los propios datos.