Skip to content

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 mit attach_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 mit list_artifacts/read_artifact.

Siehe auch Dateien & Dokumente im Handbuch.

list_files ​

Dateien der Cloud Drive zu einer Aufgabe oder Liste. read · follower

ParameterTypDefaultBeschreibung
itemIdstring–UUID oder SID einer Aufgabe: ihre Datei-Box, Dateien direkt am Item und Datei-Unterpunkte
listIdstring–UUID oder SID einer Liste: Dateien überall in der Liste
limitnumber50Max. 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

ParameterTypDefaultBeschreibung
fileIdstring (erforderlich)–file_id aus list_files oder aus einem Datei-Eintrag in den refs eines Items
max_bytesnumber2 MBObergrenze; hart max. 25 MB. Größere Dateien werden nicht übertragen, es kommt nur die Größe zurück
encodingenum auto | text | base64autoauto = 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.

Einen Link auf eine Datei oder einen ganzen Ordner der Cloud Drive erzeugen, z. B. zum Einfügen in einen Chat. write · user

ParameterTypDefaultBeschreibung
itemstring (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
revokebooleanfalsetrue = Link zurücknehmen statt erzeugen
expires_in_daysinteger 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.

Einen geteilten Datei-Link (https://<host>/<org>/f/<id>) öffnen. read · follower

ParameterTypDefaultBeschreibung
urlstring–Der Datei-Link
sidstring–Alternative zu url: nur die ID nach /f/
include_contentbooleanfalseBei Textdateien auch den Inhalt liefern
max_charsinteger 500–20000040000Obergrenze für den Text; längere Dateien werden mit Hinweis gekürzt
folderstring–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

ParameterTypBeschreibung
itemIdstring (erforderlich)UUID oder SID der Aufgabe
namestring (erforderlich)Anzeigename. Erneut unter demselben Namen an derselben Aufgabe = neue Version
entrystring (erforderlich)Relativer Pfad der Einstiegsdatei, z. B. index.html — muss in files vorkommen
filesobject[] (erforderlich)Je Datei: path (relativ, z. B. assets/style.css), entweder content_text oder content_base64, optional mime
kindenum doc | page | app | dataArt; ohne Angabe aus der Endung von entry abgeleitet
labelstringKurzer Text zur Version, am besten was sich geändert hat
conversation_idstringUUID 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

ParameterTypBeschreibung
itemIdstring (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

ParameterTypDefaultBeschreibung
itemIdstring (erforderlich)–UUID oder SID der Aufgabe
artifactstring–Name, Slug oder artifact_id aus list_artifacts; entfällt, wenn die Aufgabe genau ein Artefakt hat
pathstringEinstiegsdateiDatei innerhalb des Bündels
versionintegeraktuelleÄltere Version lesen
max_bytesnumber2 MBObergrenze; hart max. 25 MB
encodingenum auto | text | base64autowie bei read_file

Textdateien kommen als Text, Bilder als Bildblock, andere Binärdateien base64-kodiert.