Pine MCP: A Case Study

Pine MCP is a server that lets AI coding tools read Pine, Kajabi’s design system. Instead of guessing at components, an agent can look up the real ones, get Pine’s rules before it starts and check what it wrote against them.

I started it in June 2025 and co-maintain it with a teammate. The biggest surprise? AI agents are a new kind of design system user with limits of their own, and most of the hard problems turned out to be documentation problems.

The problem

If you’ve pointed an AI coding tool at a design system, you’ve probably seen this. In 2025, the tools writing UI for Kajabi kept inventing Pine components and props that didn’t exist. The code looked right. It wasn’t. Pine’s docs were written for people, as pages you browse, and an agent can’t query those reliably. So it filled the gaps with whatever was most common on the public web.

MCP (Model Context Protocol) is a standard way for AI tools to call outside services. We looked at other options first. Rules pasted into each tool’s prompt drift out of date. An instructions file in the repo helps, and we kept one, but it can’t answer questions. A custom API would have worked for nobody until every tool learned to call it. MCP won because the tools already speak it, which made it an easy call. (For Pine itself, see the Pine case study.)

How it works

At build time the server reads from three sources: Pine’s repo for component source, docs and page patterns, plus the design tokens and the icon catalog. A data build fetches everything, checks that nothing is partial or empty and writes a static snapshot. The server is one stateless endpoint, and every tool answers from that snapshot.

Under the hood it’s a small Next.js app, with the official MCP SDK handling the protocol itself. That leaves almost all of our own code about Pine: what to return, in what order and how much.

Fixing the data at deploy time keeps answers fast and predictable, and an outage upstream can’t break a request. The cost is freshness, so a scheduled check compares the snapshot with Pine and flags drift. The tools fall into three groups:

The callers are AI coding tools like Claude Code, Cursor, Windsurf, VS Code and ChatGPT, a hook in the product repo that checks Pine markup after each AI edit, and design review agents on pull requests.

Agents read through a keyhole

In early 2026, Claude Code, Cursor and Windsurf started failing on some calls. The responses were too big for them to take in. My note on the fix didn’t sugarcoat it: “the verbose defaults were the problem.”

So every response got a size budget. The most important part of each answer comes first, so a component’s API is never the part that gets cut. Agents can ask for specific sections, fewer examples or the next page, and when an answer hits its budget, it says how to get the rest.

Honestly, this was a documentation problem the whole time. What does a short description of a table component need to say first? Budgets also need tending. When we later put every code example back into component responses, some grew again, and I still think that was the right call.

Names are fuzzy

Agents ask for btn, radiogroup, pds-button or Button, and all of them should land on the right component. The obvious tool is edit distance, the number of single-letter changes between two words. By that measure, though, btn is closer to box than to button. Oops.

So lookup works in order: a short list of known aliases, then an exact match that ignores the pds- prefix, then a partial match, then edit distance with tight limits that only accepts one clear winner. If nothing wins, the agent gets “did you mean” suggestions. I’ll take a question over a confident wrong answer every time.

Healthy and serving nothing

In spring 2026, a credential problem meant the data build couldn’t read its sources. The deploy still succeeded and shipped empty data. In my own words at the time, the server was “healthy” and serving nothing. Not a great look for a tool whose whole job is accurate answers.

Now the build fails closed. It refuses to ship a partial component set or empty data, never deletes good data before new data arrives and leaves the last good version live when anything fails. The same work added the server’s first automated tests. They run without network access, so upstream Pine changes can’t break them, and I broke the code on purpose to prove they’d catch it. Now hundreds of tests run on every pull request.

My contributions

I started Pine MCP and co-maintain it with a teammate. They built the tools that check generated code and guide agents before they write, along with the logging that shows how the server gets used. We made most of the big calls together. These are the parts where I’ve had the biggest hand.

First versions

Built the first version in June 2025, six tools in one serverless function, then rebuilt it a week later as the Next.js app it still is.

Lookup

Token and icon lookup, plus the forgiving name matching that sends near-miss names to the right component, or asks.

Response budgets

Size budgets on every response, the most important part first, and ways for agents to ask for more or less.

Data build

The build that fails closed, so partial or empty data never ships and the last good version always stays live.

Tests and CI

The server’s first automated tests and CI, run offline on every pull request and proven by breaking code on purpose.

Security and upkeep

Patching a published SDK vulnerability, moving to MCP SDK version 2 and refactoring with output unchanged.

Pine MCP’s page in the Pine docs, next to the components it serves.

Outcomes

What I learned