ТИЦЬ як API: підключення й використання

Як керувати редактором ТИЦЬ програмно з іншої веб-сторінки (iframe + postMessage) або з React-застосунку через ref. Повний довідник методів, подій, помилок і формату документа — довідником API. Інтерактивна пісочниця з живими запитами — https://tyts.vercel.app/embed/api.html, демо host-сторінки — https://tyts.vercel.app/embed/demo.html.

1. Підключення за пʼять хвилин

Потрібні дві речі: SDK на вашій сторінці і редактор, який SDK відкриє в iframe. Редактор уже викладений публічно, збирати нічого не треба.

SDK

npm i @3rtools/tyts-embed

import { TytsEmbed } from '@3rtools/tyts-embed';

Без збирача — класичний скрипт, який створює глобальний TytsEmbed:

<script src="https://unpkg.com/@3rtools/tyts-embed/dist/tyts-embed.js"></script>

Редактор

Публічна збірка: https://tyts.vercel.app/embed/. Вкажіть її в src.

<div id="tyts" style="min-height: 80vh"></div>
<script type="module">
  import { TytsEmbed } from '@3rtools/tyts-embed';

  const editor = TytsEmbed.create({
    container: '#tyts',
    src: 'https://tyts.vercel.app/embed/',
    onChange(doc, { dirty }) { saveButton.disabled = !dirty; },
    onError(err) { console.warn('tyts', err.code, err.message); },
  });

  await editor.init();
  await editor.loadImage(await TytsEmbed.fileToDataUrl(file));
</script>

Контейнер має мати явну висоту або min-height: SDK ставить iframe height: 100%, і в контейнері без висоти iframe буде 150px.

2. Що далі в роботі

Типовий цикл host-сторінки:

// користувач розставив виноски...
const doc = await editor.getDocument();          // JSON документа — зберігаєте у себе
await api.put(`/reports/${id}/collage`, doc);
await editor.markSaved();                        // далі onChange дає dirty:false

// готова картинка або PDF
const { dataUrl } = await editor.export('png', 2);   // 'png' | 'jpeg' | 'pdf'

// при наступному відкритті
await editor.loadDocument(doc);                  // або editor.init({ document: doc })

• onChange(doc, { dirty }) приходить після кожної зміни з дебаунсом 250 мс; dirty каже, чи є незбережені зміни відносно того, що ви завантажили або підтвердили через markSaved.
• Усі методи повертають проміси, які резолвляться відповіддю редактора або відхиляються { code, message } (timeout, invalid_document, origin_denied, …).
• Документ містить картинку як base64, тож зберігайте його за dirty, а не на кожен onChange.
• Рецепти (попередження про незбережене, завантаження файлу, PDF на сервер, кілька редакторів) — довіднику API, розділ 9.

3. Безпека, дані, власний хостинг

• Документ і картинка ходять лише між вашою сторінкою та iframe у браузері користувача (postMessage). На сервер ТИЦЬ нічого не надсилається; публічна збірка на Vercel — статичні файли.

• Публічний редактор приймає init з будь-якого origin без токена. Перший успішний init привʼязує сесію до origin вашої сторінки, повідомлення з інших вікон і origin-ів ігноруються.

• Якщо потрібно обмежити, хто може вбудовувати редактор, або працювати офлайн, зберіть і викладіть його самі (потрібен доступ до репозиторію):

  git clone <repo> tyts && cd tyts && npm install
  VITE_TYTS_EMBED_ALLOWED_ORIGINS=https://app.example,https://staging.example \
  VITE_TYTS_EMBED_TOKEN=change-me \
  npm run build:embed        # → build/embed/ — статичні файли, викласти будь-де
  

  VITE_TYTS_EMBED_ALLOWED_ORIGINS — origin-и, з яких дозволено init; VITE_TYTS_EMBED_TOKEN — секрет для init({ token }). Шляхи в збірці відносні, тека може лежати на іншому origin, ніж host-сторінка. Тоді в src вказуєте свою адресу замість https://tyts.vercel.app/embed/.

