# Rowvia MCP-Agentenleitfaden

Dieses Dokument ist für KI-Agenten oder Chatbots gedacht, die Rowvia.ai über Rowvia MCP bedienen.

Öffentliche Dokumentation:

- Deutsch: https://rowvia.ai/de/docs/mcp
- Englisch: https://rowvia.ai/en/docs/mcp
- Tschechisch: https://rowvia.ai/docs/mcp

## Zweck

Rowvia MCP erlaubt KI-Agenten, mit vorhandenen Rowvia-Tabellen zu arbeiten: Tabellen auflisten und finden, Schemata, Prompts und Zusammenfassungen lesen, Zeilen aus URLs, Text, Inline-Dateien oder ChatGPT-Anhängen hinzufügen, optional Processing starten, Status prüfen, Zeilen durchsuchen und ausgewählte Zeilen oder Ergebnisse lesen.

Es ist keine vollständige API zur Tabellenverwaltung. Standardmäßig kann der MCP-Server neue Zeilen hinzufügen und konfiguriertes Processing auslösen, aber keine vorhandenen Zellwerte überschreiben. Optionale Zellupdate-Tools sind standardmäßig deaktiviert und erfordern `ROWVIA_MCP_ENABLE_ROW_UPDATE=true` sowie ein Token mit dem Scope `rows:update`.

## Lokale MCP-Clients vs. ChatGPT

Lokale Clients wie Claude Desktop, Cursor, Codex CLI und lokale Agenten können einen stdio MCP-Server über einen lokalen Command starten. `ROWVIA_API_BASE_URL` und `ROWVIA_API_TOKEN` gehören in die Env-Konfiguration des MCP-Clients.

ChatGPT kann eine lokale stdio-Konfiguration nicht direkt verwenden. Es benötigt einen öffentlich erreichbaren HTTPS-MCP-Endpunkt, zum Beispiel `https://api.rowvia.ai/mcp`. Die Verfügbarkeit hängt vom ChatGPT-Plan/Workspace und davon ab, ob MCP, Custom Connectors oder Developer Mode aktiviert sind.

Der hosted ChatGPT Connector kann vom Benutzer angehängte Dokumente über Apps SDK File Params übergeben. Verwenden Sie dafür `rowvia_row_add_chatgpt_document`. Das Tool deklariert `_meta["openai/fileParams"] = ["file"]` und akzeptiert ein erforderliches Top-level-Objekt `file` mit einer temporären `download_url` Referenz. Unterstützte ChatGPT-Anhänge sind PDF, DOCX, TXT und Markdown. ChatGPT-Anhänge nicht über `documents`, `files`, base64 oder manuell kopierte URLs senden.

## Konfiguration

Production:

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

Der folgende Command gilt für lokale Entwicklung im Rowvia-Monorepo. Für externe Installation verwenden Sie den Command aus den Rowvia-Integrationseinstellungen.

