heroui-v2-mcp

MCP (Model Context Protocol) Server für HeroUI v2 (https://v2.heroui.com) Komponentendokumentation, Quelcode, Stildefinitionen und Theme-Tokens.

Im gegenstaz zum offiziellen @heroui/react-mcp – das auf HeroUI v3 abzielt und einen bereitgestellten Cloudflare Worker, einen R2-Bucket und ein PostHog-Projekt benötigt – handelt es sich um einen eigenständigen lokalen Server: Er ruft alles bei Bedarf direkt von heroui-inc/heroui@main (dem Branch, der v2.x verfolgt) und raw.githubusercontent.com ab und speichert die Ergebnisse für die Lebensdauer des Prozesses zwischen. Es ist kein Cloud-Konto, keine API-Bereitstellung oder Extraktionspipeline erforderlich.

Warum ein separates Projekt

HeroUI v3 (Branch v3, Seite heroui.com) und v2 (Branch main, Seite v2.heroui.com) sind unterschiedliche, inkompatible Komponentenmodelle – unterschiedliches Paketlayout, kein llms.txt auf der v2-Seite, andere Dokumentationsordnerstrultur (/docs/komponenten/* vs /docs/react/*), anderer Styling-Ansatz (Tailwind-Variants-Dateien unter packages/core/theme/src/komponenten vs. was auch immer v3 verwendet). Der offizielle MCP lehnt es explizit ab, v2-Dokumente zu liefern, daher spiegelt dieses Projekt seine Werkzeugoberfläche wider, zeigt aber auf die v2-Datenquellen.

Related MCP server: UI Toolkit MCP Server

Werkzeuge

Installieren & Ausführen

Das Paket ist auf npm als heroui-v2-mcp veröffentlicht, daher ist kein Klon- oder Build-Schritt erforderlich, um es zu verwenden.

Verwendung mit Claude Code / Claude Desktop / Cursor

Fügen Sie es zu Ihrer MCP-Konfiguration hinzu — npx lädt es bei Bedarf herunter und führt es aus:

{
  "mcpServers": {
    "heroui-v2": {
      "command": "npx",
      "args": ["-y", "heroui-v2-mcp"]
    }
  }
}

Oder installieren Sie es global und verweisen Sie direkt auf die Binärdatei:

npm install -g heroui-v2-mcp

{
  "mcpServers": {
    "heroui-v2": {
      "command": "heroui-v2-mcp"
    }
  }
}

Lokale Entwicklung (aus dem Quelcode)

npm install
npm run dev         # tsx --watch, runs src/server.ts directly (no build step)
npm run inspect      # launches @modelcontextprotocol/inspector against src/server.ts
npm run build        # emits dist/server.js

GitHub-Ratenbegrenzungen

Verzeichnislistungen erfolgen über die GitHub REST API, die ohne Authentifizierung auf 60 Anforderungen/Stunde begrenzt ist. Dateiinhalte (raw.githubusercontent.com) unterliegen dieser Begrenzung nicht. Wenn Sie beim Durchsuchen vieler Komponenten auf 403-Fehler stoßen, setzen Sie ein Token:

export GITHUB_TOKEN=ghp_xxx   # no scopes needed, just raises the rate limit to 5000/hr

Wie Daten aufgelöst werden

• Komponentenliste = Dateien unter apps/docs/content/docs/komponenten/*.mdx im main-Branch.

• Die meisten Dok-Slugs bilden 1:1 auf ein packages/komponenten/<slug>-Paket ab. Einige wenige Dok-Seiten beschreiben Unterkomponenten, die in einem anderen Paket gebündelt sind (z.B. textarea wird in @heroui/input mitgeliefert, checkbox-group in @heroui/checkbox) – siehe KOMPONENTEN_PACKAGE_ALIASES in src/constants.ts.

• Props/API-Tabellen werden aus dem JSX-Literal <APITable data={[...]} /> jeder .mdx-Dok-Seite analisiert (dieses Array wird als JS-Literal ausgewertet – es handelt sich um statische Daten aus dem offiziellen Repo, nicht um willkürliche/ungeprüfte Eingaben).

• Theme-Tokens stammen aus packages/core/theme/src/colors/{semantic,common}.ts und default-layout.ts.

Zwischenspeicherung

Jede GitHub-Antwort (Dateiinhalte oder Verzeichnislistungen) wird für 30 Minuten im Arbeitsspeicher zwischengespeichert (CACHE_TTL_MS in src/constants.ts). Starten Sie den Prozess neu, um früher eine Aktualisierung zu erzwingen.