# Rowvia MCP průvodce pro agenty

Tento dokument použij, když AI agent nebo chatbot potřebuje pracovat s Rowvia.ai přes Rowvia MCP.

Veřejná dokumentace:

- Česky: https://rowvia.ai/docs/mcp
- Anglicky: https://rowvia.ai/en/docs/mcp
- Německy: https://rowvia.ai/de/docs/mcp

## Účel

Rowvia MCP dovolí AI agentům pracovat s existujícími Rowvia tabulkami: vypsat a najít tabulky, načíst schema, prompty a souhrny, přidat řádky z URL, textu, inline souborů nebo ChatGPT příloh, volitelně spustit processing, sledovat stav, vyhledávat řádky a číst vybrané řádky nebo výsledky.

Není to kompletní API pro správu tabulek. Ve výchozím nastavení MCP server umí přidávat nové řádky a spouštět nakonfigurovaný processing, ale neumí přepisovat existující hodnoty buněk. Volitelné nástroje pro update buněk jsou defaultně vypnuté a vyžadují `ROWVIA_MCP_ENABLE_ROW_UPDATE=true` plus token se scope `rows:update`.

## Lokální MCP klienti vs ChatGPT

Lokální klienti jako Claude Desktop, Cursor, Codex CLI a lokální agenti mohou spustit stdio MCP server lokálním commandem. `ROWVIA_API_BASE_URL` a `ROWVIA_API_TOKEN` patří do env konfigurace MCP klienta.

ChatGPT neumí přímo použít lokální stdio konfiguraci. Potřebuje veřejně dostupný HTTPS MCP endpoint, například `https://api.rowvia.ai/mcp`. Dostupnost závisí na uživatelově ChatGPT plánu/workspace a na tom, jestli jsou zapnuté MCP, custom connectors nebo developer mode.

Hosted ChatGPT connector může předat uživatelem přiložené dokumenty přes Apps SDK file params. Pro tuto cestu používej `rowvia_row_add_chatgpt_document`. Tool inzeruje `_meta["openai/fileParams"] = ["file"]` a přijímá povinný top-level objekt `file` s dočasným `download_url` odkazem. Podporované ChatGPT přílohy jsou PDF, DOCX, TXT a Markdown. ChatGPT přílohy neposílej přes `documents`, `files`, base64 ani ručně zkopírovanou URL.

## Konfigurace

Production:

```text
ROWVIA_API_BASE_URL=https://api.rowvia.ai
```

Command níže odpovídá lokálnímu vývoji v Rowvia monorepu. Pro externí instalaci použij command publikovaný v integračním nastavení Rowvia.

```json
{
  "mcpServers": {
    "rowvia": {
      "command": "npx",
      "args": ["--workspace", "@rowvia/mcp", "rowvia-mcp"],
      "env": {
        "ROWVIA_API_BASE_URL": "https://api.rowvia.ai",
        "ROWVIA_API_TOKEN": "rvia_...",
        "ROWVIA_MCP_ENABLE_ROW_UPDATE": "false"
      }
    }
  }
}
```

## Token scopes

Token vytvoř v Rowvia Profil -> Integrace.

Doporučené scopes pro běžné zpracování řádků:

- `tables:read`: vyhledání tabulek, schémat, promptů a souhrnů.
- `rows:read`: čtení omezených oken řádků, vyhledávání a vybraných výsledků.
- `row:add`: přidání URL, textových a inline souborových řádků přes `rowvia_row_add` a ChatGPT-attached dokumentů přes `rowvia_row_add_chatgpt_document`.
- `row:process`: odhad pending práce, spuštění zpracování řádků a kontrola processing jobů.

Volitelný scope pro korekce:

- `rows:update`: použij jen tehdy, když má agent dělat výslovné ruční opravy buněk přes `rowvia_row_update`.

Pokud má agent pracovat s jednou tabulkou, preferuj token omezený na tuto tabulku.

## Nástroje

Tabulky a schema:

