@maxisoft/instantcms-mcp 1.2.3

package/dist/tools/widget-tool.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * @fileoverview Widget scaffolding tool for InstantCMS
+ * Generates widgets with options, templates, and configuration
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.widgetToolSchema = exports.WidgetFieldTypeEnum = void 0;
+exports.scaffoldWidget = scaffoldWidget;
+const zod_1 = require("zod");
+const scaffold_1 = require("../types/scaffold");
+/**
+ * Widget option field types
+ */
+exports.WidgetFieldTypeEnum = zod_1.z.enum([
+    'text',
+    'number',
+    'select',
+    'checkbox',
+    'textarea',
+    'image',
+]);
+/**
+ * Generates widget class
+ */
+function generateWidgetClass(name, widget, Widget, options, options_config) {
+    const optionDefaults = options
+        .map(o => {
+        const defaultVal = typeof o.default === 'string' ? `'${o.default}'` : (o.default ?? 'null');
+        return `        '${o.name}' => ${defaultVal},`;
+    })
+        .join('\n');
+    return `<?php
+// InstantCMS 2. ${name}/widgets/${widget}.php
+
+class ${Widget}Widget extends cmsWidget {
+
+    public $is_cacheable = ${options_config.with_cache};
+
+    public function run() {
+        $options = $this->getOptions([
+${optionDefaults}
+        ]);
+
+        $data = [
+            'widget' => $this,
+            'options' => $options,
+            'title' => $options['title'],
+        ];
+
+        return $this->renderTemplate('${widget}', $data);
+    }
+
+    public function getCacheKey() {
+        return [
+            cmsConfig::get('cur_lang'),
+            $this->getOption('widget_id'),
+            $this->getOption('page'),
+        ];
+    }
+
+    public function validateOptions($options) {
+        return $options;
+    }
+
+    public function getSizeOptions() {
+        return [
+            'full' => 'Во всю ширину',
+            'half' => 'Половина ширины',
+            'third' => 'Треть ширины',
+        ];
+    }
+}`;
+}
+/**
+ * Generates widget options class
+ */
+function generateWidgetOptions(widget, Widget, options) {
+    const fieldsCode = options
+        .map(o => {
+        switch (o.type) {
+            case 'text':
+                return `        $form->addField('${o.name}', new fieldString('${o.label}'));`;
+            case 'number':
+                return `        $form->addField('${o.name}', new fieldNumber('${o.label}'));`;
+            case 'select': {
+                const optsStr = (o.options || [])
+                    .map(opt => `'${opt.value}' => '${opt.label}'`)
+                    .join(', ');
+                return `        $form->addField('${o.name}', new fieldList('${o.label}', ['options' => [${optsStr}]]));`;
+            }
+            case 'checkbox':
+                return `        $form->addField('${o.name}', new fieldCheckbox('${o.label}'));`;
+            case 'textarea':
+                return `        $form->addField('${o.name}', new fieldText('${o.label}'));`;
+            case 'image':
+                return `        $form->addField('${o.name}', new fieldImage('${o.label}'));`;
+            default:
+                return `        $form->addField('${o.name}', new fieldString('${o.label}'));`;
+        }
+    })
+        .join('\n');
+    return `<?php
+// InstantCMS 2. widgets/${widget}.options.php
+
+class ${Widget}WidgetOptions {
+
+    public static function getConfigForm($form) {
+${fieldsCode}
+
+        return $form;
+    }
+
+    public static function getDefaultOptions() {
+        return [
+${options
+        .map(o => {
+        const defaultVal = typeof o.default === 'string' ? `'${o.default}'` : (o.default ?? 'null');
+        return `            '${o.name}' => ${defaultVal},`;
+    })
+        .join('\n')}
+        ];
+    }
+
+    public static function getOptionLabels() {
+        return [
+${options.map(o => `            '${o.name}' => '${o.label}',`).join('\n')}
+        ];
+    }
+}`;
+}
+/**
+ * Generates widget template
+ */
+function generateWidgetTemplate(widget, _Widget, _options) {
+    return `<?php
+// InstantCMS 2. widgets/${widget}.html.php
+
+\\$widget = \\$data['widget'];
+\\$options = \\$data['options'];
+\\$title = \\$options['title'] ?? '';
+\\$limit = \\$options['limit'] ?? 5;
+?>
+
+<?php if (\\$title): ?>
+<h3 class="widget-title"><?php echo \\$title; ?></h3>
+<?php endif; ?>
+
+<div class="${widget}-widget">
+    <div class="widget-content">
+        <!-- Widget content here -->
+    </div>
+</div>
+
+<style>
+.widget-${widget} {
+    padding: 0;
+}
+.widget-${widget} .widget-title {
+    margin: 0 0 15px 0;
+    font-size: 18px;
+}
+.widget-${widget} .widget-content {
+    padding: 10px 0;
+}
+</style>
+`;
+}
+/**
+ * Generates widget CSS styles
+ */
+function generateWidgetStyles(widget, _options) {
+    return `/* InstantCMS 2. ${widget} widget styles */
+
+.${widget}-widget {
+    padding: 0;
+}
+
+.${widget}-widget .widget-title {
+    margin: 0 0 15px 0;
+    font-size: 18px;
+    font-weight: 600;
+}
+
+.${widget}-widget .widget-content {
+    padding: 10px 0;
+}
+
+.${widget}-widget .item {
+    padding: 8px 0;
+    border-bottom: 1px solid #eee;
+}
+
+.${widget}-widget .item:last-child {
+    border-bottom: none;
+}
+
+.${widget}-widget .item-title {
+    font-weight: 500;
+}
+
+.${widget}-widget .item-date {
+    font-size: 12px;
+    color: #999;
+}
+`;
+}
+/**
+ * Generates widget configuration
+ */
+function generateWidgetConfig(name, widget, Widget, options) {
+    return `<?php
+// InstantCMS 2. system/config/widgets/${widget}.php
+
+return [
+    'widget' => '${widget}',
+    'component' => '${name}',
+    'class' => '${Widget}Widget',
+    'options_class' => '${Widget}WidgetOptions',
+    'title' => '${Widget}',
+    'description' => '',
+    'version' => '1.0.0',
+    'author' => '',
+    'options' => [
+${options.map(o => `        '${o.name}' => '${o.label}',`).join('\n')}
+    ],
+    'size_options' => [
+        'full',
+        'half',
+        'third',
+    ],
+];`;
+}
+/**
+ * Generates a complete widget for InstantCMS
+ *
+ * @param opts - Configuration options for the widget
+ * @returns Object containing generated files and metadata
+ *
+ * @example
+ * ```typescript
+ * const result = scaffoldWidget({
+ *   addon_name: 'blog',
+ *   widget_name: 'recent_posts',
+ *   options: [
+ *     { name: 'title', type: 'text', label: 'Заголовок', default: 'Последние записи' },
+ *     { name: 'limit', type: 'number', label: 'Количество', default: 5 }
+ *   ]
+ * });
+ * ```
+ */
+function scaffoldWidget(opts) {
+    const { lowercase } = (0, scaffold_1.normalizeAddonName)(opts.addon_name);
+    const widget = opts.widget_name.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+    const Widget = widget
+        .split('_')
+        .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+        .join('');
+    const files = {};
+    const options_config = {
+        with_template: opts.options_config?.with_template ?? true,
+        with_styles: opts.options_config?.with_styles ?? true,
+        with_cache: opts.options_config?.with_cache ?? true,
+    };
+    const options = opts.options || [
+        { name: 'title', type: 'text', label: 'Заголовок', default: '' },
+        { name: 'limit', type: 'number', label: 'Количество', default: 5 },
+    ];
+    files[`${lowercase}/widgets/${widget}.php`] = generateWidgetClass(lowercase, widget, Widget, options, options_config);
+    files[`${lowercase}/widgets/${widget}.options.php`] = generateWidgetOptions(widget, Widget, options);
+    files[`${lowercase}/widgets/${widget}.html.php`] = generateWidgetTemplate(widget, Widget, options);
+    if (options_config.with_styles) {
+        files[`${lowercase}/widgets/${widget}.css`] = generateWidgetStyles(widget, options);
+    }
+    files[`system/config/widgets/${widget}.php`] = generateWidgetConfig(lowercase, widget, Widget, options);
+    return {
+        addon_name: lowercase,
+        files,
+        widget_name: widget,
+        options_count: options.length,
+        options_config,
+    };
+}
+exports.widgetToolSchema = {
+    name: 'scaffold_widget',
+    description: 'Генерация виджета InstantCMS с настройками и шаблонами',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            addon_name: { type: 'string', description: 'Имя компонента' },
+            widget_name: { type: 'string', description: 'Имя виджета' },
+            options: zod_1.z
+                .array(zod_1.z.object({
+                name: zod_1.z.string().describe('Имя опции'),
+                type: zod_1.z
+                    .enum(['text', 'number', 'select', 'checkbox', 'textarea', 'image'])
+                    .describe('Тип поля'),
+                label: zod_1.z.string().describe('Название'),
+                options: zod_1.z
+                    .array(zod_1.z.object({ value: zod_1.z.string(), label: zod_1.z.string() }))
+                    .optional()
+                    .describe('Опции для select'),
+                default: zod_1.z
+                    .union([zod_1.z.string(), zod_1.z.boolean(), zod_1.z.number()])
+                    .optional()
+                    .describe('Значение по умолчанию'),
+            }))
+                .optional()
+                .describe('Опции виджета'),
+            options_config: zod_1.z
+                .object({
+                with_template: zod_1.z.boolean().optional().describe('С шаблоном'),
+                with_styles: zod_1.z.boolean().optional().describe('Со стилями'),
+                with_cache: zod_1.z.boolean().optional().describe('С кэшированием'),
+            })
+                .optional()
+                .describe('Конфигурация'),
+        },
+        required: ['addon_name', 'widget_name'],
+    },
+    inputExamples: [
+        {
+            addon_name: 'blog',
+            widget_name: 'recent_posts',
+            options: [
+                { name: 'title', type: 'text', label: 'Заголовок', default: 'Последние записи' },
+                { name: 'limit', type: 'number', label: 'Количество', default: 5 },
+                { name: 'show_date', type: 'checkbox', label: 'Показывать дату', default: true },
+            ],
+        },
+    ],
+};

