# pasteToPrint MCP Server

Lokálny MCP server sprístupňuje bezpečný AI Builder nad Document API v2.
AI klient nemusí poznať HTTP endpointy a nedostane prístup k API tokenu.
Štruktúrovaný vstup používa **PTDF 1.0**, verejný názov existujúceho Document
Schema v1 s nezmeneným wire identifikátorom `ptp.document/1`.

Server používa transport `stdio` a poskytuje šesť nástrojov:

- `list_templates` – vráti aktuálny Template Catalog v1,
- `get_document_schema` – vráti publikovanú JSON Schema Draft 2020-12,
- `validate_document` – lokálne overí a normalizuje PTDF bez vytvorenia session,
- `create_document` – vytvorí dočasnú editorovú session zo štruktúrovaných
  blokov PTDF 1.0,
- `update_document` – nahradí obsah a/alebo zmení práva dočasnej session,
- `get_document_links` – obnoví oddelený editorový a read-only odkaz.

Nástroj nevykonáva tlač, PDF export ani kliknutie v používateľskom rozhraní.
Výsledkom `create_document` je `editorUrl` pre úpravy a `viewUrl` pre
zobrazenie. Spravovaný editovateľný PTDF sa môže automaticky vložiť iba do
úplne prázdneho editora; aplikácia vtedy zobrazí viditeľné oznámenie a
jednokrokové `Späť`. Neprázdny editor, read-only session a všetky ostatné
importné cesty naďalej vyžadujú voľbu `Pridať`, `Nahradiť` alebo `Zrušiť`.

## Požiadavky a inštalácia

- Node.js 20 alebo novší,
- dostupné Document API v2,
- voliteľný API token so scope `document:create`.

```powershell
cd C:\laragon\www\pasteToPrint\integrations\mcp
npm.cmd ci --ignore-scripts
npm.cmd test
```

Server sa dá spustiť priamo:

```powershell
$env:PASTETOPRINT_API_BASE_URL = "https://www.pastetoprint.com"
$env:PASTETOPRINT_API_TOKEN = "ptp_ai_..."
node C:\laragon\www\pasteToPrint\integrations\mcp\src\server.js
```

Pri `stdio` transporte nevypisuje nič na štandardný výstup okrem MCP správ.
Prevádzkové chyby zapisuje iba na štandardný chybový výstup.

## Konfigurácia MCP klienta

Do konfigurácie klienta pridajte lokálny proces. Cesty v JSON na Windows
obsahujú zdvojené spätné lomky:

```json
{
  "mcpServers": {
    "pastetoprint": {
      "command": "node",
      "args": [
        "C:\\laragon\\www\\pasteToPrint\\integrations\\mcp\\src\\server.js"
      ],
      "env": {
        "PASTETOPRINT_API_BASE_URL": "https://www.pastetoprint.com",
        "PASTETOPRINT_API_TOKEN": "ptp_ai_..."
      }
    }
  }
}
```

Presné miesto konfigurácie závisí od konkrétneho MCP klienta. Po zmene
konfigurácie klienta reštartujte a overte, že vidí nástroje
`list_templates`, `get_document_schema`, `validate_document`, `create_document`,
`update_document` a `get_document_links`.

## Premenné prostredia

| Premenná | Predvolená hodnota | Význam |
| --- | --- | --- |
| `PASTETOPRINT_API_BASE_URL` | `https://www.pastetoprint.com` | Základná URL API. HTTP je povolené iba pre loopback testovanie. |
| `PASTETOPRINT_API_TOKEN` | bez tokenu | Bearer token pre API v2. Token zostáva iba v procese MCP servera. |
| `PASTETOPRINT_DOCUMENT_TTL` | podľa API tieru | Predvolená požadovaná TTL v sekundách, 60 až 604800. |
| `PASTETOPRINT_REQUEST_TIMEOUT_MS` | `15000` | Timeout jednej API požiadavky, maximálne 120000 ms. |
| `PASTETOPRINT_MAX_RESPONSE_BYTES` | `131072` | Maximálna prijatá JSON odpoveď, najviac 1 MiB. |

Bez tokenu funguje server v anonymnom režime s maximálnou TTL 15 minút.
Tokeny a ich tiery sa konfigurujú podľa
[`DOCUMENT-API-AUTH.md`](DOCUMENT-API-AUTH.md).

## `create_document`

Nástroj prijíma:

- `title`, `locale`, `paper` a `template`,
- povinné pole s 1 až 500 sémantickými `blocks`,
- voliteľné `ttlSeconds`,
- voliteľný `idempotencyKey`.

`schemaVersion: ptp.document/1` doplní MCP server automaticky. HTML ani CSS
nie sú vstupnými poľami. Ak klient neposkytne `idempotencyKey`, server vytvorí
nový náhodný kľúč. Pri opakovaní rovnakého logického vytvorenia má klient
použiť rovnaký vlastný kľúč.

Príklad argumentov:

```json
{
  "title": "Objednávka revíznych prác",
  "locale": "sk-SK",
  "paper": {
    "size": "A4",
    "orientation": "portrait"
  },
  "template": "order",
  "blocks": [
    {
      "type": "heading",
      "level": 1,
      "text": "Objednávka revíznych prác"
    },
    {
      "type": "paragraph",
      "text": "Termín vykonania: do 30 dní."
    }
  ],
  "idempotencyKey": "order-2026-07-19-001"
}
```

