nakkas

nakkaş bedeutet auf Türkisch (alt) Maler/Künstler.

"make a neon terminal logo with animated binary digits"
  → AI constructs JSON config
  → nakkas renders to animated SVG
  → clean animated SVG output

Warum

• Ein Werkzeug, unendliche Designs. render_svg akzeptiert eine JSON-Konfiguration. Die KI füllt alles aus.

• KI-natives Schema. Jedes Feld hat .describe()-Annotationen, damit das Modell weiß, was zu tun ist.

• Reines deklaratives SVG. CSS @keyframes + SMIL-Animationen, kein JavaScript.

• Keine externen Abhängigkeiten. Keine Cloud-API, keine API-Schlüssel. Läuft lokal.

Installation

Claude Desktop

Fügen Sie dies Ihrer Konfigurationsdatei hinzu:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nakkas": {
      "command": "npx",
      "args": ["-y", "nakkas@latest"]
    }
  }
}

Claude Code (CLI)

claude mcp add nakkas npx nakkas@latest

Cursor / Zed / Andere MCP-Clients

{
  "mcpServers": {
    "nakkas": {
      "command": "npx",
      "args": ["-y", "nakkas@latest"]
    }
  }
}

Lokale Entwicklung

git clone https://github.com/arikusi/nakkas
cd nakkas
npm install && npm run build
# Use dist/index.js as the command

Schnellstart

Fragen Sie Ihre KI (mit verbundenem Nakkas):

"Erstelle ein animiertes SVG: dunkler Terminal-Rahmen (800×200), leuchtend cyanfarbener Text 'NAKKAS', Neon-Glow-Filter, Einblenden beim Laden."

"Erstelle einen Lade-Spinner: einen Kreis mit einer Zeichen-Animation für den Pfad, die alle 1,5 Sekunden wiederholt wird."

"Datenvisualisierung: animiertes Balkendiagramm, 5 Balken, jeder mit einer gestaffelten Verzögerung eingeblendet, Farbverläufe."

"Profil-Badge (400×120): Blau-zu-Lila-Verlauf, weißer Benutzername, Schlagschatten, dezente Puls-Animation."

Werkzeuge

Nakkas bietet drei Werkzeuge:

Der beabsichtigte Arbeitsablauf: Rendern → Vorschau → Iterieren → Speichern. Das save-Werkzeug ist von render_svg getrennt, um das Vorschauen und Verfeinern vor dem Speichern zu fördern.

Das save-Werkzeug

{ "content": "<svg ...>...</svg>", "outputPath": "./design.svg", "format": "auto" }

Formate: auto (wird aus der Endung abgeleitet), svg (Textdatei), png (rendert zuerst zu Raster). Wenn die Datei existiert, wird ein numerischer Zähler angehängt, um ein Überschreiben zu verhindern. Der tatsächliche Speicherpfad wird zurückgegeben.

Das render_svg-Werkzeug

Eingabe: SVGConfig JSON-Objekt Ausgabe: Vollständiger SVG-XML-String plus optionale Designanalyse-Notizen

Nach dem Rendern kann die Antwort Designwarnungen zu häufigen Problemen enthalten, wie z. B. zu viele gleichzeitige Animationen, fehlende transformBox oder Skalierungstransformationen auf Gruppenebene.

SVGConfig-Struktur

{
  canvas: {
    width: number | string,   // e.g. 800 or "100%"
    height: number | string,
    viewBox?: string,          // "0 0 800 400"
    background?: string        // hex "#111111" or "transparent"
  },

  defs?: {
    gradients?: Gradient[],   // linearGradient | radialGradient
    filters?: Filter[],        // preset or raw primitives
    clipPaths?: ClipPath[],
    masks?: Mask[],
    symbols?: Symbol[],
    paths?: { id, d }[]       // for textPath elements
  },

  elements: Element[],         // shapes, text, groups, use instances

  animations?: CSSAnimation[]  // CSS @keyframes definitions
}

Elementtypen

Alle visuellen Elemente (Gemeinsame Felder)

{
  id?: string,             // required for filter/gradient/clip references
  cssClass?: string,       // matches CSS animation names
  fill?: string,           // "#rrggbb" | "none" | "url(#gradId)"
  stroke?: string,
  strokeWidth?: number,
  strokeDasharray?: string, // "10 5", use for draw-on animation
  strokeDashoffset?: number,
  opacity?: number,        // 0–1
  filter?: string,         // "url(#filterId)"
  clipPath?: string,       // "url(#clipId)"
  transform?: string,      // "rotate(45)" "translate(100, 50)"
  transformBox?: "fill-box" | "view-box" | "stroke-box",  // set "fill-box" for CSS rotation
  transformOrigin?: string, // "center", works with fill-box
  smilAnimations?: SMILAnimation[]
}

Filter-Presets

Referenzieren Sie als filter: "url(#myId)" auf jedem Element, nachdem Sie es in defs.filters definiert haben:

{ "type": "preset", "id": "myGlow", "preset": "glow", "stdDeviation": 8, "color": "#ff00ff" }

CSS-Animationen