- `rowvia_table_list`: vypíše dostupné tabulky bez řádkových dat. Vstup: `limit` max 100.
- `rowvia_table_find`: najde tabulku podle názvu. Vstup: `table_name`, volitelné `require_single`.
- `rowvia_table_get_schema`: vrátí sloupce, readonly stav a plné prompty output sloupců. Vstup: `table_id`.
- `rowvia_table_get_summary`: vrátí kompaktní stav tabulky, počet řádků, stavů a output sloupců. Vstup: `table_id`.
- `rowvia_table_get_pending_work`: odhadne pending processing pro všechny pending řádky nebo vybrané řádky. Vstup: `table_id`, `mode`, volitelné `row_ids`.

Řádky a dokumenty:

- `rowvia_row_add_chatgpt_document`: přidá jedno PDF, DOCX, TXT nebo Markdown dokument nahraný v ChatGPT z top-level objektu `file`; volitelně může hned spustit processing přes `process_after_add`.
- `rowvia_row_add`: přidá až 100 dokumentových řádků z `documents`; volitelně může hned spustit processing přes `process_after_add`. Nepoužívej ho pro ChatGPT přílohy.
- `rowvia_row_list`: vrátí omezené okno řádků. Vstup: `table_id`, `offset`, `limit` max 100, volitelné `column_ids`.
- `rowvia_row_search`: vyhledá řádky. Vstup: `table_id`, `query`, volitelné `statuses`, `row_filters`, `offset`, `limit`, `column_ids`.
- `rowvia_row_get`: přečte explicitní `row_ids`; volitelně přidá metadata dokumentu přes `include_document` a omezí sloupce přes `column_ids`.
- `rowvia_row_get_results`: přečte jen výsledkové buňky pro explicitní `row_ids`, typicky po processingu.

Processing:

- `rowvia_table_start_processing`: spustí processing pro `all_pending` nebo `selected_rows`; pro `selected_rows` jsou povinné `row_ids`.
- `rowvia_processing_get_status`: vrátí kompaktní stav processing jobu podle `processing_run_id`.

Volitelný nástroj pro korekce:

- `rowvia_row_update`: ručně upraví buňky jednoho řádku. Je registrovaný jen při `ROWVIA_MCP_ENABLE_ROW_UPDATE=true` a vyžaduje scope `rows:update`.

## Resources

- `rowvia://tables`
- `rowvia://tables/{table_id}/schema`
- `rowvia://tables/{table_id}/rows?offset=0&limit=20`

## Přidávání řádků

Použij `rowvia_row_add` pro přidání jednoho nebo více nových řádků do existující nakonfigurované Rowvia tabulky. Tyto řádky obvykle reprezentují dokumenty, URL nebo textové zdroje ke zpracování.

Podporované zdroje:

- `source=url`
- `source=text`
- `source=file` pro malé inline base64 soubory

U `source=url` posílej veřejnou nebo dočasnou HTTPS adresu. Rowvia dokument stáhne server-side bez cookies, auth headerů a bez spouštění JavaScriptu. Je to doporučená cesta pro větší PDF, DOCX, TXT a MD soubory, pokud model nebo ChatGPT umí předat URL. HTML URL se ukládá jako Markdown snapshot.

Minimální URL payload:

```json
{
  "table_id": "sheet_123",
  "process_after_add": false,
  "documents": [
    {
      "client_id": "invoice-1",
      "source": "url",
      "url": "https://example.com/invoice.pdf",
      "doc_type": "auto"
    }
  ]
}
```

Inline soubory se řídí stejnými limity nahrávání jako aplikace Rowvia. V hosted HTTP MCP je navíc tělo MCP requestu omezené na 2 MB, takže `source=file` neber jako hlavní cestu pro větší lokální soubory. Podporované MIME typy dokumentů jsou PDF, DOCX, Markdown a plain text.

ChatGPT dokumentové přílohy posílej přes `rowvia_row_add_chatgpt_document`, ne přes `rowvia_row_add` a ne jako base64. Pole `file` je reálný top-level objekt ve schematu toolu. Musí obsahovat HTTPS `download_url` a `file_id`; `mime_type` a `file_name` mají popisovat původní PDF, DOCX, TXT nebo Markdown přílohu.