Úspešný výsledok obsahuje najmä `documentId`, `editorUrl`, `viewUrl`,
`nativeDeepLink`, `pwaDeepLink`, `permissions`, `expiresAt`,
`sessionTtlSeconds` a `requiresUserConfirmation`. MCP klient má použiť
`editorUrl` na kontrolu a úpravy alebo `viewUrl` na read-only zdieľanie;
pravidlá pre protokolové odkazy sú v [`DEEP-LINKS.md`](DEEP-LINKS.md).
Hodnota `requiresUserConfirmation` zostáva konzervatívne `true`, pretože klient
nemôže vopred vedieť, či je cieľový editor prázdny. Samotný pasteToPrint
prijímač môže preskočiť modal iba pri bezpečnom prázdnom editore podľa pravidla
vyššie; používateľ musí výsledný návrh skontrolovať.

## `validate_document`

Nástroj prijíma kompletný PTDF objekt vrátane
`schemaVersion: "ptp.document/1"`. Používa rovnaký normalizátor ako editor,
nevolá sieť a nevytvára session. Pri úspechu vráti `normalizedDocument` a
štatistiky blokov, textu, obrázkov a buniek tabuľky. Neplatný dokument vráti
`valid: false` s poľami `code`, `path` a `message`.

## `get_document_schema`

Nástroj načíta aktuálnu verejnú schému
`/api/document-schema/v1/schema.json` a vráti ju spolu s identifikátorom
`ptp.document/1` a MIME typom
`application/vnd.pastetoprint.ptdf+json`. Výsledok obsahuje aj MIT licenciu a
odkaz na presný licenčný scope. Endpoint nevyžaduje autentifikáciu.

## `update_document`

Nástroj prijíma:

- `documentId` vrátené nástrojom `create_document`,
- voliteľný kompletný náhradný `document` bez `schemaVersion`,
- voliteľné `permissions.allowEditing` a `permissions.allowExport`,
- voliteľný `ifMatch`, napríklad `"session-2"`.

Aspoň `document` alebo `permissions` musí byť uvedené. MCP server doplní
`schemaVersion`, dokument lokálne overí a až potom zavolá PATCH API.
`ifMatch` použite pri súbežných úpravách; neaktuálna revízia sa odmietne bez
prepísania novšieho obsahu.

Výsledok obsahuje nové `revision`, `etag`, účinné práva a obnovené odkazy.

## `get_document_links`

Nástroj prijíma iba netajné `documentId`. Vráti `editorUrl`, `viewUrl`,
protokolové deep linky, účinné práva, revíziu, `etag` a expiráciu. Nevracia
obsah dokumentu ani tajný správcovský token.

Po `create_document` zostáva správcovský token iba v pamäti bežiaceho MCP
procesu. Vďaka tomu funguje `update_document` a `get_document_links` aj pre
anonymnú session bez toho, aby model token videl. Po reštarte procesu je na
správu už existujúcej session potrebný Bearer token s príslušným
`document:read` alebo `document:update` scope a s rovnakým vlastníkom session.

## Bezpečnostné hranice

- API token nikdy neposielajte ako argument nástroja alebo do dokumentu.
- Token uložte iba do chráneného prostredia lokálneho MCP procesu.
- Správcovský `sessionToken` nie je výstupom ani vstupom MCP nástrojov; server
  ho pre práve vytvorené session drží iba v pamäti do expirácie.
- MCP server nesleduje HTTP presmerovania, aby neposlal Authorization hlavičku
  na inú adresu.
- Odpovede API majú veľkostný limit a časový limit.
- `editorUrl` je dočasný capability odkaz. Zdieľajte ho iba s používateľom,
  ktorý má dokument skontrolovať.
- Nepridávajte nástroje na automatickú tlač alebo export, kým API nemá
  samostatné scopes a potvrdenie používateľa.

## Vývoj a test

```powershell
cd C:\laragon\www\pasteToPrint\integrations\mcp
npm.cmd test
```

Test spustí skutočného MCP klienta a server cez `stdio`, simuluje API v2,
overí všetkých šesť nástrojov, lokálnu validáciu, schému, ETag aktualizáciu,
oddelené odkazy, hlavičky autentifikácie, TTL, idempotenciu, spracovanie API
chyby a to, že sa API ani správcovský token neobjaví vo výsledku nástroja.

## PTDF kompatibilita a príklady

`get_document_schema` vracia stabilný wire identifikátor `ptp.document/1`.
Aktuálna revízia `2026-08-01` a podporované orientácie, šablóny, bloky a
konverzie sú publikované samostatne v
[`capabilities.json`](api/document-schema/v1/capabilities.json); revízia sa
nikdy nekopíruje do dokumentu. Pred výberom `coloring_*` šablóny použite
`list_templates`. Ak schopnosti cieľového prijímateľa nie sú známe, použite
`portrait` a `blank`.

Na overenie nástrojom `validate_document` možno použiť úplné verejné dokumenty
[`landscape-example.json`](api/document-schema/v1/landscape-example.json) a
[`coloring-drawing-example.json`](api/document-schema/v1/coloring-drawing-example.json).
Coloring príklad obsahuje štandardný rastrový `image`, nie editovateľný drawing
projekt. MCP klient nesmie sľúbiť zachovanie vrstiev alebo histórie kresby.