InstantCMS MCP server

InstantCMS MCP Server

MCP-сервер и набор переносимых AI-workflows для разработки дополнений, виджетов, шаблонов и layout-схем InstantCMS 2.

Сервер предоставляет структурированную базу API InstantCMS, безопасные генераторы, валидатор пакетов, диагностические инструменты и MCP resources. Runtime-данные синхронизированы с официальным репозиторием instantsoft/icms2, последняя проверенная стабильная версия — InstantCMS 2.18.2.

Текущий релиз: v1.8.0. Генераторы проверяются в рантайме на живом InstantCMS (npm run verify:generated): CRUD, API с токенами, виджеты, маршруты, ЧПУ по slug, фильтры, cron, формы и гриды. Сгенерированные API-дополнения при отсутствии метода модели отвечают 501 NOT_IMPLEMENTED, а не падают; scaffold_crud с with_api_model добавляет нужный контракт и токены. MCP работает автономно: доступ к GitHub нужен только сопровождающим проекта для обновления базы знаний.

Установка

npm install @maxisoft/instantcms-mcp

npm-пакет: @maxisoft/instantcms-mcp. Автоматическая публикация использует Trusted Publishing (GitHub Actions OIDC). Готовая сборка также доступна в GitHub Release ZIP:

curl -L -O https://github.com/instantcms-dev/instantcms-mcp/releases/download/v1.8.0/instantcms-mcp-v1.8.0.zip
unzip instantcms-mcp-v1.8.0.zip && cd instantcms-mcp-*/release
npm install --production
node dist/index.js

Подробности секции Установка.

Возможности

• справочник хуков с параметрами, типами и примерами;
• справочник основных классов InstantCMS;
• генерация пяти вариантов дополнений;
• генерация темы и YAML layout-схем;
• проверка полных installation package paths и плоских controller paths;
• диагностические коды для автоматического исправления;
• экранирование пользовательских данных для XML, INI, PHP и YAML;
• AI-инструкции и skills без дублирования базы знаний.
• 101 MCP-инструментов и четыре встроенных MCP resource;
• воспроизводимая генерация runtime-справочников из зафиксированного commit InstantCMS;
• автоматическая еженедельная проверка обновлений и Pull Request с изменившимися данными;
• CI на Node.js 22 и 24 (Stryker 10 требует ≥22).

Требования и установка

• Node.js 22 или новее (см. package.json:engines); Node.js 18 и 20 больше не поддерживаются — Stryker 10 требует ≥22.
• npm.

git clone https://github.com/instantcms-dev/instantcms-mcp.git
cd instantcms-mcp
npm ci
npm run build

Либо скачайте готовый ZIP из последнего GitHub Release.

Подключение к MCP-клиенту:

{
  "mcpServers": {
    "instantcms": {
      "command": "node",
      "args": ["/absolute/path/to/instantcms-mcp/dist/index.js"]
    }
  }
}

Для разработки:

npm run dev
npm run inspector
npm run check

npm run check выполняет проверку provenance/generated metadata, TypeScript, unit-тестов, порогов покрытия и конфигураций AI-клиентов. Интеграционный MCP smoke-test запускается отдельно командой npm run test:integration.

HTTP-транспорт (опционально)

По умолчанию сервер работает через stdio. Для удалённых клиентов доступен Streamable HTTP:

node dist/index.js --http                # http://127.0.0.1:3001/mcp
node dist/index.js --http --port 8080    # порт флагом или MCP_HTTP_PORT
MCP_HTTP_TOKEN=secret node dist/index.js --http   # требовать Authorization: Bearer secret
MCP_HTTP_HOST=0.0.0.0 node dist/index.js --http   # слушать внешний интерфейс
node dist/index.js --http --session      # stateful: сессии Mcp-Session-Id (GET/DELETE)
MCP_HTTP_RATE_LIMIT=120 node dist/index.js --http # лимит 120 запросов/мин с одного IP (429 + Retry-After)

