MCP Typography Audit Server

Сервер протокола Model Context Protocol (MCP), позволяющий AI-агентам (Claude, Cursor, Windsurf и др.) выполнять полиграфический аудит вёрстки и проверять вёрстку с книжным выравниванием текста по алгоритму Кнута — Пласса (как в издательской системе $\mathrm{\TeX}$).

Ядро проекта: Вся логика высокоточной веб-типографики, переносов и микровыравнивания базируется на библиотеке Justif от Lyall Cooper. Данный MCP-сервер переносит её возможности в автономную среду headless-браузера Playwright для работы с AI-агентами.

---

📖 Возможности

• Книжная типографика для агента: Реализация алгоритма Кнута — Пласса (Knuth-Plass line breaking) устраняет построчные «реки» пробелов, выравнивает полосу набора, включает микротипографику и висячую пунктуацию.
• Поддержка переносов (Hyphenation): Корректные переносы длинных слов по слогам (включая русский язык ru и английский en-us).
• Визуальная обратная связь (Vision-in-the-loop): Сервер отдаёт скриншот страницы прямо в формате MCP image/png. Мультимодальные модели (Claude 3.5/3.7, GPT-4o) могут визуально оценить вёрстку и скорректировать CSS.
• Анализ разметки: Автоматический перехват ошибок JavaScript в консоли браузера, проверка наличия обязательного атрибута lang и тест адаптивности под разную ширину контейнера.

---

🛠️ Установка и сборка

1. Клонирование и установка зависимостей

git clone https://github.com/kobaltgit/mcp-typography-server.git
cd mcp-typography-server

# Установка NPM-зависимостей
npm install

# Установка браузера Chromium для Playwright (обязательно)
npx playwright install chromium

2. Сборка проекта

npm run build

Команда компилирует TypeScript в исполняемый JavaScript-файл в папке dist/index.js.

---

🧪 Тестирование сервера

Вариант 1. Интерактивная проверка через MCP Inspector

MCP Inspector — официальный веб-интерфейс для отладки MCP-инструментов.

1. Запустите инспектор из корня проекта:

   npx @modelcontextprotocol/inspector node dist/index.js

2. Откройте в браузере ссылку, которую выведет терминал (вида http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...).
3. В интерфейсе:
   • Убедитесь, что статус соединения — Connected (зелёный индикатор).
   • Перейдите во вкладку Tools и нажмите List Tools.
   • Выберите инструмент audit_typography.
4. Заполните тестовые поля:
   • lang: ru
   • width: 700
   • html:

     <h2>Проверка типографики Кнута — Пласса</h2>
     <p>
       «Качественный набор текста — это баланс между формой и смыслом», — писали классики графического дизайна.
       В обычном браузере стандартное выравнивание по ширине часто создает неприятные белые пустоты («реки в наборе»),
       которые сильно утомляют глаз читателя.
     </p>
     <p>
       Библиотека Justif применяет алгоритм из типографской системы TeX. Сложные составные слова,
       такие как <em>высококвалифицированный</em>, <em>сельскохозяйственный</em> или
       <em>достопримечательность</em>, делятся строго по правилам русской орфографии.
     </p>

5. Нажмите Run Tool. В окне появится отчёт по разметке и скриншот отрендеренной страницы с идеальным выравниванием.

---

Вариант 2. Автоматический тест через скрипт (test.js)

Запустите тестовый клиент в терминале:

node test.js

Скрипт подключится к серверу через stdio, выполнит тестовый запрос и сохранит результат в файл test-result.png в корне проекта.

---

🔌 Подключение к AI-клиентам

1. Claude Desktop

Откройте файл конфигурации:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Добавьте конфигурацию сервера:

macOS / Linux:

{
  "mcpServers": {
    "typography-auditor": {
      "command": "node",
      "args": [
        "/абсолютный/путь/к/mcp-typography-server/dist/index.js"
      ]
    }
  }
}

Windows:

(Обратите внимание на экранирование обратных слэшей \\):

{
  "mcpServers": {
    "typography-auditor": {
      "command": "node",
      "args": [
        "C:\\path\\to\\mcp-typography-server\\dist\\index.js"
      ]
    }
  }
}

---

2. Cursor / Windsurf

В корне вашего разрабатываемого веб-проекта создайте или отредактируйте файл .cursor/mcp.json:

{
  "mcpServers": {
    "typography-auditor": {
      "command": "node",
      "args": [
        "/абсолютный/путь/к/mcp-typography-server/dist/index.js"
      ]
    }
  }
}

---

🤖 Пример использования с агентом

После подключения инструмента агенту доступен тул audit_typography.

Пример промпта:

«Сверстай мне адаптивный блок статьи о пользе чтения на русском языке. Примени алгоритм Justif для выравнивания по ширине. Проверь вёрстку через инструмент audit_typography на ширине 375px (мобилка) и 750px (десктоп). Если на скриншоте увидишь неудачные переносы или разрывы строк — скорректируй стили».

Что произойдёт под капотом:

1. Агент генерирует HTML/CSS код.
2. Вызывает audit_typography с кодом статьи.
3. Сервер через Playwright рендерит страницу, применяет Justif и делает скриншот.
4. Агент получает скриншот, анализирует его с помощью Vision и отдаёт вам проверенный результат.

---

🙏 Основа проекта и благодарности (Credits)

Этот MCP-сервер был бы невозможен без проекта:

• Justif — автор Lyall Cooper. Великолепная реализация алгоритма Кнута — Пласса, микротипографики и оптического выравнивания полей для современного веба.

---

⚠️ Частые вопросы и отладка

Ошибка	Причина	Решение
Executable doesn't exist at ... playwright	Не скачан браузер Chromium	Выполните команду npx playwright install chromium.
Cannot find name 'process' при сборке	Особенности типизации ES-модулей	Убедитесь, что в src/index.ts добавлен import process from "node:process";, а в tsconfig.json указано "types": ["node"].
Сервер не отвечает или ломается JSON-RPC	Вывод лишнего текста в stdout	В коде сервера для логов используйте только console.error(), так как console.log() ломает канал обмена протокола stdio.

---

📄 Лицензия

MIT