![MCP Typography Server Banner](./banner.svg)

# MCP Typography Audit Server

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

> **Ядро проекта:** Вся логика высокоточной веб-типографики, переносов и микровыравнивания базируется на библиотеке [Justif](https://github.com/lyallcooper/justif) от [Lyall Cooper](https://github.com/lyallcooper). Данный 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. Клонирование и установка зависимостей
```bash
git clone https://github.com/kobaltgit/mcp-typography-server.git
cd mcp-typography-server

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

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

### 2. Сборка проекта
```bash
npm run build
```
Команда компилирует TypeScript в исполняемый JavaScript-файл в папке `dist/index.js`.

---

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

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

[MCP Inspector](https://github.com/modelcontextprotocol/inspector) — официальный веб-интерфейс для отладки MCP-инструментов.

1. Запустите инспектор из корня проекта:
   ```bash
   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`**:
     ```html
     <h2>Проверка типографики Кнута — Пласса</h2>
     <p>
       «Качественный набор текста — это баланс между формой и смыслом», — писали классики графического дизайна.
       В обычном браузере стандартное выравнивание по ширине часто создает неприятные белые пустоты («реки в наборе»),
       которые сильно утомляют глаз читателя.
     </p>
     <p>
       Библиотека Justif применяет алгоритм из типографской системы TeX. Сложные составные слова,
       такие как <em>высококвалифицированный</em>, <em>сельскохозяйственный</em> или
       <em>достопримечательность</em>, делятся строго по правилам русской орфографии.
     </p>
     ```
5. Нажмите **Run Tool**. В окне появится отчёт по разметке и скриншот отрендеренной страницы с идеальным выравниванием.

---

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

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

```bash
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:
```json
{
  "mcpServers": {
    "typography-auditor": {
      "command": "node",
      "args": [
        "/абсолютный/путь/к/mcp-typography-server/dist/index.js"
      ]
    }
  }
}
```

#### Windows:
*(Обратите внимание на экранирование обратных слэшей `\\`)*:
```json
{
  "mcpServers": {
    "typography-auditor": {
      "command": "node",
      "args": [
        "C:\\path\\to\\mcp-typography-server\\dist\\index.js"
      ]
    }
  }
}
```

---

### 2. Cursor / Windsurf

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

```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](https://github.com/lyallcooper/justif)** — автор [Lyall Cooper](https://github.com/lyallcooper). Великолепная реализация алгоритма Кнута — Пласса, микротипографики и оптического выравнивания полей для современного веба.

---

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

| Ошибка | Причина | Решение |
| :--- | :--- | :--- |
| `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