• --session / MCP_HTTP_SESSION=1: MCP-сессия живёт между запросами; initialize выдаёт Mcp-Session-Id, GET держит SSE, DELETE закрывает сессию. / --session keeps MCP sessions alive across requests; initialize issues Mcp-Session-Id, GET opens SSE, DELETE closes. / --session 使 MCP 会话跨请求存续；initialize 下发 Mcp-Session-Id，GET 打开 SSE，DELETE 关闭会话。
• MCP_HTTP_RATE_LIMIT: фиксированное окно на IP, применяется до авторизации (брутфорс токена тоже ограничен). / Per-IP fixed-window rate limit applied before auth (token brute force is throttled too). / 基于 IP 的固定窗口限流，先于鉴权执行（令牌爆破同样受限）。
• За обратным прокси лимит считается по адресу прокси — используйте MCP_HTTP_HOST только с доверенным прокси. / Behind a reverse proxy the limit counts the proxy address — bind 0.0.0.0 only behind a trusted proxy. / 在反向代理之后按代理地址计数——仅在可信代理之后绑定 0.0.0.0。

Режим stateless (без сессий, только POST), по умолчанию привязка к 127.0.0.1 — сервер не доступен извне без явного MCP_HTTP_HOST. / HTTP mode is stateless (POST only) and binds to 127.0.0.1 by default. / HTTP 模式为无状态（仅 POST），默认绑定 127.0.0.1。

Профиль инструментов (опционально)

Определения инструментов (tools/list) уходят в контекст модели на каждый запрос, поэтому выключение неиспользуемых групп прямо снижает расход токенов:

INSTANTCMS_MCP_DISABLE=templates,sources node dist/index.js

• Группы: meta, generators, knowledge, database, sources, languages, extensions, project, templates. Неизвестные группы игнорируются с предупреждением в лог. / Groups: meta, generators, knowledge, database, sources, languages, extensions, project, templates. Unknown groups are ignored with a log warning. / 分组：meta, generators, knowledge, database, sources, languages, extensions, project, templates。未知分组会被忽略并记录警告。
• Мета-инструменты (find_tool, get_workflow) могут упоминать выключенные инструменты — их вызов вернёт ошибку клиента. / Meta tools (find_tool, get_workflow) may still mention disabled tools — calling them returns a client error. / 元工具（find_tool、get_workflow）仍可能提及已关闭的工具——调用会返回客户端错误。
• Фактическое число активных инструментов показывает get_server_capabilities. / get_server_capabilities reports the actual number of active tools. / get_server_capabilities 显示当前实际启用的工具数量。

Docker / Docker / Docker

Публикуемый в GHCR образ (docker.yml собирает linux/amd64 + linux/arm64 при теге v*):

docker run --rm -p 3001:3001 ghcr.io/instantcms-dev/instantcms-mcp
MCP_HTTP_TOKEN=secret docker run --rm -p 3001:3001 -e MCP_HTTP_TOKEN ghcr.io/instantcms-dev/instantcms-mcp

• Режим по умолчанию — HTTP на порту 3001 (EXPOSE 3001); stdio: docker run ... image node dist/index.js.
• GET /health — liveness-эндпоинт для оркестраторов, отвечает 200 без токена; остальные маршруты требуют Authorization: Bearer при заданном MCP_HTTP_TOKEN. / GET /health is a tokenless liveness probe; other routes require the bearer token when MCP_HTTP_TOKEN is set. / GET /health 为无需令牌的存活探针；设置 MCP_HTTP_TOKEN 后其余路由需要 Bearer 令牌。
• Локальная сборка: docker build -t instantcms-mcp .

Проверка генераторов на реальном InstantCMS

npm run verify:generated разворачивает сгенерированный артефакт в тестовом экземпляре InstantCMS, прогоняет HTTP-сценарии и удаляет всё созданное.

npm run verify:generated -- \
  --scenario crud --name mydemo \
  --site ~/Sites/idev.test --base-url https://idev.test \
  --db-name idev.test --db-user root --db-password secret \
  --insecure --yes --cleanup

• --scenario: crud, api, addon, component, webhook, external_api, oauth, content_type, widget, routes, crud_options, crud_slug, filter, cache, core_artifacts, template_override, admin_partial, import_export, cron, form, grid или integration.
• Без --yes скрипт только печатает план.
• --cleanup удаляет созданные файлы, записи и таблицы; удаляются только пустые каталоги, которые создал сам скрипт, и это проверяется тестами в src/__tests__/site-deploy.test.ts.
• Скрипт отказывается работать, если в каталоге нет system/config/config.php.

Экземпляр для проверки ставится без веб-установщика:

npm run verify:install-icms -- \
  --source .cache/icms2 --target /tmp/icms-site \
  --base-url http://127.0.0.1:8099 \
  --db-name icms_ci --db-user root --db-password secret

php -S 127.0.0.1:8099 -t /tmp/icms-site /tmp/icms-site/index.php &

