Kookeebeta
Back to Getting Started

Getting Started

Building with an AI coding assistant

Updated 109 views

Assistants are good at the shape of an integration and bad at its details. They will lay out a listing page and a detail page correctly and then invent a method that does not exist, unwrap an envelope that is not there, or read a field off a list item that never includes one. Every one of those is a debugging session you did not need.

The fix is context. There are two kinds worth giving.

Give it the types

@kookee/sdk ships TypeScript declarations, and an assistant working in your repository reads them. This is the highest-value thing you can do and it costs one install:

Bash 
npm install @kookee/sdk

Now kookee.blog.list( autocompletes, the parameter names are real, and a hallucinated method is a type error rather than a runtime surprise. Ask for TypeScript even in a JavaScript project — the assistant checks itself against the declarations.

Connect it to your content

Add the MCP server and the assistant can read your actual entries — the real slugs, the real categories, the real shape of your data — instead of writing against an imagined project. In Claude Code, run:

Bash 
claude mcp add --transport http kookee https://api.kookee.dev/api/mcp

Then run /mcp, pick kookee and sign in to Kookee in the browser tab it opens. Read only is enough to read. Cursor connects with a personal token from Connect → MCP server instead.

This changes what you can ask for. "Build a changelog page" becomes "read my changelog entries and build a page that renders them", and the difference shows up in the details: it knows your entries carry a changelogType field, because it looked. The MCP article covers the setup.

The prompt

Paste something like this:

Build a blog with the @kookee/sdk package, which is already installed. A listing page (/blog) with tag filtering, search and pagination, and a detail page (/blog/:slug) with rendered HTML content and emoji reactions. Next.js App Router, fetching in server components. Read the key from process.env.KOOKEE_API_KEY. Handle KookeeApiError — a 404 renders not-found.

The last two sentences matter more than they look. Without them assistants hardcode keys and let 404s throw in production.

Or start from the components

In a React app, ask for the ready-made components instead of hand-written markup. The assistant writes far less code, so there is far less for it to get wrong:

Build a blog with the @kookee/react components, which are already installed: BlogTagFilter, BlogPostList and Pagination on /blog, and BlogPost with TrackedTableOfContents and Reactions on /blog/[slug]. Next.js App Router: fetch with @kookee/sdk in server components and pass the data as props. Import server components from @kookee/react/blog and @kookee/react/entry, and the interactive ones from @kookee/react/entry/client.

The component articles, starting with React components for your blog, changelog and help center, are worth pointing the assistant at as well.

Before you start

  1. A Kookee project with at least one published entry. An empty project produces an empty page, which is hard to distinguish from a bug.

  2. An API key from Connect → API keys for the application itself. This is not your MCP token.

  3. @kookee/sdk installed, so the types are on disk.

Other surfaces

The same shape works for each module:

Build a help center with category navigation, semantic search and article pages.

Build a changelog page grouped by release type, with emoji reactions.

Build a public roadmap that groups feedback posts by board column.

Build one at a time. All three at once produces a large diff nobody reviews carefully.

Review the result

Assistants get the details wrong in predictable places. Worth checking every time:

  • Is contentHtml read from a single-entry fetch? List items never include it.

  • Is the API key read from an environment variable rather than hardcoded?

  • Are search inputs debounced, or firing a request per keystroke?

  • Is the code block stylesheet imported (@kookee/sdk/styles/content.css), and does the element holding contentHtml carry the kookee-entry-content class it is scoped to? EntryContent adds it.

  • Do 404s render a not-found page rather than throwing?

  • With the React components: are server components imported from @kookee/react/<area> paths rather than the package root, and do the /client components get only ids, counts and headings, never a whole entry?

  • Are structured fields read with the field helpers — fieldOptionKey(entry.fields, 'changelogType') — rather than a property that does not exist on the entry?

That last one is the current favourite mistake. A changelog entry's release type lives in its fields array, and entry.type is the string 'changelog', which is not what an assistant expects.

Each of these is covered in the articles on rendering content, API keys, and rate limits.

Was this article helpful?