@tecof/mcp

Stdio-MCP-Server für die Tecof Developer API v1. Läuft innerhalb eines Tecof-Theme-Repositorys; liest die Theme-Komponenten von der Festplatte (AST), übersetzt die einfachen „Abschnittsdefinitionen" des Agenten in ein Editor-Dokument und erstellt/aktualisiert Entwurfsseiten über die Developer API. Die Veröffentlichung erfolgt immer über das Panel (es gibt kein Publish in der API).

• SDK: @modelcontextprotocol/server@^2 (+ zod@^4) — McpServer + serveStdio

• Node ≥ 20, ESM

• Tool-Annotationen (readOnlyHint, destructiveHint) und _meta["anthropic/requiresUserInteraction"] (Löschen) werden unterstützt

Installation

Im Stammverzeichnis des Theme-Repositorys:

# 1) Panelden API anahtarı üretin: Ayarlar → Geliştirici / API Anahtarları (scope: pages:read, pages:write)
# 2) .env (gitignore'da) içine yazın
echo 'TECOF_API_TOKEN=tcf_...' >> .env

Der Server läuft über npx; eine globale Installation ist nicht erforderlich:

npx -y @tecof/mcp@latest

Umgebungsvariablen

TECOF_PROJECT_DIR → CLAUDE_PROJECT_DIR → process.cwd() – in dieser Reihenfolge wird das Projektverzeichnis ermittelt; .env und .env.local werden von dort gelesen. process.env wird nicht überschrieben – Dateiwerte füllen nur leere Schlüssel (.env.local > .env).

Bei fehlendem Token/URL startet der Server trotzdem; list_components und validate_document funktionieren, Seiten-Tools geben einen Hinweisfehler zurück. Logs werden nur auf stderr geschrieben; auch unbehandelte Fehler landen auf stderr, der Prozess stürzt nicht ab.

Sicherheit: TECOF_API_URL muss https sein. Wird eine http://-Adresse (außer Loopback) angegeben, wird beim Start eine stderr-Warnung ausgegeben und jedem Tool-Fehler derselbe Hinweis angehängt; http→https-Weiterleitungen werden nicht verfolgt (Node fetch entfernt bei Weiterleitungen den Authorization-Header, was zu irreführenden 401 führt) – eine 3xx-Antwort wird in den Fehler „TECOF_API_URL-Schema/-Host falsch" umgewandelt. Das Request-Timeout (30 s) umfasst Header- und Body-Lesen vollständig.

Claude Code — .mcp.json

{
  "mcpServers": {
    "tecof": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "${TECOF_MCP_PACKAGE:-@tecof/mcp@latest}"]
    }
  }
}

Die Env-Variable TECOF_MCP_PACKAGE überschreibt die Paket-Spezifikation – vor der Veröffentlichung auf npm oder für die lokale Entwicklung diesen Repo-Ordner angeben (npx -y /pfad/zu/tecof-mcp führt das bin im Ordner aus):

export TECOF_MCP_PACKAGE=/Users/<siz>/Desktop/Tecof/tecof-mcp   # claude'u bu shell'den başlatın

Veröffentlichung (npm)

npm run build && npm test && node scripts/smoke.mjs
npm version patch            # ya da minor
npm publish --access public  # @tecof kapsamı — tecof-theme-editor/analytics ile aynı hesap

Codex — .codex/config.toml

[mcp_servers.tecof]
command = "npx"
args = ["-y", "@tecof/mcp@latest"]

Gemini CLI — .gemini/settings.json

{
  "mcpServers": {
    "tecof": {
      "command": "npx",
      "args": ["-y", "@tecof/mcp@latest"]
    }
  }
}

Das Token wird in keiner Konfigurationsdatei gespeichert; es bleibt in .env. Der Client-Prozess startet im Stammverzeichnis des Theme-Repositorys, der Server liest die .env von dort.

Related MCP server: anticms-mcp

Tools

Ergebnisse werden als content[0].text (JSON) + structuredContent zurückgegeben; Fehler enthalten isError: true mit Feld-/Pfadinformationen (damit der Agent sie korrigieren kann).

update_page-Operationen

append_section{section} (vor dem Footer), insert_section{section, before?|after?} (ohne Anker wie append vor dem Footer), replace_section{id, section}, remove_section{id}, move_section{id, before?|after?}, set_props{id, props} (flaches Zusammenführen), set_slot{id, slot, children} (ersetzt den Slot vollständig; neue Kinder werden zuerst erstellt, bei Fehlern bleibt der alte Inhalt erhalten), set_root_props{props}.

Verhaltenshinweise:

• Gemeinsame Komponenten sind schreibgeschützt – einschließlich ihrer untergeordneten Knoten. Ein Knoten mit sharedComponentId (Header/Footer) und alle seine Nachkommen unter dessen Zonen (Logo, NavLink, FooterColumn …) können nicht über set_props/set_slot/replace_section/remove_section geändert werden; es wird der Fehler „gemeinsame Komponente – bitte im Panel-Editor bearbeiten" zurückgegeben. Die gemeinsame Wurzel selbst kann mit remove_section von der Seite entfernt werden (mit Warnung; die Master-Vorlage bleibt unberührt). In der get_page-Gliederung sind diese Knoten mit shared: true markiert.

• Fehler-/Warnungsunterscheidung (Operationsmodus): Das vom GET stammende Dokument wird zuerst normalisiert (in props verbliebene Inline-Slot-Arrays → Zonen; SharedComponentRef-Knoten mit gelöschtem Master werden mit Warnung verworfen – das Backend macht beim PUT dasselbe). Knoten, die der Agent in dieser Runde hinzugefügt/geändert hat, werden streng geprüft (unbekannter Typ, Allow-Verletzung, Element-at-Root → Fehler); Verstöße in bereits vorhandenen, unveränderten Knoten sind nur Warnungen – eine unabhängige Aktualisierung wird nicht blockiert, nur weil sich das Theme geändert hat. Im document-Modus sowie bei create_page/validate_document werden alle Knoten streng geprüft.

• Leere operations: [] (auch ohne Meta) → Fehler „keine Operationen anzuwenden"; es wird kein PUT gesendet. Wird nur meta angegeben, wird draftData nicht gesendet (Status wechselt nicht von published→changed, es wird keine unnötige Revision erstellt); das Feld savedDraft in der Antwort zeigt dies an.

• Backend-Speicherwarnungen (warnings: [{code,path,message}] im Antwortstamm, z. B. Verwerfen einer Header-Verknüpfung mit gelöschtem Master) werden in der create_page/update_page-Antwort als server: [code] path: message-Zeilen zurückgegeben.

Autorenformat

Der Agent schreibt keinen Dokument-JSON, sondern einen Abschnittsbaum; ID-Erzeugung, defaultProps-Zusammenführung, Slot→Zone-Konvertierung und Mehrsprachigkeits-Kurzbefehle werden serverseitig durchgeführt.

{
  "type": "FeaturesSection",
  "props": { "columns": "3", "background": "dark" },
  "variant": "dark",                       // bileşenin variants anahtarı (varsa)
  "slots": {
    "contentSlot": [
      { "type": "Title", "props": { "text": { "tr": "Neden biz?", "en": "Why us?" }, "size": "lg" } }
    ],
    "itemsSlot": [
      { "type": "Card", "props": { "href": "/hakkimizda" },
        "slots": { "contentSlot": [ { "type": "Paragraph", "props": { "text": "<p>Hızlı teslimat</p>" } } ] } }
    ]
  }
}

Transformationsregeln:

1. Wenn type nicht im Katalog vorhanden ist, Fehler; element-Kategorie an der Wurzel ist ein Fehler; Slot-Kind außerhalb von allow ist ein Fehler.

2. props = defaultProps (−id, −Inline-Slot-Kinder) ← variants[variant].props (+_variant) ← Benutzer-props.

3. Wenn slots[slot] angegeben ist, wird es verwendet; andernfalls die Beispielkinder aus defaultProps; bei [] leer. Alle werden in zones["<id>:<slot>"] geschrieben, props[slot] = [].

4. Mehrsprachigkeits-Kurzbefehle: "text" → [{code: Standardsprache, value}]; {tr, en} → [{code,value}]; fehlende Sprache ist eine Warnung. link: "/pfad" → [{code, value:{url, target:"_self"}}]. upload: URL-String → externer Dateidatensatz.

5. Wenn der select/radio-Wert außerhalb von options liegt, Fehler. Schlüssel mit _-Präfix sind ein Fehler (className ist frei).

6. id: 8 Zeichen [A-Za-z0-9_-], dokumentweit eindeutig (eine gültige und eindeutige props.id wird akzeptiert).

Entwicklung

npm install
npm run build        # tsc → dist/ (+ dist/bin.js +x)
npm test             # vitest (parser, build, validate, operations, api mock, config, uçtan uca MCP)
node scripts/smoke.mjs   # dist/bin.js'i stdio ile ayağa kaldırıp initialize + tools/list doğrular

Tests senden keine Anfragen an echte Backends (fetch-Mock); der Themenkatalog wird aus den Kopierkomponenten unter test/fixtures/theme gelesen.

Programmatische Nutzung (HTTP-Transport usw.):

import { buildServer, ServerContext, loadConfig } from "@tecof/mcp";
const ctx = new ServerContext({ config: loadConfig() });
const server = buildServer({ ctx }); // McpServer — istediğiniz transport'a bağlayın