```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

Erstellen Sie das Token in Rowvia Profil -> Integrationen.

Empfohlene Scopes für normale Zeilenverarbeitungs-Workflows:

- `tables:read`: Tabellen, Schemata, Prompts und Zusammenfassungen finden.
- `rows:read`: Begrenzte Zeilenfenster, Suchen und ausgewählte Ergebnisse lesen.
- `row:add`: URL-, Text- und Inline-Dateizeilen über `rowvia_row_add` sowie ChatGPT-attached Dokumente über `rowvia_row_add_chatgpt_document` hinzufügen.
- `row:process`: Pending Work schätzen, Zeilenverarbeitung starten und Processing-Jobs prüfen.

Optionaler Korrektur-Scope:

- `rows:update`: nur verwenden, wenn der Agent ausdrückliche manuelle Zellkorrekturen über `rowvia_row_update` durchführen soll.

Wenn der Agent mit einer Tabelle arbeiten soll, bevorzugen Sie ein auf diese Tabelle beschränktes Token.

## Tools

Tabellen und Schema:

- `rowvia_table_list`: listet verfügbare Tabellen ohne Zeilendaten. Input: `limit` bis 100.
- `rowvia_table_find`: findet eine Tabelle nach Name. Input: `table_name`, optional `require_single`.
- `rowvia_table_get_schema`: gibt Spalten, Readonly-Status und vollständige Output-Spalten-Prompts zurück. Input: `table_id`.
- `rowvia_table_get_summary`: gibt kompakten Tabellenstatus, Zeilenzahl, Statuszahlen und Output-Spaltenzahl zurück. Input: `table_id`.
- `rowvia_table_get_pending_work`: schätzt pending Processing für alle pending Zeilen oder ausgewählte Zeilen. Input: `table_id`, `mode`, optional `row_ids`.

Zeilen und Dokumente:

- `rowvia_row_add_chatgpt_document`: fügt ein in ChatGPT hochgeladenes PDF-, DOCX-, TXT- oder Markdown-Dokument aus einem Top-level-Objekt `file` hinzu; optional kann es mit `process_after_add` sofort Processing starten.
- `rowvia_row_add`: fügt bis zu 100 Dokumentzeilen aus `documents` hinzu; optional kann es mit `process_after_add` sofort Processing starten. Nicht für ChatGPT-Anhänge verwenden.
- `rowvia_row_list`: gibt ein begrenztes Zeilenfenster zurück. Input: `table_id`, `offset`, `limit` bis 100, optional `column_ids`.
- `rowvia_row_search`: durchsucht Zeilen. Input: `table_id`, `query`, optional `statuses`, `row_filters`, `offset`, `limit`, `column_ids`.
- `rowvia_row_get`: liest explizite `row_ids`; optional mit Dokumentmetadaten über `include_document` und Spaltenbegrenzung über `column_ids`.
- `rowvia_row_get_results`: liest nur Ergebniszellen für explizite `row_ids`, typischerweise nach Processing.

Processing:

- `rowvia_table_start_processing`: startet Processing für `all_pending` oder `selected_rows`; `selected_rows` benötigt `row_ids`.
- `rowvia_processing_get_status`: gibt kompakten Processing-Job-Status nach `processing_run_id` zurück.

Optionales Korrektur-Tool:

- `rowvia_row_update`: aktualisiert Zellen in einer Zeile manuell. Es wird nur mit `ROWVIA_MCP_ENABLE_ROW_UPDATE=true` registriert und benötigt den Scope `rows:update`.

## Resources

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

## Zeilen hinzufügen

Verwenden Sie `rowvia_row_add`, um eine oder mehrere neue Zeilen zu einer vorhandenen konfigurierten Rowvia-Tabelle hinzuzufügen. Diese Zeilen repräsentieren normalerweise Dokumente, URLs oder Textquellen, die verarbeitet werden sollen.

Unterstützte Quellen:

- `source=url`
- `source=text`
- `source=file` für kleine Inline-base64-Dateien

Für `source=url` eine öffentliche oder temporäre HTTPS-URL senden. Rowvia lädt das Dokument serverseitig ohne Cookies, Auth-Header oder JavaScript-Ausführung herunter. Das ist der empfohlene Weg für größere PDF-, DOCX-, TXT- und MD-Dateien, wenn das Modell oder ChatGPT eine URL liefern kann. HTML-URLs werden als Markdown-Snapshots gespeichert.

Minimaler 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-Dateien folgen denselben Upload-Limits wie die Rowvia-App. Hosted HTTP MCP begrenzt außerdem den MCP-Request-Body auf 2 MB, daher ist `source=file` nicht der primäre Weg für größere lokale Dateien. Unterstützte Dokument-MIME-Typen sind PDF, DOCX, Markdown und Plain Text.

ChatGPT-Dokumentanhänge über `rowvia_row_add_chatgpt_document` senden, nicht über `rowvia_row_add` und nicht als base64. Das Feld `file` ist ein echtes Top-level-Objekt im Tool-Schema. Es muss eine HTTPS-`download_url` und `file_id` enthalten; `mime_type` und `file_name` sollten den ursprünglichen PDF-, DOCX-, TXT- oder Markdown-Anhang beschreiben.

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"
  }
}
```

Das Ergebnis enthält `accepted_count`, `rejected_count` und per-item Einträge mit `client_id`, `row_id`, `file_id`, `document_name`, `doc_type`, `code` und `message`.