package/dist/tools/wysiwyg-tool.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listWysiwygEditors = listWysiwygEditors;
+exports.getWysiwygEditor = getWysiwygEditor;
+exports.getWysiwygOptions = getWysiwygOptions;
+exports.getWysiwygPlugins = getWysiwygPlugins;
+exports.searchWysiwygEditors = searchWysiwygEditors;
+exports.getWysiwygButtons = getWysiwygButtons;
+const wysiwyg_map_js_1 = require("../data/wysiwyg-map.js");
+function listWysiwygEditors() {
+    return {
+        total: wysiwyg_map_js_1.wysiwygMap.editorCount,
+        editors: wysiwyg_map_js_1.wysiwygMap.editors.map(e => ({
+            name: e.name,
+            className: e.className,
+            description: e.description,
+            features: e.features,
+            plugins_count: e.plugins?.length ?? 0,
+        })),
+    };
+}
+function getWysiwygEditor(editorName) {
+    const editor = wysiwyg_map_js_1.wysiwygMap.byName[editorName.toLowerCase()];
+    if (!editor) {
+        const similar = Object.keys(wysiwyg_map_js_1.wysiwygMap.byName).filter(name => name.includes(editorName.toLowerCase()));
+        return {
+            error: `Редактор "${editorName}" не найден`,
+            available: Object.keys(wysiwyg_map_js_1.wysiwygMap.byName),
+            similar: similar.length > 0 ? similar : undefined,
+        };
+    }
+    return {
+        name: editor.name,
+        className: editor.className,
+        filePath: editor.filePath,
+        optionsFormPath: editor.optionsFormPath,
+        description: editor.description,
+        features: editor.features,
+        options: editor.options,
+        options_descriptions: editor.optionsDescriptions,
+        plugins: editor.plugins,
+        buttons: editor.buttons,
+        usage: {
+            instantiation: `cmsWysiwyg::getEditor('${editor.name}', $config);`,
+            display: `$editor = cmsWysiwyg::getEditor('${editor.name}');\n$editor->displayEditor('content', $content);`,
+            options_form: editor.optionsFormPath,
+        },
+        example_config: buildExampleConfig(editor),
+    };
+}
+function getWysiwygOptions(editorName) {
+    const editor = wysiwyg_map_js_1.wysiwygMap.byName[editorName.toLowerCase()];
+    if (!editor) {
+        return { error: `Редактор "${editorName}" не найден` };
+    }
+    return {
+        editor: editor.name,
+        options: Object.entries(editor.optionsDescriptions).map(([key, opt]) => ({
+            name: key,
+            type: opt.type,
+            description: opt.description,
+            default: opt.default,
+            current: editor.options[key],
+        })),
+    };
+}
+function getWysiwygPlugins(editorName) {
+    const editor = wysiwyg_map_js_1.wysiwygMap.byName[editorName.toLowerCase()];
+    if (!editor) {
+        return { error: `Редактор "${editorName}" не найден` };
+    }
+    if (!editor.plugins) {
+        return {
+            editor: editor.name,
+            plugins: [],
+            note: `${editor.name} не поддерживает плагины`,
+        };
+    }
+    return {
+        editor: editor.name,
+        plugins: editor.plugins,
+    };
+}
+function searchWysiwygEditors(query) {
+    const lower = query.toLowerCase();
+    const results = wysiwyg_map_js_1.wysiwygMap.editors.filter(e => e.name.includes(lower) ||
+        e.description.toLowerCase().includes(lower) ||
+        e.features.some(f => f.toLowerCase().includes(lower)) ||
+        e.plugins?.some(p => p.name.includes(lower) || p.description.toLowerCase().includes(lower)));
+    return {
+        query,
+        total: results.length,
+        results: results.map(e => ({
+            name: e.name,
+            description: e.description,
+            matching_features: e.features.filter(f => f.toLowerCase().includes(lower)),
+            matching_plugins: e.plugins?.filter(p => p.name.includes(lower) || p.description.toLowerCase().includes(lower)) ?? [],
+        })),
+    };
+}
+function getWysiwygButtons(editorName) {
+    const editor = wysiwyg_map_js_1.wysiwygMap.byName[editorName.toLowerCase()];
+    if (!editor) {
+        return { error: `Редактор "${editorName}" не найден` };
+    }
+    if (editorName === 'markitup' && editor.buttons) {
+        return {
+            editor: editor.name,
+            type: 'markitup_buttons',
+            buttons: editor.buttons.map((btn, index) => ({
+                id: index,
+                ...(typeof btn === 'string' ? { name: btn } : btn),
+            })),
+        };
+    }
+    if (editor.buttons && editor.buttons.every(b => typeof b === 'string')) {
+        return {
+            editor: editor.name,
+            type: 'toolbar_buttons',
+            buttons: editor.buttons,
+        };
+    }
+    return {
+        editor: editor.name,
+        buttons: editor.buttons ?? [],
+        note: `${editor.name} не имеет списка кнопок`,
+    };
+}
+function buildExampleConfig(editor) {
+    const example = {};
+    Object.entries(editor.optionsDescriptions).forEach(([key, opt]) => {
+        if (opt.default !== undefined) {
+            example[key] = opt.default;
+        }
+    });
+    return example;
+}