• SDK і збірка мають однакову версію протоколу (TytsEmbed.PROTOCOL); при невідповідності init відхиляється з protocol_mismatch.

4. Довідник SDK

TytsEmbed.create(options) → editor

Методи editor

Коди помилок

5. Протокол postMessage

Для host-ів без JS SDK (інша мова, власна обгортка). Host шле iframe.contentWindow.postMessage(msg, origin), редактор відповідає window.parent.postMessage(...). Повідомлення з requestId отримують відповідь із тим самим requestId. Редактор приймає повідомлення лише від батьківського вікна.

Редактор сам надсилає:

• { type: 'tyts:ready', protocol: 1 } — один раз після завантаження; init, надісланий раніше, host має відкласти до цього моменту.
• { type: 'tyts:change', document, dirty } — після init, з дебаунсом.
• { type: 'tyts:error', requestId?, error: { code, message } }.

Повні JSON-приклади і мінімальний клієнт без SDK — довіднику API, розділ 6.

6. Формат документа

interface TytsDocument {
  version: 1;
  backgroundImage: string;                  // data: URL
  imageSize: { w: number; h: number };      // логічний розмір полотна
  sourceImageSize: { w: number; h: number } | null;
  pins: Pin[];                              // повний опис полів — розділ 5
  cardPositions: Record<string, CardPosition>; // позиції карток за pin.id; порожньо — редактор розкладе сам
  settings?: { fontId?: 'road-ui' | 'uaf-sans'; strokeWidthScale?: number };
  meta?: { sourceUrl?: string; sourceTitle?: string; capturedAt?: number };
}

Мінімальний пін:

{
  "id": "pin-1", "label": 1, "color": "#E63946",
  "description": "<p>Техніка</p>", "descPos": "below",
  "image": null, "imageAspect": null,
  "anchor": { "type": "point", "x": 320, "y": 180 }
}

anchor.type: point, rectangle, ellipse, polygon, polyline, arrow, text, compass, numbering, standalone, linked — поля кожного з прикладами в довіднику API, розділ 7. Координати — в image space (пікселі imageSize).

Документ, що не проходить валідацію, відхиляється з invalid_document, редактор при цьому не змінюється.

7. React без iframe

import { useRef } from 'react';
import { CollageBuilder } from './components/CollageBuilder';
import type { TytsEditorHandle } from './embed/types';

function Report() {
  const editor = useRef<TytsEditorHandle>(null);
  return (
    <>
      <CollageBuilder
        ref={editor}
        mode="embed"                       // без autosave і без localStorage
        initialDocument={savedDoc}
        onChange={(doc, { dirty }) => setDirty(dirty)}
      />
      <button onClick={async () => download(await editor.current!.exportPdf())}>PDF</button>
    </>
  );
}

TytsEditorHandle має ті самі методи, що й SDK (loadDocument, loadImage, getDocument, exportImage, exportPdf, markSaved, reset). Пакет @3rtools/tyts-editor поки не публікується; пакет @3rtools/tyts-editor поки не публікується.

8. Для агентів

MCP-сервер @3rtools/tyts-mcp дає ті самі можливості LLM-агентам: claude mcp add tyts -- npx -y @3rtools/tyts-mcp. Деталі — довідник API, розділ 11, і сторінка MCP.

9. Як перевірити

• Пісочниця: https://tyts.vercel.app/embed/api.html — кожна команда з описом, запитом, відповіддю й логом повідомлень.
• Демо host-сторінки: https://tyts.vercel.app/embed/demo.html.
• Свій host без збірки: скопіюйте приклад із демо і замініть src на свій.

ТИЦЬ Embed API — довідник

Описано Клодом

Повний опис програмного інтерфейсу редактора: JS SDK, події, помилки, сирий postMessage-протокол, формат документа і React-handle. Як підключити SDK і викласти редактор — встановлення. Інтерактивна версія з живими запитами — api.html у embed-збірці.

Зміст