`process_after_add` ist standardmäßig `false`. Processing kann Processing Units verbrauchen, daher sollten Agenten es nur ausführen, wenn der Benutzer es angefordert hat oder der MCP-Request es ausdrücklich setzt.

## Empfohlener Agent-Workflow

1. Verwenden Sie `rowvia_table_list` oder `rowvia_table_find`, um eine vorhandene Tabelle zu finden. Bei Unklarheit die Zieltabelle bestätigen lassen.
2. Vor dem Hinzufügen von Zeilen oder Processing `rowvia_table_get_schema` oder `rowvia://tables/{table_id}/schema` verwenden. Prompts in Output-Spalten sind vollständige Anweisungen.
3. Für ein in ChatGPT angehängtes unterstütztes Dokument `rowvia_row_add_chatgpt_document` verwenden; für URL-/Text-/Inline-Dokumentzeilen `rowvia_row_add` mit `process_after_add=false` verwenden.
4. Das per-item Ergebnis des Hinzufügens prüfen. Eine Batch kann accepted und rejected Elemente enthalten.
5. Vor Processing `rowvia_table_get_pending_work` aufrufen und bei größeren oder kostenrelevanten Läufen die Schätzung anzeigen.
6. Processing mit `rowvia_table_start_processing` starten.
7. Die zurückgegebene `processing_run_id` speichern und mit `rowvia_processing_get_status` prüfen.
8. Ergebnisse über `rowvia_row_get_results` oder `rowvia_row_get` mit Spaltenprojektion lesen.

Für Automatisierung `table_id` und `row_id` verwenden. `row_index` ist nur eine Anzeige-Position und kann sich durch Sortierung, Filterung oder Reimport ändern.

## Beispiele

Eine Rechnungs-URL hinzufügen und verarbeiten:

1. `rowvia_table_list`
2. `rowvia_row_add` mit `process_after_add=false`
3. `rowvia_table_start_processing` für die zurückgegebene `row_id`
4. `rowvia_processing_get_status`
5. `rowvia_row_get` für die zurückgegebene `row_id`

Zeilen hinzufügen, aber nicht verarbeiten:

1. `rowvia_table_list`
2. `rowvia_row_add`
3. `rowvia_row_get` für die zurückgegebenen `row_id` Werte

In ChatGPT angehängte Dokumente hinzufügen:

1. `rowvia_table_find` oder `rowvia_table_list`
2. `rowvia_row_add_chatgpt_document` mit Top-level `file` und `process_after_add=false`
3. Accepted/rejected Positionen prüfen
4. Optional `rowvia_table_start_processing` für die zurückgegebenen `row_id` Werte

Ausgewählte Zeilen erneut verarbeiten:

1. `rowvia_row_list` oder `rowvia_row_search`
2. `rowvia_table_start_processing` mit `selected_rows` und `row_ids`
3. `rowvia_processing_get_status`
4. `rowvia_row_get_results`

## Sicherheitsregeln

- Das vollständige API-Token niemals anzeigen oder loggen.
- Vollständige ChatGPT `download_url` Werte nicht loggen; sie sind temporäre sensitive URLs.
- Rowvia-Token niemals an importierte URLs senden.
- Für Automatisierungen tabellenbeschränkte Token bevorzugen.
- Nicht die ganze Tabelle ausgeben. Begrenzte Fenster und Spaltenprojektion verwenden.
- Große Batches nicht ohne ausdrückliche Bestätigung verarbeiten.
- Vor größerem Processing `rowvia_table_get_pending_work` bevorzugen.
- Eine leere Output-Zelle ist verarbeitbar. Eine nicht leere Output-Zelle wird gemäß den normalen Rowvia-Regeln übersprungen.
- Rowvia MCP verwendet dieselbe Rowvia-Authentifizierung, denselben Owner-Kontext, dieselben Quotas, Billing-Regeln und Audit-Logs wie die Web-App.
- MCP-Tools löschen keine Zeilen oder Tabellen, erstellen keine Tabellen, ändern keine Schemata, bearbeiten keine Prompts und ändern keine Billing-/Admin-Einstellungen.