@tecof/mcp

stdio MCP-сервер для Tecof Developer API v1. Работает внутри репозитория темы Tecof; читает компоненты темы с диска (AST), преобразует простые определения «секций», написанные агентом, в документ редактора и создаёт/обновляет страницы в статусе черновика через Developer API. Публикация всегда выполняется из панели (в API нет publish).

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

• Node ≥ 20, ESM

• Поддерживаются аннотации инструментов (readOnlyHint, destructiveHint) и _meta["anthropic/requiresUserInteraction"] (для удаления)

Установка

В корне репозитория темы:

# 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

Сервер запускается через npx; глобальная установка не требуется:

npx -y @tecof/mcp@latest

Переменные окружения

Каталог проекта определяется в порядке TECOF_PROJECT_DIR → CLAUDE_PROJECT_DIR → process.cwd(); из него читаются .env и .env.local. process.env не перезаписывается — значения из файлов заполняют только пустые ключи (.env.local > .env).

При отсутствии токена/URL сервер всё равно запускается; list_components и validate_document работают, инструменты страниц возвращают ошибку с подсказкой. Логи пишутся только в stderr; необработанные ошибки также попадают в stderr, процесс не падает.

Безопасность: TECOF_API_URL должен быть https. Если указан адрес http:// (не loopback), при запуске выводится предупреждение в stderr, и к каждой ошибке инструмента добавляется та же подсказка; редиректы http→https не отслеживаются (Node fetch при редиректе сбрасывает Authorization, что даёт вводящий в заблуждение 401) — ответ 3xx превращается в ошибку «схема/хост TECOF_API_URL неверны». Таймаут запроса (30 с) покрывает чтение заголовков и тела целиком.

Claude Code — .mcp.json

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

Переменная окружения TECOF_MCP_PACKAGE переопределяет спецификацию пакета — до публикации в npm или для локальной разработки укажите папку этого репозитория (npx -y /path/to/tecof-mcp запускает bin из папки):

export TECOF_MCP_PACKAGE=/Users/<siz>/Desktop/Tecof/tecof-mcp   # claude'u bu shell'den başlatı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"]
    }
  }
}

Токен не записывается ни в один файл конфигурации; он остаётся в .env. Клиентский процесс запускается в корне репозитория темы, сервер читает .env оттуда.

Related MCP server: anticms-mcp

Инструменты

Результаты возвращаются как content[0].text (JSON) + structuredContent; ошибки имеют isError: true и содержат информацию о поле/пути (чтобы агент мог исправить).

Операции update_page

append_section{section} (перед Footer), insert_section{section, before?|after?} (если якорь не указан — как append, перед Footer), replace_section{id, section}, remove_section{id}, move_section{id, before?|after?}, set_props{id, props} (поверхностное слияние), set_slot{id, slot, children} (полностью заменяет слот; сначала строятся новые дети, при неудаче старое содержимое сохраняется), set_root_props{props}.

Примечания по поведению:

• Общие компоненты доступны только для чтения — включая их дочерние узлы. Узел с sharedComponentId (Header/Footer) и все его потомки в zones (Logo, NavLink, FooterColumn…) не могут быть изменены через set_props/set_slot/replace_section/remove_section; возвращается ошибка «общий компонент — редактируйте в панельном редакторе». Сам общий корень можно удалить со страницы через remove_section (с предупреждением; master не затрагивается). В outline get_page эти узлы помечены shared: true.

• Разделение ошибок/предупреждений (режим operations): документ, полученный через GET, сначала нормализуется (inline-массивы слотов, оставшиеся в props → zones; узлы SharedComponentRef с удалённым master отбрасываются с предупреждением — backend делает то же самое при PUT). Узлы, добавленные/изменённые агентом в этом ходе, проверяются строго (неизвестный type, нарушение allow, element-at-root → ошибка); нарушения в ранее существовавших, не тронутых узлах — только предупреждение: несвязанное обновление не блокируется из-за изменившейся темы. В режиме document и в create_page/validate_document все узлы проверяются строго.

• Пустой operations: [] (и нет meta) → ошибка «нет операций для применения»; PUT не отправляется. Если указан только meta, draftData не отправляется (status не меняется published→changed, лишняя ревизия не создаётся); в ответе это показывает поле savedDraft.

• Предупреждения бэкенда при сохранении (warnings: [{code,path,message}] в корне конверта, напр. отбрасывание ссылки на Header с удалённым master) возвращаются в ответе create_page/update_page строками sunucu: [code] path: message.

Формат авторства

Агент пишет не JSON документа, а дерево секций; генерация id, слияние defaultProps, преобразование slot → zone и многоязычные сокращения выполняются на сервере.

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

Правила преобразования:

1. Если type отсутствует в каталоге — ошибка; категория element в корне — ошибка; дочерний элемент слота вне allow — ошибка.

2. props = defaultProps (−id, −inline-дети слотов) ← variants[variant].props (+_variant) ← пользовательские props.

3. Если slots[slot] задан — он; если нет — примерные дети из defaultProps; если [] — пусто. Всё записывается в zones["<id>:<slot>"], props[slot] = [].

4. Многоязычные сокращения: "текст" → [{code: языкПоУмолчанию, value}]; {tr, en} → [{code,value}]; отсутствующий язык — предупреждение. link: "/путь" → [{code, value:{url, target:"_self"}}]. upload: строка URL → запись внешнего файла.

5. Если значение select/radio вне options — ошибка. Ключи с префиксом _ — ошибка (className разрешён).

6. id: 8 символов [A-Za-z0-9_-], уникален во всём документе (если передан валидный и уникальный props.id — принимается).

Разработка

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

Тесты не отправляют запросы к реальному бэкенду (мок fetch); каталог темы читается из копий компонентов в test/fixtures/theme.

Программное использование (HTTP transport и т.п.):

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