MCP-Tools: Dateien & Artefakte
An einer Aufgabe gibt es zwei getrennte Ablagen:
- Cloud Drive — Dateien, die jemand anhängt oder ablegt (der Eingang). Lesen mit
list_files/read_file, weitergeben per Datei-Link. Ablegen mitattach_file_to_list_item. - Artefakte — Ergebnisse, die eine KI erzeugt und veröffentlicht (der Ausgang): benannte, versionierte Bündel im Kasten „Artefakte“ der Aufgabe. Sie stehen nicht in
list_files; lesen mitlist_artifacts/read_artifact.
Siehe auch Dateien & Dokumente im Handbuch.
list_files
Dateien der Cloud Drive zu einer Aufgabe oder Liste. read · follower
| Parameter | Typ | Default | Beschreibung |
|---|---|---|---|
itemId | string | – | UUID oder SID einer Aufgabe: ihre Datei-Box, Dateien direkt am Item und Datei-Unterpunkte |
listId | string | – | UUID oder SID einer Liste: Dateien überall in der Liste |
limit | number | 50 | Max. Anzahl |
Genau eines von itemId und listId angeben. Pro Datei kommen u. a. file_id, name, mime, size, readable_as_text, location und item_id (das Datei-Item) zurück. file_id geht an read_file, item_id an share_file_link. Dateien externer Speicher (Unified.to) liefert stattdessen search_files.
read_file
Inhalt einer Datei aus der Cloud Drive. read · follower
| Parameter | Typ | Default | Beschreibung |
|---|---|---|---|
fileId | string (erforderlich) | – | file_id aus list_files oder aus einem Datei-Eintrag in den refs eines Items |
max_bytes | number | 2 MB | Obergrenze; hart max. 25 MB. Größere Dateien werden nicht übertragen, es kommt nur die Größe zurück |
encoding | enum auto | text | base64 | auto | auto = Text für Textdateien, sonst base64 |
Textdateien (md, txt, json, csv, Code …) kommen als Text, andere Binärdateien base64-kodiert. Bilder (PNG, JPEG, WebP, GIF bis 4 MB) kommen als MCP-Bildblock, den ein Modell direkt ansehen kann.
share_file_link
Einen Link auf eine Datei oder einen ganzen Ordner der Cloud Drive erzeugen, z. B. zum Einfügen in einen Chat. write · user
| Parameter | Typ | Default | Beschreibung |
|---|---|---|---|
item | string (erforderlich) | – | Das Datei- oder Ordner-Item (UUID, SID oder sein Link) — nicht die Aufgabe. item_id aus list_files oder attach_file_to_list_item |
revoke | boolean | false | true = Link zurücknehmen statt erzeugen |
expires_in_days | integer 1–3650 | – | Link auf so viele Tage begrenzen; ohne Angabe läuft er nicht ab |
Den Link öffnen alle Mitglieder der Organisation, auch ohne Zugriff auf das Projekt — Gäste nicht. Gibt es schon einen aktiven Link, kommt dieser zurück. Teilen kann man nur Dateien, die man selbst lesen darf; hat das Projekt Datei-Links abgeschaltet, scheitert der Aufruf. Antwort: url, active, created, opened_count.
get_file_link
Einen geteilten Datei-Link (https://<host>/<org>/f/<id>) öffnen. read · follower
| Parameter | Typ | Default | Beschreibung |
|---|---|---|---|
url | string | – | Der Datei-Link |
sid | string | – | Alternative zu url: nur die ID nach /f/ |
include_content | boolean | false | Bei Textdateien auch den Inhalt liefern |
max_chars | integer 500–200000 | 40000 | Obergrenze für den Text; längere Dateien werden mit Hinweis gekürzt |
folder | string | – | Nur bei Ordner-Links: SID eines Unterordners aus entries |
Die Antwort trägt Name, Typ, Größe, Datum und shared_by. Bilder, PDFs, Videos und andere Binärdateien kommen als download_url (15 Minuten gültig). Ein Ordner-Link liefert kind: "folder" mit seinen entries. Abgelaufene, zurückgenommene oder fremde Links melden einen Fehler mit Grund.
publish_artifact
Ein Ergebnis als Artefakt an eine Aufgabe hängen, sichtbar für das ganze Team. write · user
| Parameter | Typ | Beschreibung |
|---|---|---|
itemId | string (erforderlich) | UUID oder SID der Aufgabe |
name | string (erforderlich) | Anzeigename. Erneut unter demselben Namen an derselben Aufgabe = neue Version |
entry | string (erforderlich) | Relativer Pfad der Einstiegsdatei, z. B. index.html — muss in files vorkommen |
files | object[] (erforderlich) | Je Datei: path (relativ, z. B. assets/style.css), entweder content_text oder content_base64, optional mime |
kind | enum doc | page | app | data | Art; ohne Angabe aus der Endung von entry abgeleitet |
label | string | Kurzer Text zur Version, am besten was sich geändert hat |
conversation_id | string | UUID der KI-Konversation, aus der die Version stammt |
Ein Artefakt ist ein benanntes Bündel aus einer oder mehreren Dateien mit Einstiegspunkt, höchstens 50 Dateien und 25 MB. Ist das Bündel byte-gleich mit der aktuellen Version, entsteht keine neue (unchanged: true). Antwort u. a. artifact_id, slug, version, created.
Für Dateien, die nur abgelegt werden (Eingaben, Uploads, Referenzen), ist attach_file_to_list_item der richtige Weg.
list_artifacts
Die Artefakte einer Aufgabe. read · follower
| Parameter | Typ | Beschreibung |
|---|---|---|
itemId | string (erforderlich) | UUID oder SID der Aufgabe |
Pro Artefakt: ID, Name, Art, aktuelle Version, Einstiegsdatei, die Dateien der aktuellen Version und die Versionsgeschichte.
read_artifact
Inhalt eines Artefakts lesen. read · follower
| Parameter | Typ | Default | Beschreibung |
|---|---|---|---|
itemId | string (erforderlich) | – | UUID oder SID der Aufgabe |
artifact | string | – | Name, Slug oder artifact_id aus list_artifacts; entfällt, wenn die Aufgabe genau ein Artefakt hat |
path | string | Einstiegsdatei | Datei innerhalb des Bündels |
version | integer | aktuelle | Ältere Version lesen |
max_bytes | number | 2 MB | Obergrenze; hart max. 25 MB |
encoding | enum auto | text | base64 | auto | wie bei read_file |
Textdateien kommen als Text, Bilder als Bildblock, andere Binärdateien base64-kodiert.