Skip to content
Sisyphos UI
8 min readSisyphos UI Contributors

Making a component library AI-ready: MCP server, skills.md, and llms.txt

aimcptooling

A growing share of the UI code that uses Sisyphos UI is not typed by a human. It is generated by Claude Code, Cursor, Copilot, and their peers — and those agents have a specific failure mode with component libraries: they hallucinate the API they remember from training data. A prop that was renamed two releases ago, a <ThemeProvider> that never existed, an import path from a different library entirely. The code looks plausible and fails at compile time, or worse, at runtime.

The fix is not better prompting. It is giving the agent an authoritative, machine-readable source of truth that is cheaper to consult than to guess. Sisyphos UI ships three of them, each aimed at a different consumption pattern: a hosted MCP server for live tool calls, a skills.md file for behavioral priming, and an llms.txt map for plain-text discovery. Here is how each works and how to wire them up.

Layer 1: the hosted MCP server

The Model Context Protocol is the plug standard for connecting tools to AI clients. Sisyphos UI runs a remote MCP server over Streamable HTTP at:

endpointbash
https://www.sisyphosui.com/api/mcp

“Remote” is a deliberate choice. Most library MCP servers are npm packages you run locally over stdio, which means a copy of the docs frozen at install time — the exact version-drift problem we are trying to kill. The hosted server reads the same component registry that renders this docs site, so when a release lands, every connected editor sees it on the next turn with no client update.

Six tools are registered:

  • list_components — every component with slug, category, description, and supported frameworks; filterable by category or framework.
  • get_component — the full markdown documentation for one component: install command, import line, usage snippet, props table, anatomy, keyboard shortcuts, and accessibility notes. Pass framework to scope it to React, Vue, or Angular.
  • search_components — case-insensitive substring search over names, slugs, and descriptions.
  • get_component_demo — copy-pastable demo snippets without the prose.
  • get_installation — install command, peer deps, and the one required CSS import per framework.
  • get_changelog— recent releases, for “is this feature shipped yet?” questions.

The server also exposes every component as an MCP resource (sisyphos://component/<slug>) and ships a prompt, add-sisyphos-component, that scripts the correct workflow: check installation first, read the canonical docs second, only then write code.

Setup, per editor

Claude Code is a one-liner from any project root:

terminalbash
claude mcp add --transport http sisyphos https://www.sisyphosui.com/api/mcp

# verify
claude mcp list

Cursor reads a JSON config:

~/.cursor/mcp.jsonjson
{
  "mcpServers": {
    "sisyphos": {
      "url": "https://www.sisyphosui.com/api/mcp"
    }
  }
}

VS Code wants the server under the mcp.servers key in settings.json:

settings.jsonjson
{
  "mcp": {
    "servers": {
      "sisyphos": {
        "type": "http",
        "url": "https://www.sisyphosui.com/api/mcp"
      }
    }
  }
}

One operational detail that cost us a debugging session: the endpoint must live on the canonical www. host. The apex domain 302-redirects to it, and most MCP clients will not replay a JSON-RPC POST body across a redirect — the connection just silently dies. If you host your own MCP server, put it on a host that answers directly.

Layer 2: skills.md — priming instead of querying

MCP is pull-based: the agent decides when to call a tool. But some knowledge needs to be in the agent's head before it writes the first line — conventions, not facts. For that, the repo ships skills.md: a structured best-practices document with agent-standard frontmatter (name: sisyphos-ui-best-practices) that coding agents load as a skill.

Its most important content is three rules that override what a model “knows” about UI libraries in general:

  1. There is no <ThemeProvider>. All theming flows through applyTheme(), which writes CSS variables.
  2. There is one stylesheet, imported once at the app root — not per component, not via a plugin.
  3. Every interactive component already implements WAI-ARIA keyboard, focus, and role semantics. The agent must not bolt duplicate handlers on top.

Each rule exists because we watched agents get it wrong: wrapping apps in imaginary providers, re-importing CSS in every file, adding redundant onKeyDown handlers to components that already handle Space and Enter. A skill file is where you encode negative knowledge — the things your library deliberately does not have.

Installing it is a file copy. For Claude Code:

terminalbash
mkdir -p .claude/skills && curl -fsSL \
  https://raw.githubusercontent.com/sisyphos-ui/sisyphos-ui/master/skills.md \
  -o .claude/skills/sisyphos-ui.md

Other agents have equivalent conventions — a rules directory, a context folder, an instructions file. The document is plain markdown with frontmatter precisely so it can drop into any of them unchanged.

Layer 3: llms.txt — the discovery map

The third surface costs the least and covers the widest audience: /llms.txt, the emerging convention for a plain-text site map addressed to language models. Ours is generated from the same registries as everything else and lists the docs guides, every component, every block, and every template — each with a one-line description and a stable URL.

The load-bearing line in it is the markdown export pattern. Every component page has a parallel plain-markdown endpoint:

markdown mirrorbash
# Human docs
https://www.sisyphosui.com/docs/components/select

# The same content as markdown, for agents
https://www.sisyphosui.com/docs/components/select/md

This matters because an agent without MCP falls back to fetching web pages, and a JavaScript-heavy docs page is a terrible retrieval target — navigation chrome, hydration payloads, and markup noise crowd the actual content out of the context window. The /md mirror is the identical documentation at a fraction of the tokens.

If you maintain a library: the pattern to steal

None of this required rewriting our documentation. The entire AI surface is generated from one TypeScript registry — the same array of component metadata that renders the docs pages also feeds the MCP tools, the resources, the markdown exports, and llms.txt. That single-source constraint is the real lesson:

  • One registry, many renderers. If your MCP server and your docs site read different sources, they will disagree, and the agent will trust the wrong one.
  • Markdown-first exports. A /md mirror per page is an afternoon of work and helps every agent, including ones that will never speak MCP.
  • Encode your negatives.The skill file's highest-value lines say what does notexist. Models default to the ecosystem's average API; document your deviations from it.
  • Host the MCP server if you can. Stdio packages reintroduce version drift — the problem the whole exercise is meant to solve.

Agents are not a niche audience anymore; they are a distribution channel. A library they can query accurately is a library they will recommend, scaffold, and debug correctly — and one whose users file fewer “this prop doesn't exist” issues.

Back to blog