ChatGPT attached-file payload:

```json
{
  "table_id": "sheet_123",
  "process_after_add": false,
  "file": {
    "download_url": "https://files.oaiusercontent.com/...",
    "file_id": "file_abc",
    "mime_type": "application/pdf",
    "file_name": "invoice.pdf"
  }
}
```

Výsledek vrací `accepted_count`, `rejected_count` a per-item položky s `client_id`, `row_id`, `file_id`, `document_name`, `doc_type`, `code` a `message`.

`process_after_add` má defaultně hodnotu `false`. Processing může spotřebovat Processing Units, takže ho agent má spouštět jen tehdy, když o to uživatel požádal nebo MCP request tuto volbu výslovně nastavil.

## Doporučený workflow agenta

1. Použij `rowvia_table_list` nebo `rowvia_table_find` a najdi existující tabulku. Když je cíl nejasný, nech si ho potvrdit.
2. Před přidáváním řádků nebo processingem použij `rowvia_table_get_schema` nebo `rowvia://tables/{table_id}/schema`. Prompty output sloupců jsou plné instrukce.
3. Pro podporovaný dokument přiložený v ChatGPT použij `rowvia_row_add_chatgpt_document`; pro URL/text/inline dokumentové řádky použij `rowvia_row_add` s `process_after_add=false`.
4. Zkontroluj per-item výsledek přidání. Jedna dávka může obsahovat accepted i rejected položky.
5. Před processingem zavolej `rowvia_table_get_pending_work` a u většího nebo placeného běhu ukaž odhad.
6. Processing spusť přes `rowvia_table_start_processing`.
7. Ulož vrácené `processing_run_id` a kontroluj ho přes `rowvia_processing_get_status`.
8. Výstupy čti přes `rowvia_row_get_results` nebo `rowvia_row_get` s projekcí sloupců.

Pro automatizaci používej `table_id` a `row_id`. `row_index` je jen zobrazovací pozice a může se změnit po řazení, filtrování nebo reimportu.

## Příklady

Přidat jednu fakturu z URL a zpracovat ji:

1. `rowvia_table_list`
2. `rowvia_row_add` s `process_after_add=false`
3. `rowvia_table_start_processing` pro vrácené `row_id`
4. `rowvia_processing_get_status`
5. `rowvia_row_get` pro vrácené `row_id`

Přidat řádky bez processingu:

1. `rowvia_table_list`
2. `rowvia_row_add`
3. `rowvia_row_get` pro vrácené hodnoty `row_id`

Přidat dokument přiložený v ChatGPT:

1. `rowvia_table_find` nebo `rowvia_table_list`
2. `rowvia_row_add_chatgpt_document` s top-level `file` a `process_after_add=false`
3. Zkontrolovat accepted/rejected položky
4. Volitelně `rowvia_table_start_processing` pro vrácené `row_id`

Znovu zpracovat vybrané řádky:

1. `rowvia_row_list` nebo `rowvia_row_search`
2. `rowvia_table_start_processing` se `selected_rows` a `row_ids`
3. `rowvia_processing_get_status`
4. `rowvia_row_get_results`

## Bezpečnostní pravidla

- Nikdy neukazuj ani neloguj celý API token.
- Nezapisuj do logů celé ChatGPT `download_url`; ber je jako dočasné citlivé odkazy.
- Nikdy neposílej Rowvia tokeny na importované URL.
- Pro automatizace preferuj token omezený na konkrétní tabulku.
- Nevypisuj celou tabulku. Používej omezená okna a projekci sloupců.
- Nespouštěj velké dávky bez výslovného potvrzení.
- Před větším processingem preferuj `rowvia_table_get_pending_work`.
- Prázdná output buňka je processable. Neprázdná output buňka se přeskakuje podle běžných pravidel Rowvia.
- Rowvia MCP používá stejné Rowvia ověření, owner context, kvóty, billing a audit logy jako webová aplikace.
- MCP nástroje nemažou řádky ani tabulky, nevytváří tabulky, nemění schema, neupravují prompty a nemění billing/admin nastavení.