package/dist/types/scaffold.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createError = createError;
+exports.createSuccess = createSuccess;
+exports.validateAddonName = validateAddonName;
+exports.normalizeAddonName = normalizeAddonName;
+exports.sanitizePath = sanitizePath;
+exports.getCurrentDate = getCurrentDate;
+/**
+ * Creates a standardized error response
+ */
+function createError(code, message, details) {
+    return {
+        success: false,
+        error: { code, message, details },
+    };
+}
+/**
+ * Creates a standardized success response
+ */
+function createSuccess(data) {
+    return {
+        success: true,
+        data,
+    };
+}
+/**
+ * Validates addon name format
+ */
+function validateAddonName(name) {
+    if (!name) {
+        return { valid: false, error: 'Addon name is required' };
+    }
+    if (!/^[a-z][a-z0-9_]*$/.test(name)) {
+        return {
+            valid: false,
+            error: 'Addon name must start with lowercase letter and contain only lowercase letters, numbers, and underscores',
+        };
+    }
+    if (name.length > 50) {
+        return { valid: false, error: 'Addon name must be 50 characters or less' };
+    }
+    return { valid: true };
+}
+/**
+ * Converts addon name to various case formats
+ */
+function normalizeAddonName(name) {
+    const lowercase = name.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+    const UpperCamelCase = lowercase
+        .split('_')
+        .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+        .join('');
+    const lowercaseSnake = lowercase.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase();
+    return { lowercase, UpperCamelCase, lowercaseSnake };
+}
+/**
+ * Sanitizes a string for use in file paths
+ */
+function sanitizePath(str) {
+    return str.replace(/[^a-zA-Z0-9_\/-]/g, '_').replace(/__+/g, '_');
+}
+/**
+ * Generates a timestamp for use in version strings
+ */
+function getCurrentDate() {
+    return new Date().toISOString().split('T')[0];
+}