scripts/install-instantcms.mjs копирует исходники, создаёт базу из base.sql (схема, контроллеры, виджеты, события, группы) и подключает виджеты темы через widgets_bind_modern.sql, после чего пишет config.php. Без второго дампа страницы рендерятся пустыми, потому что не подключается виджет «Тело страницы».

В CI это выполняет job Generated artifacts on a live InstantCMS: он поднимает MariaDB, ставит InstantCMS закреплённой версии и прогоняет все сценарии verify:generated.

Отдельный job Dependency audit проверяет npm audit --omit=dev --audit-level=high: advisories в dev-зависимостях (eslint, prettier) выпуск не блокируют, уязвимости в поставляемом коде — блокируют.

Выпуск релиза

Номер версии выбирается строго по SemVer (см. AGENTS.md → «Release versioning»): MAJOR — ломающие изменения, MINOR — обратно совместимые возможности, PATCH — исправления. Если в релиз попало несколько типов, берётся старшая часть.

Релиз запускается тегом, совпадающим с версией в package.json:

npm version minor          # или patch / major
git push && git push --tags

release.yml проверит, что тег, package.json и package-lock.json согласованы, прогонит проверки, соберёт ZIP для GitHub Release и опубликует пакет в npm через Trusted Publishing (OIDC). Версия с дефисом (например 1.5.0-beta.1) публикуется под dist-tag next, остальные — под latest.

Публикуемый пакет содержит только dist без тестов, README.md и LICENSE: сборка идёт по tsconfig.build.json, а npm run typecheck проверяет весь код, включая тесты.

Безопасность работы с базой данных

Инструменты maria_* работают с чужой базой, поэтому по умолчанию разрешено только чтение:

• maria_execute_query выполняет SELECT, SHOW, DESCRIBE, EXPLAIN, WITH; изменение данных требует явного allow_write: true;
• запросы INTO OUTFILE/DUMPFILE, LOAD_FILE, GRANT, CREATE USER, SET GLOBAL, SHUTDOWN запрещены всегда;
• несколько инструкций в одном запросе отклоняются;
• строки ответа ограничены (по умолчанию 1000, признак truncated), запрос имеет таймаут (по умолчанию 10 секунд);
• значения колонок-секретов (password, password_hash, api_token, token_hash, secret_key и подобных) заменяются на ***; какие именно колонки скрыты, видно в redacted_columns. Вернуть их как есть можно только явным include_sensitive: true;
• в текстах ошибок и в эхо-запросе маскируются пароли, токены, учётные данные в URL и Authorization.

Скрипты scripts/install-instantcms.mjs и scripts/verify-generated.ts не передают пароль MySQL аргументом (-p<password> виден в ps): они пишут временный option-файл с правами 0600 и удаляют его при выходе.

Переменная DB_READONLY=1 запрещает запись полностью, даже с allow_write. Для рабочей базы рекомендуется отдельный пользователь MySQL только с правами SELECT.

Проверка достоверности базы знаний

Утверждения src/data сверяются с закреплённым исходником InstantCMS тестом src/__tests__/knowledge-provenance.test.ts: существование всех файлов, на которые ссылаются справочники (поля, контроллеры, трейты, виджеты), объявление классов ядра в своих файлах, вызовы хуков в исходниках (hook, hookAll, runHook), типы из components, а также отсутствие в документации несуществующих конвенций (system/hooks/, system/config/permissions/, extends cmsInstaller).

Без исходников проверка пропускается; в CI её выполняет job upstream-compatibility, где выставляется ICMS_REQUIRE_SOURCE=1 и данные должны совпасть с upstream.

Уровень достоверности каждого источника задан в knowledge/catalog.yaml и проверяется сборкой: verified допустим только для файлов, созданных парсером закреплённого исходника, а рукописные данные помечаются curated и inferred. npm run knowledge:build падает, если достоверность завышена. Текущая сводка доступна в get_server_capabilities (knowledge.sources).

Ответ на несуществующий или неоднозначный запрос — это отказ с кандидатами, а не правдоподобная выдумка:

Матрица проверки генераторов

Проверено на живом InstantCMS 2.18.2 (скрипт npm run verify:generated и ручные сценарии).