1. Огляд
2. Життєвий цикл сесії
3. SDK TytsEmbed
4. Події
5. Помилки
6. Протокол postMessage
7. Формат документа TytsDocument
8. React: TytsEditorHandle
9. Рецепти
10. Обмеження
11. MCP для агентів

1. Огляд

Редактор ТИЦЬ можна вбудувати трьома способами, і всі три дають один і той самий набір операцій:

Операції: init, loadImage, loadDocument, getDocument, export, markSaved, reset. Події від редактора: ready, change, error.

Версія протоколу — 1 (TytsEmbed.PROTOCOL у пакеті @3rtools/tyts-embed). SDK і бандл мають бути однієї версії, інакше init відхиляється з protocol_mismatch.

2. Життєвий цикл сесії

host                                   iframe (редактор)
 │  create() → вставляє <iframe>        │
 │◄──────────── tyts:ready ─────────────│  бандл завантажився, слухає
 │─── tyts:init {token?, document?} ───►│  перевірка origin і токена
 │◄──────── tyts:initialized ───────────│  сесію прив'язано до origin host-а
 │─── tyts:loadImage / loadDocument ───►│
 │◄──────────── tyts:done ──────────────│
 │◄──────── tyts:change {dirty} ────────│  після кожної зміни, з дебаунсом
 │─── tyts:getDocument / export ───────►│
 │◄──── tyts:document / exportResult ───│
 │─── tyts:markSaved ──────────────────►│  стан підтверджено як збережений
 │◄──────── tyts:change {dirty:false} ──│

• До init редактор відповідає на будь-яку команду помилкою not_initialized.
• Після init приймаються лише повідомлення від батьківського вікна і з того ж origin, що й init.
• ready приходить один раз. SDK відкладає всі запити до нього, тож методи можна викликати одразу після create().
• Повторний init у тій самій сесії дозволений (наприклад, щоб передати новий документ).

3. SDK TytsEmbed