package/dist/utils/define-tool.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTool = defineTool;
+exports.defineToolWithManualResult = defineToolWithManualResult;
+const mcp_result_js_1 = require("./mcp-result.js");
+/**
+ * Регистрирует MCP-инструмент и нормализует контракт ответа.
+ *
+ * Любое исключение из handler превращается в errorResult (isError: true,
+ * code: TOOL_EXECUTION_ERROR), не пробрасывается наружу. Это сохраняет
+ * инвариант MCP: каждый tools/call возвращает корректный результат.
+ *
+ * Schema намеренно типизирована как `unknown`, чтобы не воевать с zod v4 ↔
+ * MCP SDK generic-конфликтами; контракт реэкспортируется из sdk в site-вызова.
+ */
+function defineTool(server, name, description, schema, handler) {
+    server.tool(name, description, schema, async (rawArgs) => {
+        try {
+            const data = await handler((rawArgs ?? {}));
+            return (0, mcp_result_js_1.successResult)(data);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return (0, mcp_result_js_1.errorResult)('TOOL_EXECUTION_ERROR', message, {
+                tool: name,
+                cause: err instanceof Error ? err.stack : undefined,
+            });
+        }
+    });
+}
+/**
+ * Вариант, когда handler сам решает вернуть success- или error-result
+ * (например, для ожидаемых отказов вроде "unknown lookup").
+ */
+function defineToolWithManualResult(server, name, description, schema, handler) {
+    server.tool(name, description, schema, handler);
+}