{
  "animations": [{
    "name": "pulse",
    "duration": "2s",
    "iterationCount": "infinite",
    "direction": "alternate",
    "keyframes": [
      { "offset": "from", "properties": { "opacity": "0.3", "transform": "scale(0.9)" } },
      { "offset": "to",   "properties": { "opacity": "1",   "transform": "scale(1.1)" } }
    ]
  }],
  "elements": [{
    "type": "circle",
    "cx": 100, "cy": 100, "r": 40,
    "cssClass": "pulse",
    "transformBox": "fill-box",
    "transformOrigin": "center"
  }]
}

CSS-Eigenschaftsschlüssel: camelCase (strokeDashoffset) oder kebab-case (stroke-dashoffset). Beides funktioniert.

Animierbare CSS-Eigenschaften: opacity, fill, stroke, transform, filter, clip-path, stroke-dasharray, stroke-dashoffset, font-size, letter-spacing und mehr.

SMIL-Animationen

Drei SMIL-Typen, inline definiert auf jedem Element via smilAnimations: []:

{ "kind": "animate",          "attributeName": "d",       "from": "...", "to": "...", "dur": "2s" }
{ "kind": "animateTransform", "type": "rotate",            "from": "0 100 100", "to": "360 100 100", "dur": "3s" }
{ "kind": "animateMotion",    "path": "M 0 0 C ...",      "dur": "4s", "rotate": "auto" }

Pfad-Morphing (attributeName: "d"): Von/Zu-Pfade müssen identische Befehlstypen und Anzahlen haben. Nur Koordinaten können variieren.

Schriftarten

Systemschriftarten funktionieren überall ohne Laden: Arial, Helvetica, Courier New, Georgia, Verdana, monospace, sans-serif, serif.

Benutzerdefinierte Schriftfamilien werden ebenfalls akzeptiert. Sie funktionieren, wenn die Schriftart in der Rendering-Umgebung verfügbar ist (Webseite mit geladenen Schriftarten, Design-Tool usw.).

Anwendungsfälle & Kompatibilität

Fehlerbehebung

"MCP error -32602: Input validation error"

Dies bedeutet, dass das MCP-SDK die Eingabe abgelehnt hat, bevor sie den Handler erreichte. Es passiert normalerweise beim ersten Versuch und funktioniert beim erneuten Versuch. Die häufigsten Auslöser:

• Tippfehler beim Verlaufstyp. Verwenden Sie "linearGradient" oder "radialGradient", nicht "linear" oder "radial". Dies ist der häufigste Fehler.

• Keyframe-Offset als String. Schreiben Sie 0 oder 100 (Zahlen) oder "from" / "to". Das Schreiben von "0%" oder "100%" führt zu einem Fehler.

• Benannte Farben. Nur Hex-Werte funktionieren: "#ff0000", nicht "red". Auch kein rgb().

• Fehlender type bei Elementen. Jedes Elementobjekt benötigt ein type-Feld.

Wenn Sie eine MCP-Client-Integration erstellen und dies konsistent sehen, liegt das Problem wahrscheinlich an der Art und Weise, wie Ihr Client Argumente serialisiert. Siehe anthropics/claude-code#29104 für Kontext zu bekannten Serialisierungs-Eigenheiten.

Vorschau zeigt ein leeres oder unerwartetes Bild

Das Vorschau-Tool rendert einen statischen Schnappschuss bei t=0. Animationen werden nicht erfasst. Was Sie sehen, ist der Anfangszustand des SVGs, bevor eine CSS- oder SMIL-Animation beginnt.

Wenn das Bild komplett leer ist:

• Überprüfen Sie, ob Ihre Elemente fill oder stroke gesetzt haben. Eine Form ohne Füllung auf einer transparenten Leinwand ist unsichtbar.

• Überprüfen Sie die Koordinaten. Ein Element bei x: 2000 auf einer 800px breiten Leinwand ist einfach außerhalb des Bildschirms.

• Wenn Sie filter: "url(#myFilter)" verwenden, stellen Sie sicher, dass myFilter tatsächlich in defs.filters definiert ist.

Animationen funktionieren nicht auf GitHub

GitHub READMEs rendern SVG über <img>-Tags, die JavaScript entfernen, aber CSS und SMIL beibehalten. Wenn Ihre Animation lokal funktioniert, aber nicht auf GitHub:

• Vermeiden Sie <script> oder Event-Handler (onclick, onmouseover). Diese werden entfernt.

• Externe Schriftarten werden nicht geladen. Bleiben Sie bei Systemschriftarten: Arial, Courier New, Georgia, monospace, sans-serif.

• CSS @import für Schriftarten ist blockiert. Wenn Sie eine bestimmte Schriftart benötigen, verwenden Sie inline <text> mit einem System-Fallback.

Große SVG-Ausgabe

Wenn render_svg eine Warnung zur Dateigröße (über 50kb) zurückgibt, erzeugen die parametrischen Kurven oder Mustergruppen wahrscheinlich zu viele Elemente. Reduzieren Sie steps bei parametrischen Kurven oder count bei Mustergruppen. Eine grid-group mit cols: 50, rows: 50 erzeugt 2500 Elemente, was sich schnell summiert.

Tech-Stack

• TypeScript + Node.js 18+

• @modelcontextprotocol/sdk (MCP-Server)

• zod