Підключення: npm i @3rtools/tyts-embed і import { TytsEmbed } from '@3rtools/tyts-embed', або класичний <script src=".../tyts-embed.js"></script> (з build/embed/ або https://unpkg.com/@3rtools/tyts-embed/dist/tyts-embed.js), який створює глобальний обʼєкт TytsEmbed. Типи — в пакеті (index.d.ts).

TytsEmbed.create(options) → editor

Вставляє iframe у контейнер і починає слухати відповіді.

const editor = TytsEmbed.create({
  container: '#tyts',
  src: 'https://app.example/tyts/embed/',
  onChange(doc, { dirty }) { setDirty(dirty); },
  onError(err) { toast(err.message); },
});

TytsEmbed.fileToDataUrl(file) → Promise<string>

Допоміжна функція: File/Blob → data: URL для loadImage.

editor.init(config?) → Promise<void>

Відкриває сесію. Резолвиться після tyts:initialized.

Можливі помилки: origin_denied, invalid_token, protocol_mismatch, invalid_document, init_failed, timeout.

await editor.init({ token: 'change-me', document: savedDoc });

editor.loadImage(dataUrl) → Promise<void>

Нове фонове зображення. Усі піни й картки скидаються, історія undo очищається, стан стає чистим.

Помилки: handler_error з повідомленням Failed to load image, якщо зображення не декодується.

input.onchange = async () => {
  await editor.loadImage(await TytsEmbed.fileToDataUrl(input.files[0]));
};

editor.loadDocument(document) → Promise<void>

Відновлює документ (див. розділ 7). Замінює все: зображення, піни, картки, settings. Стан стає чистим.

Приймає також файл проєкту .tyts як є (конверт { format: 'tyts-collage', document }, див. розділ 7) і автосейв-чернетку ТИЦЬ (version: 2 з savedAt).

Помилки: invalid_document — документ не пройшов валідацію, редактор не змінився.

editor.getDocument() → Promise<TytsDocument | null>

Поточний стан. null, якщо зображення не завантажене. Це те, що host зберігає у себе.

editor.export(format, scale?) → Promise<{ format, mime, dataUrl }>

Рендерить готовий колаж.

Результат: mime — image/png, image/jpeg або application/pdf; dataUrl — вміст. Таймаут 120 с. Помилки: export_failed.

const { dataUrl } = await editor.export('png', 2);
const blob = await (await fetch(dataUrl)).blob();

editor.markSaved() → Promise<void>

Поточний стан вважати збереженим: наступний onChange прийде з dirty: false, і dirty знову стане true лише після нової зміни. Викликати після того, як host успішно зберіг результат getDocument().

editor.reset() → Promise<void>

Порожній редактор: без зображення, пінів, історії.

editor.destroy()

Знімає слухачі й видаляє iframe. Незавершені проміси відхиляються з destroyed.

Таймаути

4. Події

dirty рахується від «базового» стану. Базовим стає:

• стан одразу після loadImage, loadDocument, init({ document }) (плюс автоматична розкладка карток, яку редактор робить у перші 150 мс);
• стан на момент markSaved().

5. Помилки

Кожна помилка — обʼєкт { code, message }.

6. Протокол postMessage

Для host-ів без SDK. Host надсилає у iframe.contentWindow.postMessage(message, editorOrigin), редактор відповідає window.parent.postMessage(message, hostOrigin). Кожен запит із requestId отримує рівно одну відповідь із тим самим requestId: результат або tyts:error.

Правила безпеки з боку редактора:

• приймаються лише повідомлення, у яких event.source === window.parent;
• до init — лише tyts:init, і лише з дозволеного origin;
• після init — лише з origin, що зробив init;
• tyts:ready іде з targetOrigin: '*' (без даних) або на кожен дозволений origin; усе інше — лише на origin сесії.

Host → редактор

// init
{ "type": "tyts:init", "protocol": 1, "requestId": "r1", "token": "change-me", "document": { /* TytsDocument, необовʼязково */ } }
// відповідь
{ "type": "tyts:initialized", "requestId": "r1", "protocol": 1 }

// loadImage
{ "type": "tyts:loadImage", "requestId": "r2", "dataUrl": "data:image/jpeg;base64,..." }
{ "type": "tyts:done", "requestId": "r2" }

// loadDocument
{ "type": "tyts:loadDocument", "requestId": "r3", "document": { /* TytsDocument */ } }
{ "type": "tyts:done", "requestId": "r3" }

// getDocument
{ "type": "tyts:getDocument", "requestId": "r4" }
{ "type": "tyts:document", "requestId": "r4", "document": { /* TytsDocument або null */ } }

// export
{ "type": "tyts:export", "requestId": "r5", "format": "png", "scale": 2 }
{ "type": "tyts:exportResult", "requestId": "r5", "format": "png", "mime": "image/png", "dataUrl": "data:image/png;base64,..." }

// markSaved
{ "type": "tyts:markSaved", "requestId": "r6" }
{ "type": "tyts:done", "requestId": "r6" }

// reset
{ "type": "tyts:reset", "requestId": "r7" }
{ "type": "tyts:done", "requestId": "r7" }

requestId для loadImage, loadDocument, markSaved, reset необовʼязковий; без нього відповіді tyts:done не буде. Для getDocument і export він обовʼязковий.

Редактор → host без запиту

{ "type": "tyts:ready", "protocol": 1 }
{ "type": "tyts:change", "document": { /* TytsDocument */ }, "dirty": true }
{ "type": "tyts:error", "requestId": "r3", "error": { "code": "invalid_document", "message": "Invalid document" } }

Мінімальний клієнт без SDK

const iframe = document.querySelector('iframe');
const editorOrigin = new URL(iframe.src).origin;
const pending = new Map();

window.addEventListener('message', (e) => {
  if (e.source !== iframe.contentWindow || e.origin !== editorOrigin) return;
  const m = e.data;
  if (m.type === 'tyts:change') return render(m.document, m.dirty);
  const p = pending.get(m.requestId);
  if (!p) return;
  pending.delete(m.requestId);
  m.type === 'tyts:error' ? p.reject(m.error) : p.resolve(m);
});

function request(message) {
  const requestId = crypto.randomUUID();
  return new Promise((resolve, reject) => {
    pending.set(requestId, { resolve, reject });
    iframe.contentWindow.postMessage({ ...message, requestId }, editorOrigin);
  });
}

await request({ type: 'tyts:init', protocol: 1 });
await request({ type: 'tyts:loadImage', dataUrl });
const { document: doc } = await request({ type: 'tyts:getDocument' });

7. Формат документа TytsDocument

Типи постачаються з пакетом @3rtools/tyts-embed (index.d.ts): TytsDocument, TytsPin, TytsAnchor.

interface TytsDocument {
  version: 1;
  backgroundImage: string;                       // data: URL фонового зображення
  imageSize: { w: number; h: number };           // логічний розмір полотна, у ньому всі координати
  sourceImageSize: { w: number; h: number } | null; // розмір оригіналу до масштабування
  pins: Pin[];
  cardPositions: Record<string, CardPosition>;   // ключ — pin.id; порожній обʼєкт = авто-розкладка
  settings?: { fontId?: 'road-ui' | 'uaf-sans'; strokeWidthScale?: number };
  meta?: { sourceUrl?: string; sourceTitle?: string; capturedAt?: number };
}

interface CardPosition { x: number; y: number; width: number; height: number }

Файл проєкту .tyts

Редактор зберігає й відкриває колажі як файли («Зберегти у файл» і «Відкрити» зліва в хедері, перетягування у вікно). Це той самий TytsDocument у JSON-конверті:

interface TytsCollageFile {
  format: 'tyts-collage';
  version: 1;
  appVersion: string;   // версія ТИЦЬ, що зберегла файл; на розбір не впливає
  savedAt: number;      // мс
  document: TytsDocument;
}

Host може віддати вміст файлу в loadDocument без розпакування, а getDocument() — загорнути в такий конверт і запропонувати користувачу як завантаження: вебверсія відкриє його. В embed-режимі кнопки файлу в редакторі є, а «Останні проєкти» й чернетка в IndexedDB вимкнені — сховищем керує host.

Pin

Anchor

Усі координати — пікселі в просторі imageSize.

Мінімальний повний документ:

{
  "version": 1,
  "backgroundImage": "data:image/jpeg;base64,...",
  "imageSize": { "w": 960, "h": 600 },
  "sourceImageSize": null,
  "pins": [
    {
      "id": "pin-1", "label": 1, "color": "#F0462F",
      "description": "<p>Техніка</p>", "descPos": "below",
      "image": null, "imageAspect": null,
      "anchor": { "type": "rectangle", "x": 130, "y": 360, "width": 220, "height": 130 }
    }
  ],
  "cardPositions": {}
}

Валідація

Документ відхиляється (invalid_document), якщо:

• version не 1 (або не 1/2 для автосейв-чернетки з savedAt);
• backgroundImage не рядок, що починається з data:;
• imageSize не пара скінченних чисел; sourceImageSize не пара і не null;
• будь-який пін без обовʼязкового поля з таблиці вище, label < 1, або anchor невідомого типу чи без потрібних полів;
• cardPositions не обʼєкт, або якась позиція не має x, y, width, height.

Невідомі додаткові поля ігноруються, документ не змінюється при відхиленні.

8. React: TytsEditorHandle

Для React-застосунку, де редактор у тому ж бандлі (без iframe і postMessage).

import { useRef } from 'react';
import { CollageBuilder } from './components/CollageBuilder';
import type { TytsEditorHandle } from './embed/types';

const editor = useRef<TytsEditorHandle>(null);

<CollageBuilder
  ref={editor}
  mode="embed"                // autosave вимкнено, localStorage не використовується
  initialDocument={doc}       // застосовується один раз при монтуванні
  features={{ autosave: false }}
  onReady={() => {}}          // лише в iframe-режимі
  onChange={(doc, { dirty }) => {}}
  onError={(err) => {}}
/>

Семантика dirty така сама, як у SDK. Пропи embedConfig (allowedOrigins, token) мають сенс лише для iframe-режиму.

9. Рецепти

Зберегти й відновити

saveButton.onclick = async () => {
  const doc = await editor.getDocument();
  await api.put(`/reports/${id}/collage`, doc);   // ваше сховище
  await editor.markSaved();
};

// при відкритті звіту
const doc = await api.get(`/reports/${id}/collage`);
await editor.init({ document: doc });             // або editor.loadDocument(doc) після init

Попередження про незбережені зміни

let dirty = false;
TytsEmbed.create({ ..., onChange(_, meta) { dirty = meta.dirty; } });
window.addEventListener('beforeunload', (e) => { if (dirty) e.preventDefault(); });

Завантажити PNG як файл

const { dataUrl } = await editor.export('png', 2);
const a = Object.assign(document.createElement('a'), { href: dataUrl, download: 'collage.png' });
a.click();

Надіслати PDF на сервер

const { dataUrl } = await editor.export('pdf');
const blob = await (await fetch(dataUrl)).blob();
await fetch('/upload', { method: 'POST', body: blob, headers: { 'Content-Type': 'application/pdf' } });

Створити виноски програмно

Документ — звичайний JSON, тож host може згенерувати піни сам і віддати їх через loadDocument; cardPositions: {} змусить редактор розкласти картки. Повноцінний API операцій без документа («постав прямокутник тут») — у планах.

Кілька редакторів на сторінці

Кожен TytsEmbed.create — незалежна сесія зі своїм iframe. Обробник message фільтрує за event.source, тож інстанси не перетинаються.

Обробка помилок

try {
  await editor.loadDocument(doc);
} catch (err) {
  if (err.code === 'invalid_document') showValidationHint();
  else if (err.code === 'timeout') reloadEditor();
  else throw err;
}

10. Обмеження

• Документ містить зображення як base64, тож getDocument/onChange можуть важити мегабайти. Для великих знімків зберігайте документ рідше (за dirty, а не на кожен onChange).
• onChange іде з дебаунсом 250 мс і лише після init; зміни до init приходять однією подією після нього.
• Координати після кропу в редакторі перераховуються редактором; host отримує вже нові imageSize і піни.
• export('pdf') — одна сторінка A4 з вписаним зображенням; масштаб не застосовується.
• Налаштування settings (шрифт, товщина) в embed-режимі зберігаються в localStorage origin-у бандла так само, як у вебверсії; документ, переданий через loadDocument, їх перезаписує.
• Історія undo не переживає loadDocument/loadImage/reset.

11. MCP для агентів

Пакет @3rtools/tyts-mcp дає LLM-агентам той самий API як MCP-інструменти: tyts_render (картинка + анотації → PNG/JPEG/PDF з preview), tyts_image_info, tyts_validate, ресурс tyts://docs/annotations і промпт annotate-image. Координати анотацій — у пікселях оригінальної картинки; сервер сам переводить їх у простір редактора.

claude mcp add tyts -- npx -y @3rtools/tyts-mcp

Деталі — сторінка MCP.

@3rtools/tyts-mcp

MCP-сервер редактора ТИЦЬ (Tyts): агент дає картинку й список анотацій, отримує готовий PNG/JPEG/PDF з нумерованими виносками. Працює через headless Chrome із вбудованою збіркою редактора, тож результат піксель-у-піксель такий, як у застосунку.

MCP server for the Tyts annotated-collage editor: an agent passes an image plus annotations and gets a rendered PNG/JPEG/PDF back.

Вимоги

• Node.js ≥ 20
• Google Chrome, Chromium або Edge на машині (пакет не завантажує Chromium). Якщо браузер у нестандартному місці — TYTS_CHROME_PATH=/шлях/до/chrome.

Підключення

Claude Code:

claude mcp add tyts -- npx -y @3rtools/tyts-mcp

Будь-який MCP-клієнт (Cursor, Claude Desktop, .mcp.json у проєкті):

{
  "mcpServers": {
    "tyts": {
      "command": "npx",
      "args": ["-y", "@3rtools/tyts-mcp"],
      "env": { "TYTS_OUTPUT_DIR": "./collages" }
    }
  }
}

Змінні середовища: TYTS_OUTPUT_DIR (куди класти результати; типово тимчасова тека), TYTS_CHROME_PATH, TYTS_EDITOR_DIR (своя збірка редактора замість вбудованої).

Інструменти

tyts_render

Головний інструмент. Вхід:

Відповідь: JSON { path, bytes, width, height, imageSize, sourceImageSize, pins, document } і preview.

{
  "image": "./photo.jpg",
  "pins": [
    { "type": "rectangle", "x": 130, "y": 360, "width": 220, "height": 130, "text": "Техніка" },
    { "type": "point", "x": 460, "y": 460, "text": "Дорога", "color": "#0088FF" },
    { "type": "arrow", "start": { "x": 300, "y": 120 }, "end": { "x": 520, "y": 260 }, "text": "Напрямок руху" }
  ],
  "width": 1600
}

Типи фігур — усі, що є в редакторі: point, rectangle, ellipse, polygon, polyline, arrow, text (з point — «точка з текстом»), compass, standalone, numbering, image (картинка поверх фото), redact (розмиття / пікселізація / заливка), linked (ще одна виноска до тієї ж фігури).

Картка-виноска будь-якого піна: text, photo (фото в картці — шлях, URL або data URL), textPosition (текст над / під фото), theme, bold / italic / underline / strike, fontSize, textColor, cardBackground (none — прозорий), card (явна позиція), hideCallout, bends (злами лінії). Фігура: color, strokeStyle, fillStyle, strokeWidth.

Кілька об'єктів на одну виноску: attachTo: "<id>" у фігури (point, polygon, polyline, rectangle, ellipse, arrow) — своєї картки в неї немає, лінія йде до картки піна з цим id.

Картки без card MCP розкладає так само, як редактор (колонки від правого краю), але картка з фото вища — під пропорції фото. Поля кожного типу — у ресурсі tyts://docs/annotations (агент читає його сам).

{
  "image": "./scene.jpg",
  "pins": [
    { "id": "tech", "type": "rectangle", "x": 130, "y": 360, "width": 220, "height": 130, "text": "Техніка", "photo": "./closeup.jpg" },
    { "type": "linked", "to": "tech", "text": "Друга виноска до тієї ж рамки" },
    { "type": "redact", "x": 40, "y": 40, "width": 120, "height": 60, "mode": "pixelate" }
  ],
  "crop": { "x": 0, "y": 100, "width": 1600, "height": 900 },
  "stamp": { "image": "./logo.png", "corner": "se" }
}

Не вміє лише часткове форматування тексту (жирне окреме слово): стиль задається на всю картку.

tyts_image_info

{ image } → { width, height, mime, editorSize }. Викликати першим, щоб знати систему координат.

tyts_validate

{ document } → { ok: true } або { ok: false, code, message } без рендера.

Ресурс і промпт

• tyts://docs/annotations — формат анотацій, палітра, поради.
• Промпт annotate-image(image, task?) — покрокова інструкція агенту: розмір → рендер → перевірка preview.

Як це працює

Сервер піднімає статику з вбудованою embed-збіркою ТИЦЬ на 127.0.0.1, відкриває її в headless Chrome і керує редактором через postMessage-протокол @3rtools/tyts-embed. Браузер стартує ліниво на першому виклику і закривається після 5 хв без роботи. Файли нікуди не надсилаються.

Перевірити, що працює

Без агента — запустити сервер напряму (у stderr має зʼявитися [tyts-mcp] ready):

npx -y @3rtools/tyts-mcp

Подивитися інструменти, ресурс і промпт та викликати їх вручну:

npx @modelcontextprotocol/inspector npx -y @3rtools/tyts-mcp

Через агента: tyts_image_info на будь-якому фото має повернути розмір у пікселях, далі tyts_render з кількома pins — шлях до файлу і preview.

Ліцензія

Apache-2.0. Шрифт Road UI — CC BY-ND 4.0 (див. NOTICE).