Генератор	Проверка
scaffold_crud	рантайм: список, материал, 404, гость, пагинация
scaffold_api	рантайм: 200/501/401/405, JSON-ответы
scaffold_addon	рантайм: фронтенд, дашборд и грид админки
scaffold_widget	рантайм: привязка к позиции и рендер на главной
scaffold_permission	рантайм: правила регистрируются и читаются cmsPermissions::getRulesList()
scaffold_seo	рантайм: хук render_page внедряет Open Graph и JSON-LD в страницу
scaffold_filter	рантайм: грид с фильтрами в админке и применение фронтенд-фильтра к модели
scaffold_addon (with_routes)	рантайм: ЧПУ из routes.php через метод route()
scaffold_crud (with_api_model)	рантайм: контракт API и токены выдаются и проверяются
scaffold_crud (use_seo, list_template)	рантайм: SEO-метатеги в <head> и разметка списка таблицей
scaffold_crud (use_slug) + scaffold_seo (use_slug)	рантайм: ЧПУ /c/<slug>.html, 404 на чужой slug, OG по slug
scaffold_form	рантайм: класс формы загружается и собирает структуру
scaffold_grid	рантайм: функция грида возвращает колонки с фильтрами
scaffold_cron	рантайм: задача планировщика регистрируется и выполняется
scaffold_email	рантайм: письмо читается getLanguageTextFile, {плейсхолдеры} подставляются
scaffold_layout_override	рантайм: шаблон темы рендерится через getTemplateFileName()
scaffold_admin_partial	рантайм: фрагмент админки рендерится через getRenderedAsset()
scaffold_cache	рантайм: класс кэша и хук <controller>_after_add вызывается ядром
scaffold_import_export	рантайм: импорт/экспорт на модели CRUD, API-действия и форма импорта
scaffold_component	рантайм: multi-controller пакет, классы по конвенции ядра, фронтенд и модель
scaffold_webhook	рантайм: приём подписанного веб-хука, очередь на cmsModel и cron-обработка
scaffold_external_api	рантайм: cURL-клиент, auth-заголовки, rate limiting и кэш на cmsCache
scaffold_oauth	рантайм: OAuth-обмен кода на токен через cURL, PKCE и токены в БД
scaffold_migration, generate_migration, scaffold_lang, scaffold_hook	рантайм: таблица создаётся из SQL, install_package() и хук вызываются ядром
scaffold_content_type	рантайм: 7 таблиц ТК, записи, поля/колонки, опции и докатка поля на существующий тип
scaffold_test	только статически: нужны PHPUnit/Codeception
scaffold_template, scaffold_complete_template	только статически: активация темы затрагивает весь сайт

«Только статически» означает: php -l, проверка символов против реального исходника, соответствие структуре каталогов. Поведение в рантайме для этих генераторов не подтверждено.

Все генераторы либо проверены в рантайме, либо помечены как «только статически» (см. выше): прототипов с scaffold_status: 'experimental' больше не осталось.

Основные MCP-инструменты

Сервер регистрирует 101 инструментов. Ниже — сгруппированный список (RU/EN/中文). Полные схемы и описания доступны через стандартный MCP tools/list.

Так выглядит ответ по конкретному хуку — с параметрами, файлами-источниками в ядре и примером реализации:

Мета / Meta / 元 (10)

Инструмент / Tool / 工具	Назначение / RU	Purpose / EN	用途 / 中文
get_server_capabilities	Версии, профили и объём базы знаний MCP-сервера	Versions, profiles, and knowledge base size of the MCP server	—
find_tool	Подбирает MCP-инструменты по описанию задачи	Selects MCP tools by task description	—
get_workflow	Возвращает рекомендуемую последовательность инструментов	Returns the recommended sequence of tools	—
diagnose_request	Определяет тип InstantCMS-задачи и рекомендуемый workflow	Determines the InstantCMS task type and recommended workflow	—
explain_validation_error	Объясняет стабильный код диагностики	Explains a stable diagnostic code	—
compare_instantcms_versions	Сравнивает документированные профили InstantCMS	Compares documented InstantCMS profiles	—
get_project_health	Возвращает состояние встроенной базы и рекомендуемые проверки	Returns the state of the built-in knowledge base and recommended checks	—
validate_generated_artifacts	Проверяет XML, INI, YAML и форму PHP-файлов настоящими parser-ами	Validates XML, INI, YAML, and the shape of PHP files with real parsers	—
build_addon_archive	Создаёт ZIP дополнения в памяти и возвращает base64	Creates an addon ZIP in memory and returns base64	—
inspect_addon_archive	Проверяет пути и синтаксис файлов ZIP-архива base64	Checks paths and syntax of files inside a base64 ZIP archive	—