package/dist/utils/find-tool.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Matching логика для find_tool: token-based matching с ранжированием.
+ *
+ * Приоритет:
+ *   1. exact match ключевого слова (category.keywords.includes(query.normalized))
+ *   2. prefix match (keyword.startsWith(queryToken) || queryToken.startsWith(keyword))
+ *   3. substring match (keyword.includes(queryToken) || queryToken.includes(keyword))
+ *
+ * Запрос токенизируется по Unicode-словным границам; multi-word запросы
+ * матчатся, если ВСЕ токены попадают в keywords одной категории.
+ * Возвращает категории, отсортированные по score desc, плюс дополнительные
+ * метрики.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rankToolCategories = rankToolCategories;
+exports.findToolCategories = findToolCategories;
+const MAX_TOKEN_LENGTH = 64;
+function normalize(s) {
+    return s.toLowerCase().trim();
+}
+function tokenize(s) {
+    const norm = normalize(s);
+    // Unicode-словные границы, фильтр пустых и длинных токенов.
+    return norm
+        .split(/[\s,.!?;:"'()[\]{}<>|/\\\-_+=]+/u)
+        .filter(t => t.length > 0 && t.length <= MAX_TOKEN_LENGTH);
+}
+function scoreCategory(queryTokens, category) {
+    if (queryTokens.length === 0 || category.keywords.length === 0) {
+        return { score: 0, matched: [] };
+    }
+    const keywords = category.keywords.map(normalize);
+    const matched = [];
+    let totalScore = 0;
+    for (const token of queryTokens) {
+        let bestScore = 0;
+        let matchedKeyword = null;
+        for (const keyword of keywords) {
+            let s = 0;
+            if (keyword === token) {
+                s = 100;
+            }
+            else if (keyword.startsWith(token) || token.startsWith(keyword)) {
+                s = 60;
+            }
+            else if (keyword.includes(token) || token.includes(keyword)) {
+                s = 30;
+            }
+            if (s > bestScore) {
+                bestScore = s;
+                matchedKeyword = keyword;
+            }
+        }
+        if (bestScore > 0) {
+            totalScore += bestScore;
+            if (matchedKeyword)
+                matched.push(matchedKeyword);
+        }
+    }
+    // Multi-word: matched at least once per token.
+    if (matched.length < queryTokens.length) {
+        // Partial match: даём меньший score, чтобы категории с полным совпадением
+        // были выше.
+        totalScore = Math.floor(totalScore * 0.5);
+    }
+    return { score: totalScore, matched };
+}
+/**
+ * Ранжирует категории по релевантности запросу. Возвращает не более maxResults,
+ * отсортированных по score desc. Категории с score=0 НЕ включаются.
+ */
+function rankToolCategories(query, categories, maxResults = 5) {
+    const tokens = tokenize(query);
+    if (tokens.length === 0)
+        return [];
+    return categories
+        .map(category => {
+        const { score, matched } = scoreCategory(tokens, category);
+        return { category: category.category, tools: category.tools, score, matchedTokens: matched };
+    })
+        .filter(result => result.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+}
+/**
+ * Удобная обёртка: вернуть список объектов ToolCategory в исходном формате,
+ * отсортированных по релевантности. Пустой результат → полный каталог.
+ */
+function findToolCategories(query, categories, fallbackAll = true) {
+    const ranked = rankToolCategories(query, categories);
+    const matches = categories.filter(c => ranked.some(r => r.category === c.category));
+    if (matches.length === 0 && fallbackAll) {
+        return { matches: categories, ranked: [] };
+    }
+    return { matches, ranked };
+}

package/dist/utils/mcp-result.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.successResult = successResult;
+exports.errorResult = errorResult;
+function successResult(data, summary) {
+    return {
+        content: [{ type: 'text', text: summary ?? JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+    };
+}
+function errorResult(code, message, details = {}) {
+    const data = { code, message, ...details };
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+    };
+}