MCP Report Generator

Генератор HTML-отчётов и инструкций администратора через Model Context Protocol (MCP). FastAPI + Python, Jinja2-шаблоны, SSE-транспорт.

Обзор

MCP Report Generator — это сервер, который предоставляет Claude Code (и другим MCP-клиентам) инструменты для генерации красивых HTML-отчётов. Два типа документов:

• Отчёт / Чеклист — статус выполненных задач, шаги ручной проверки, результаты E2E-тестов
• Инструкция администратора — пошаговое руководство по админ-панели с таблицами полей и хлебными крошками

Отчёты генерируются как самодостаточные HTML-файлы (весь CSS встроен) и сохраняются на сервере. В ответ вы получаете прямую ссылку на готовый документ.

Быстрый старт

1. 1 Добавьте MCP-сервер в конфигурацию Claude Code. Создайте или отредактируйте файл .mcp.json в корне проекта (или ~/.claude/mcp.json для глобального доступа).
2. 2 Перезапустите Claude Code — MCP-инструменты появятся автоматически: generate_report, generate_guide, list_reports.
3. 3 Попросите Claude сгенерировать отчёт: «Сгенерируй отчёт по проекту с результатами проверки» — Claude сам вызовет нужный инструмент и вернёт ссылку.

Конфигурация

Проектный конфиг

Файл .mcp.json в корне проекта — MCP-сервер доступен только в этом проекте:

{
  "mcpServers": {
    "reports": {
      "type": "sse",
      "url": "https://tpl.developing-site.ru/mcp/sse"
    }
  }
}

Глобальный конфиг

Файл ~/.claude/mcp.json — MCP-сервер доступен из любого проекта:

{
  "mcpServers": {
    "reports": {
      "type": "sse",
      "url": "https://tpl.developing-site.ru/mcp/sse"
    }
  }
}

Совместно с другими MCP-серверами

Если у вас уже есть другие серверы, просто добавьте "reports" в существующий mcpServers:

{
  "mcpServers": {
    "claude-code": {
      "command": "claude",
      "args": ["mcp", "serve"]
    },
    "reports": {
      "type": "sse",
      "url": "https://tpl.developing-site.ru/mcp/sse"
    }
  }
}

generate_report

Параметры

Возвращает

Строку с URL сгенерированного отчёта, путём к файлу, размером и статистикой.

Компо��енты отчёта

• Боковая панель — статистика (выполнено/частично/ошибки/тестов), навигация с цветными точками
• Карточки статистики — цветные плашки в шапке
• Статус-бейджи — Выполнено Частично Ошибка
• Шаги проверки — нумерованные с ожидаемым результатом
• E2E тесты — строки PASS/FAIL/SKIP для каждого теста
• Сводная таблица — тестовые файлы с итогами

generate_guide

Параметры

Возвращает

Строку с URL сгенерированной инструкции, путём к файлу, размером и числом разделов.

Компоненты инструкции

• Боковая панель — SVG-иконки для каждого раздела, блок данных доступа
• Хлебные крошки — путь навигации (WP Admin → Страницы → Главная)
• Таблицы полей — колонки «Поле» и «Описание»
• Пошаговые инструкции — нумерованные шаги с ожидаемым результатом
• Заметки — информация, предупреждения, результат
• Секции и подсекции — иерархическая структура документа

list_reports

Параметры: нет. Возвращает текстовый список файлов.

Модели данных

Все параметры инструментов используют типизированные модели. Ниже — полная схема каждой.

Step

Note

TestResult

CheckItem report

ItemGroup report

TestFile report

Credentials guide

FieldDesc guide

GuideSubsection guide

GuideSection guide

Дизайн-система

Цвета

Четыре семантических цвета, каждый в трёх вариантах (основной, фон, рамка). Автоматически переключаются между светлой и тёмной темой.

Светлая и тёмная тема

Оба шаблона (отчёт и инструкция) поддерживают светлую и тёмную тему. Пользователь может переключить тему кнопкой в боковой панели (солнце/луна), выбор сохраняется в localStorage.

Генерация с тёмной темой по умолчанию

Чтобы отчёт или инструкция открывались сразу в тёмной теме, передайте параметр dark: true:

{
  "project_name": "Мой Сайт",
  "project_url": "https://example.com",
  "date": "24 февраля 2026",
  "dark": true,
  "groups": [...]
}

{
  "project_name": "Мой Сайт",
  "admin_url": "https://example.com/wp-admin/",
  "date": "24 февраля 2026",
  "dark": true,
  "credentials": {...},
  "sections": [...]
}

Или попросите Claude на естественном языке:

Сгенерируй отчёт по проекту в тёмной теме.

Адаптивность

На экранах менее 900px боковая панель скрывается, контент занимает всю ширину.

Общие компоненты

• .sidebar — фиксированная левая панель (260px)
• .page-header + .summary-item — шапка с карточками статистики
• .steps + .step-n — нумерованные шаги
• .note-info/warn/error/success — цветные блоки-заметки
• .fields table — таблица полей
• .path + .path-arrow — хлебные крошки
• code — инлайн-код

