@tecof/mcp

Servidor MCP stdio para la API de desarrollador de Tecof v1. Se ejecuta desde dentro de un repositorio de temas de Tecof; lee los componentes del tema desde el disco (AST), convierte las definiciones simples de «secciones» escritas por el agente en un documento de editor y crea/actualiza páginas en borrador mediante la API de desarrollador. La publicación siempre se realiza desde el panel (no hay publish en la API).

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

• Node ≥ 20, ESM

• Anotaciones de herramientas (readOnlyHint, destructiveHint) y _meta["anthropic/requiresUserInteraction"] (borrado) compatibles.

Instalación

En la raíz del repositorio de temas:

# 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

El servidor se ejecuta con npx; no requiere instalación global:

npx -y @tecof/mcp@latest

Variables de entorno

El directorio del proyecto se determina en el orden TECOF_PROJECT_DIR → CLAUDE_PROJECT_DIR → process.cwd(); .env y .env.local se leen desde ahí. process.env no se sobrescribe: los valores de los archivos solo completan las claves vacías (.env.local > .env).

Si falta el token/URL, el servidor igualmente arranca; list_components y validate_document funcionan, y las herramientas de páginas devuelven un error orientativo. Los registros se escriben solo en stderr; los errores no capturados también van a stderr y el proceso no se bloquea.

Seguridad: TECOF_API_URL debe ser https. Si se proporciona una dirección http:// (fuera de loopback), se muestra una advertencia en stderr al inicio y se añade la misma pista a cada error de herramienta; las redirecciones http→https no se siguen (Node fetch elimina Authorization en la redirección, lo que producía un 401 engañoso) — una respuesta 3xx se convierte en el error «esquema/host de TECOF_API_URL incorrecto». El tiempo de espera de la solicitud (30 s) cubre la lectura completa de cabeceras y cuerpo.

Claude Code — .mcp.json

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

La variable de entorno TECOF_MCP_PACKAGE sobrescribe la especificación del paquete: indique la carpeta de este repositorio antes de publicarlo en npm o para desarrollo local (npx -y /path/to/tecof-mcp ejecuta el bin de la carpeta):

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

Publicación (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"]
    }
  }
}

El token no se escribe en ningún archivo de configuración; permanece en .env. El proceso cliente se inicia en la raíz del repositorio de temas y el servidor lee el .env desde allí.

Related MCP server: anticms-mcp

Herramientas

Los resultados se devuelven como content[0].text (JSON) + structuredContent; los errores llevan isError: true con información de campo/ruta (para que el agente pueda corregirlos).

Operaciones de update_page

append_section{section} (antes del Footer), insert_section{section, before?|after?} (si no hay ancla, como append, antes del Footer), replace_section{id, section}, remove_section{id}, move_section{id, before?|after?}, set_props{id, props} (fusión superficial), set_slot{id, slot, children} (reemplaza el slot por completo; primero se construyen los nuevos hijos, si falla se conserva el contenido anterior), set_root_props{props}.

Notas de comportamiento:

• Los componentes compartidos son de solo lectura, incluidos sus nodos hijos. El nodo que lleva sharedComponentId (Header/Footer) y todos sus descendientes bajo zones (Logo, NavLink, FooterColumn…) no se pueden modificar con set_props/set_slot/replace_section/remove_section; devuelve el error «componente compartido: edítelo desde el editor del panel». La raíz compartida en sí puede eliminarse de la página con remove_section (con advertencia; el master no se ve afectado). En el outline de get_page, estos nodos están marcados con shared: true.

• Distinción entre error y advertencia (modo operations): el documento procedente de GET se normaliza primero (las matrices de slots inline que quedaron en props → zones; los nodos SharedComponentRef cuyo master se ha eliminado se descartan con advertencia — el backend hace lo mismo en el PUT). Los nodos que el agente añadió/modificó en esta ronda se validan estrictamente (tipo desconocido, violación de allow, element-at-root → error); las violaciones en nodos preexistentes no tocados son solo advertencias: una actualización no relacionada no se bloquea porque el tema haya cambiado. En el modo document y en create_page/validate_document, todos los nodos se validan estrictamente.

• operations: [] vacío (si tampoco hay meta) → error «no hay operaciones que aplicar»; no se hace PUT. Si solo se proporciona meta, no se envía draftData (el estado no pasa de published→changed, no se abre una revisión innecesaria); el campo savedDraft de la respuesta lo indica.

• Las advertencias de guardado del backend (warnings: [{code,path,message}] en la raíz del sobre, p. ej. la eliminación de un vínculo Header cuyo master se ha borrado) se devuelven en la respuesta de create_page/update_page como líneas sunucu: [code] path: message.

Formato de autoría

El agente escribe un árbol de secciones, no un documento JSON; la generación de ids, la fusión de defaultProps, la conversión de slot → zone y los atajos multilingües se realizan en el servidor.

{
  "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>" } } ] } }
    ]
  }
}

Reglas de conversión:

1. Si type no está en el catálogo, error; la categoría element en la raíz, error; un hijo de slot fuera de allow, error.

2. props = defaultProps (−id, −hijos de slot inline) ← variants[variant].props (+_variant) ← props del usuario.

3. Si se proporciona slots[slot], se usa ese; si no, los hijos de ejemplo en defaultProps; si se proporciona [], vacío. Todo se escribe en zones["<id>:<slot>"] y props[slot] = [].

4. Atajos multilingües: "metin" → [{code: varsayılanDil, value}]; {tr, en} → [{code,value}]; idioma faltante advertencia. link: "/yol" → [{code, value:{url, target:"_self"}}]. upload: URL string → registro de archivo externo.

5. Si el valor de select/radio está fuera de options, error. Las claves con prefijo _ son error (className libre).

6. id: 8 caracteres [A-Za-z0-9_-], único en todo el documento (si se proporciona un props.id válido y único, se acepta).

Desarrollo

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

Los tests no hacen peticiones al backend real (mock de fetch); el catálogo de temas se lee de los componentes de copia en test/fixtures/theme.

Uso programático (transporte HTTP, etc.):

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