Иконки

В инструкции администратора каждая секция может иметь SVG-иконку в боковой панели. Доступны 17 иконок из набора Lucide (16x16, контурные):

Примеры использования

Пример: простой отчёт

Попросите Claude сгенерировать отчёт, описав задачи и их статус. Claude автоматически вызовет generate_report:

Сгенерируй отчёт по проекту "Мой Сайт" (https://example.com).
Дата: 24 февраля 2026.

Блок 1 — Главная:
- 1.1 Hero-секция — выполнено
- 1.2 Навигация — выполнено
- 1.3 Футер — частично (не хватает ссылок на соцсети)

Блок 2 — Контакты:
- 2.1 Форма обратной связи — выполнено
- 2.2 Карта — ошибка (API ключ не работает)

Сделай в тёмной теме.

Пример: JSON вызова generate_report

Если нужно вызвать инструмент напрямую с конкретными данными:

{
  "project_name": "Мой Сайт",
  "project_url": "https://example.com",
  "date": "24 февраля 2026",
  "dark": true,
  "groups": [
    {
      "name": "Блок 1 — Главная",
      "items": [
        {
          "num": "1.1",
          "title": "Hero-секция",
          "status": "done",
          "description": "Слайдер с 3 слайдами, автопрокрутка",
          "steps": [
            {"text": "Открыть главную страницу", "expect": "Слайдер загружается"},
            {"text": "Подождать 5 секунд", "expect": "Слайд автоматически переключается"}
          ]
        },
        {
          "num": "1.2",
          "title": "Форма обратной связи",
          "status": "done",
          "tests": [
            {"name": "form.spec.ts > отправка формы", "status": "pass"},
            {"name": "form.spec.ts > валидация email", "status": "pass"}
          ]
        },
        {
          "num": "1.3",
          "title": "Карта",
          "status": "error",
          "note": {"type": "error", "text": "API ключ Яндекс.Карт истёк"}
        }
      ]
    }
  ],
  "test_summary": [
    {"file": "form.spec.ts", "status": "pass", "passed": 2, "total": 2}
  ]
}

Пример: простая инструкция

Попросите Claude сгенерировать инструкцию администратора, описав разделы и поля. Claude автоматически вызовет generate_guide:

Сгенерируй инструкцию администратора для проекта "Мой Сайт".
URL админки: https://example.com/wp-admin/
Логин: admin, пароль: mypassword123
Дата: 24 февраля 2026.

Разделы:

1. Управление страницами (иконка fileText)
   - 1.1 Главная страница
     Путь: WP Admin → Страницы → Главная
     Поля: Заголовок (основной текст hero), Подзаголовок (текст под заголовком)
     Шаги: Перейти в WP Admin → Страницы → Главная,
            Найти мета-бокс «Hero-секция»,
            Изменить текст и нажать «Обновить» → Изменения видны на сайте

2. Медиафайлы (иконка image, счётчик: 47)
   Шаги: Перейти в Медиафайлы → Добавить новый → Загрузить файл
   Совет: Рекомендуемый размер 1920x1080, формат WebP

3. Настройки калькулятора (иконка calculator)
   Путь: WP Admin → Настройки → Калькулятор
   Поля: API ключ (ключ для расчё��а), Валюта (RUB/USD/EUR)
   Важно: После изменения API ключа очистите кэш сайта

Пример: JSON вызова generate_guide

{
  "project_name": "Мой Сайт",
  "admin_url": "https://example.com/wp-admin/",
  "date": "24 февраля 2026",
  "dark": true,
  "credentials": {
    "url": "https://example.com/wp-admin/",
    "login": "admin",
    "password": "mypassword123"
  },
  "sections": [
    {
      "id": "pages",
      "title": "Управление страницами",
      "icon": "fileText",
      "description": "Редактирование контента страниц через мета-боксы.",
      "subsections": [
        {
          "num": "1.1",
          "title": "Главная страница",
          "path": ["WP Admin", "Страницы", "Главная"],
          "fields": [
            {"name": "Заголовок", "description": "Основной заголовок hero-секции"},
            {"name": "Подзаголовок", "description": "Текст под заголовком"}
          ],
          "steps": [
            {"text": "Перейдите в WP Admin → Страницы → Главная"},
            {"text": "Найдите мета-бокс «Hero-секция»"},
            {"text": "Измените текст и нажмите «Обновить»", "expect": "Изменения видны на сайте"}
          ]
        }
      ]
    },
    {
      "id": "media",
      "title": "Медиафайлы",
      "icon": "image",
      "count": 47,
      "steps": [
        {"text": "Перейдите в WP Admin → Медиафайлы"},
        {"text": "Загрузите изображение через «Добавить новый»", "expect": "Файл появляется в библиотеке"}
      ],
      "note": {"type": "info", "text": "Рекомендуемый размер изображений: 1920x1080px, формат WebP."}
    }
  ]
}