Sutram MCP Server Handbuch

Version: 0.111.0 Datum: 2026-03-14 Status: In Entwicklung

Übersicht

Sutram Fernzugriff ermöglicht KI-Assistenten und Automatisierungstools die Verbindung zu Ihren Projekten über das Model Context Protocol (MCP). Einmal konfiguriert, kann Ihr KI-Assistent Ordner durchsuchen, Dateien hochladen, Web-/Video-/Audio-Links hinzufügen, Inhalte verwalten und mit Dokumentkommentaren in Ihren Sutram-Projekten interagieren — alles mit ordnungsgemäßer Authentifizierung und Berechtigungen.

Funktionsweise

AI Assistant (Claude, Cursor, etc.)
        |
        | MCP Protocol (HTTPS)
        v
  Sutram MCP Endpoint
    https://app.sutram.io/mcp
        |
        | Dual Key Authentication
        v
  Your Project (folders, files, content)

Für jede Verbindung sind zwei API-Schlüssel erforderlich:

Schlüssel	Zweck	Wer erstellt ihn	Wo zu finden
Projektschlüssel (`sk_proj_...`)	Identifiziert das Projekt	Projektbesitzer	Projektseite oder Projekteinstellungen
Benutzerschlüssel (`sk_user_...`)	Identifiziert Sie	Jeder Benutzer erstellt seinen eigenen	Benutzereinstellungen > API-Schlüssel

Beide Schlüssel müssen gültig sein, und Sie müssen ein aktives Mitglied des Projekts sein (kein Viewer), um eine Verbindung herzustellen.

Erste Schritte

Schritt 1: Persönlichen API-Schlüssel erstellen

Gehen Sie zu Einstellungen (Zahnradsymbol im Menü oben rechts)
Klicken Sie auf die Karte API-Schlüssel
Klicken Sie auf Schlüssel erstellen
Kopieren Sie den Schlüssel sofort — er wird nur einmal angezeigt

Ihr persönlicher Schlüssel sieht so aus: sk_user_zQD0BjH56nQhOgX3uxni...

Wichtig: Bewahren Sie Ihren Schlüssel sicher auf. Wenn Sie ihn verlieren, können Sie den alten widerrufen und einen neuen Schlüssel auf derselben Einstellungsseite erstellen.

Schritt 2: Projektschlüssel erhalten

Der Projektbesitzer muss zunächst den Fernzugriff für das Projekt aktivieren:

Gehen Sie zu Einstellungen > Tab Projekte
Öffnen Sie das Dropdown-Menü (drei Punkte) neben dem Projekt
Klicken Sie auf Fernzugriff aktivieren
Kopieren Sie den angezeigten Projektschlüssel

Sobald der Fernzugriff aktiviert ist, kann jedes Projektmitglied (Besitzer, Admin oder Mitglied) den Projektschlüssel kopieren:

Öffnen Sie das Projekt
Klicken Sie auf das grüne Signalsymbol neben dem Rollen-Badge in der Kopfzeile
Ein Dialog zeigt den Projektschlüssel — klicken Sie auf die Kopierschaltfläche

Der Projektschlüssel sieht so aus: sk_proj_ej8NWMisd2rJgMwAJ22T...

Ihren KI-Client konfigurieren

Jedes Sutram-Projekt sollte seine eigene lokale MCP-Konfiguration haben. Da der Projektschlüssel an ein bestimmtes Projekt gebunden ist, wird empfohlen, für jede Integration einen dedizierten Arbeitsbereichsordner zu erstellen und die .mcp.json-Datei dort abzulegen.

Beispiel: Wenn Sie Sutram zur Speicherung medizinischer Untersuchungen verwenden, erstellen Sie einen lokalen Ordner für diesen Arbeitsablauf:

~/projects/medical-exams/
└── .mcp.json          ← Sutram-Schlüssel für Ihr Gesundheitsprojekt

Dies hält die Anmeldedaten auf den richtigen Kontext beschränkt und vermeidet die Vermischung nicht zusammengehöriger Projekte.

Claude Code (CLI) — Empfohlen

Erstellen Sie eine .mcp.json-Datei in Ihrem Arbeitsbereichsordner:

{
  "mcpServers": {
    "sutram": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.sutram.io/mcp",
        "--header",
        "x-project-key: sk_proj_YOUR_PROJECT_KEY",
        "--header",
        "x-user-key: sk_user_YOUR_USER_KEY"
      ]
    }
  }
}

Hinweis: Claude Code unterstützt type: "url" noch nicht nativ. Die obige Konfiguration verwendet mcp-remote als Brücke zur Verbindung über stdio. Dies erfordert die Installation von Node.js (npx). Das Paket mcp-remote wird beim ersten Gebrauch automatisch heruntergeladen.

Starten Sie dann Claude Code aus diesem Ordner. Sutram-Tools sind nur in diesem Kontext verfügbar.

Cursor

Erstellen Sie eine .cursor/mcp.json-Datei in Ihrem Arbeitsbereichsordner:

{
  "mcpServers": {
    "sutram": {
      "type": "url",
      "url": "https://app.sutram.io/mcp",
      "headers": {
        "x-project-key": "sk_proj_YOUR_PROJECT_KEY",
        "x-user-key": "sk_user_YOUR_USER_KEY"
      }
    }
  }
}

Claude Desktop

Claude Desktop verwendet eine globale Konfigurationsdatei. Fügen Sie für jedes Sutram-Projekt einen Eintrag hinzu und verwenden Sie einen beschreibenden Namen zur Unterscheidung:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Wenn Ihre Version von Claude Desktop type: "url" unterstützt:

{
  "mcpServers": {
    "sutram-medical-exams": {
      "type": "url",
      "url": "https://app.sutram.io/mcp",
      "headers": {
        "x-project-key": "sk_proj_HEALTH_PROJECT_KEY",
        "x-user-key": "sk_user_YOUR_USER_KEY"
      }
    },
    "sutram-construction": {
      "type": "url",
      "url": "https://app.sutram.io/mcp",
      "headers": {
        "x-project-key": "sk_proj_WORK_PROJECT_KEY",
        "x-user-key": "sk_user_YOUR_USER_KEY"
      }
    }
  }
}

Wenn type: "url" nicht erkannt wird, verwenden Sie stattdessen die mcp-remote-Brücke:

{
  "mcpServers": {
    "sutram-medical-exams": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.sutram.io/mcp",
        "--header",
        "x-project-key: sk_proj_HEALTH_PROJECT_KEY",
        "--header",
        "x-user-key: sk_user_YOUR_USER_KEY"
      ]
    }
  }
}

Starten Sie Claude Desktop nach dem Speichern der Datei neu.

Tipp: Der Benutzerschlüssel (sk_user_...) ist in allen Einträgen gleich — er identifiziert Sie. Der Projektschlüssel (sk_proj_...) ändert sich pro Projekt.

Andere MCP-Clients

Sutram verwendet den MCP Streamable HTTP-Transport. Jeder MCP-kompatible Client, der HTTP-Transport unterstützt, kann sich verbinden mit:

Endpunkt: https://app.sutram.io/mcp
Methode: POST (JSON-RPC 2.0)
Authentifizierung: Benutzerdefinierte Header x-project-key und x-user-key
Protokollversion: 2024-11-05

Für Clients, die nur stdio-Transport unterstützen, verwenden Sie mcp-remote als Brücke:

npx -y mcp-remote https://app.sutram.io/mcp \
  --header "x-project-key: sk_proj_YOUR_PROJECT_KEY" \
  --header "x-user-key: sk_user_YOUR_USER_KEY"

Verfügbare Tools

Sobald die Verbindung hergestellt ist, hat Ihr KI-Assistent Zugriff auf diese Tools. Sie können diese Liste auch programmatisch abrufen, indem Sie die Standard-MCP-Anfrage tools/list an den Server-Endpunkt senden.

Kurzübersicht (A–Z)

#	Tool	Kategorie	Beschreibung
1	`sutram_add_enum_values`	Schema	Fügt neue Werte zu einer bestehenden Enum-Metadatendefinition hinzu
2	`sutram_cancel_checkout`	Versionierung	Bricht den Checkout ab, ohne Änderungen hochzuladen
3	`sutram_checkin_file`	Versionierung	Gibt eine Datei aus dem Checkout frei (Check-in)
4	`sutram_checkout_file`	Versionierung	Checkt eine Datei zur exklusiven Bearbeitung aus
5	`sutram_confirm_upload`	Inhalt	Schritt 2 des Uploads: Bestätigt, dass die Datei auf S3 hochgeladen wurde
6	`sutram_bulk_create_file_links`	Dateilinks	Erstellt Dateilinks in großer Menge von einem Quellordner zu einem Zielordner
7	`sutram_cancel_checkout`	Versionierung	Bricht den Checkout ab, ohne Änderungen hochzuladen
8	`sutram_checkin_file`	Versionierung	Gibt eine Datei aus dem Checkout frei (Check-in)
9	`sutram_checkout_file`	Versionierung	Checkt eine Datei zur exklusiven Bearbeitung aus
10	`sutram_confirm_upload`	Inhalt	Schritt 2 des Uploads: Bestätigt, dass die Datei auf S3 hochgeladen wurde
11	`sutram_create_audio_link`	Inhalt	Erstellt einen Audio-Link (Spotify, SoundCloud usw.)
12	`sutram_create_comment`	Kommentare	Erstellt einen Datei-Level- oder Markdown-Kommentar zu einem Inhaltselement
13	`sutram_create_file_link`	Dateilinks	Erstellt einen Dateilink (symbolische Referenz) zu einer bestehenden Datei
14	`sutram_create_folder`	Ordner	Erstellt einen neuen Ordner oder verschachtelten Pfad
15	`sutram_create_new_version`	Versionierung	Erstellt eine neue Version aus einer veröffentlichten Datei
16	`sutram_create_record`	Datensätze	Erstellt einen neuen Datensatz in einer Kategorie
17	`sutram_create_video_link`	Inhalt	Erstellt einen Video-Link (YouTube, Vimeo usw.)
18	`sutram_create_web_link`	Inhalt	Erstellt einen Web-Link mit automatisch abgerufenem Titel
19	`sutram_delete`	Inhalt	Löscht ein Inhaltselement oder einen Ordner
20	`sutram_delete_comment`	Kommentare	Löscht einen Kommentar und alle seine Antworten
21	`sutram_delete_metadata`	Schema	Löscht eine Metadatendefinition
22	`sutram_delete_record`	Datensätze	Löscht einen Datensatz
23	`sutram_delete_record_category`	Schema	Löscht eine Datensatzkategorie
24	`sutram_disable_versioning`	Versionierung	Konvertiert die Datei zurück in eine Referenz (schreibgeschützt)
25	`sutram_enable_versioning`	Versionierung	Konvertiert die Datei von Referenz zu bearbeitbar
26	`sutram_force_release_lock`	Versionierung	Erzwingt die Freigabe eines Checkouts eines anderen Benutzers (nur Besitzer)
27	`sutram_get_comment_thread`	Kommentare	Ruft einen Kommentar mit seinem vollständigen Antwortstrang ab
28	`sutram_get_folder`	Ordner	Gibt den Inhalt eines Ordners zurück
29	`sutram_get_item`	Inhalt	Ruft vollständige Details und Download-URL eines Inhaltselements ab
30	`sutram_get_item_tag_keys`	Tags	Gibt alle unterschiedlichen Tag-Schlüssel zurück, die auf Inhaltselementen verwendet werden
31	`sutram_get_metadata_definitions`	Schema	Gibt alle Metadatenfelddefinitionen zurück
32	`sutram_get_record_categories`	Schema	Gibt alle Datensatzkategorien zurück
33	`sutram_get_record_category_detail`	Schema	Gibt eine Kategorie mit vollständig aufgelösten Metadaten zurück
34	`sutram_get_tag_keys`	Tags	Gibt alle unterschiedlichen Tag-Schlüssel zurück, die auf Ordnern verwendet werden
35	`sutram_list_comments`	Kommentare	Listet alle übergeordneten Kommentare zu einem Inhaltselement auf
36	`sutram_list_file_links_for_source`	Dateilinks	Listet alle Dateilinks auf, die auf eine Quelldatei verweisen
37	`sutram_list_file_links_in_folder`	Dateilinks	Listet Dateilinks in einem Ordner mit Quelldatei-Details auf
38	`sutram_list_versions`	Versionierung	Listet alle Versionen einer Datei auf
39	`sutram_move_contents`	Ordner	Verschiebt alle Inhalte von einem Ordner in einen anderen
40	`sutram_move_item`	Inhalt	Verschiebt ein einzelnes Inhaltselement in einen anderen Ordner
41	`sutram_project_info`	Projekt	Gibt Projektname, Beschreibung und Einstellungen zurück
42	`sutram_publish_version`	Versionierung	Veröffentlicht einen Dateientwurf und erstellt einen Versions-Snapshot
43	`sutram_remove_enum_values`	Schema	Entfernt Werte aus einer Enum-Metadatendefinition
44	`sutram_rename`	Inhalt	Benennt ein Inhaltselement oder einen Ordner um
45	`sutram_reply_to_comment`	Kommentare	Antwortet auf einen bestehenden übergeordneten Kommentar
46	`sutram_request_upload`	Inhalt	Schritt 1 des Uploads: Gibt eine vorsignierte S3-PUT-URL zurück
47	`sutram_resolve_comment`	Kommentare	Löst einen Kommentarstrang oder öffnet ihn wieder
48	`sutram_search_folders`	Tags	Sucht Ordner nach Tag (einzeln oder UND-Bedingungen)
49	`sutram_search_items`	Tags	Sucht Inhaltselemente nach Tag
50	`sutram_set_folder_tags`	Tags	Setzt Schlüssel-Wert-Tags auf einem Ordner
51	`sutram_set_item_tags`	Tags	Setzt Schlüssel-Wert-Tags auf einem Inhaltselement
52	`sutram_undo_checkin`	Versionierung	Macht den letzten Check-in rückgängig und stellt die vorherige Version wieder her
53	`sutram_update_record`	Datensätze	Aktualisiert die Metadaten eines Datensatzes
54	`sutram_upload_modified_file`	Versionierung	Ersetzt den Dateiinhalt während des Checkouts
55	`sutram_upsert_metadata`	Schema	Erstellt oder aktualisiert eine Metadatenfelddefinition
56	`sutram_upsert_record_category`	Schema	Erstellt oder aktualisiert eine Datensatzkategorie

Kategorien: Projekt (1) · Ordner (3) · Inhalt (8) · Dateilinks (4) · Tags (6) · Versionierung (12) · Kommentare (6) · Schema (8) · Datensätze (4)

Die folgenden Abschnitte beschreiben jedes Tool im Detail, geordnet nach Funktionalität.

sutram_project_info

Gibt Informationen über das aktuelle Projekt zurück.

Parameter: Keine

Beispielantwort:

{
  "project": {
    "id": "a1b2c3d4-...",
    "name": "Construction Site Alpha",
    "description": "Main project documentation",
    "your_role": "member",
    "created_at": "2026-01-15T10:00:00Z"
  }
}

sutram_get_folder

Durchsucht den Inhalt eines Ordners (Unterordner, Dateien und Links). Lassen Sie folder_id weg, um die Stamminhalte aufzulisten.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`folder_id`	string	Nein	Ordner-UUID. Weglassen für Stammverzeichnis.

Beispielantwort:

{
  "folder": {
    "id": null,
    "name": "Root",
    "path": "/"
  },
  "contents": [
    {
      "type": "folder",
      "id": "f1a2b3c4-...",
      "name": "Reports",
      "tags": {"category": "monthly", "department": "engineering"}
    },
    {
      "type": "file",
      "id": "d5e6f7a8-...",
      "name": "site-plan.pdf",
      "content_type": "application/pdf",
      "size": 2450000,
      "filename": "site-plan.pdf"
    },
    {
      "type": "web_link",
      "id": "a1b2c3d4-...",
      "name": "Project Wiki",
      "url": "https://wiki.example.com/project",
      "favicon_url": "https://wiki.example.com/favicon.ico"
    },
    {
      "type": "video_link",
      "id": "e5f6a7b8-...",
      "name": "Site walkthrough",
      "url": "https://www.youtube.com/watch?v=abc123",
      "platform": "youtube",
      "thumbnail_url": "https://img.youtube.com/vi/abc123/hqdefault.jpg"
    },
    {
      "type": "audio_link",
      "id": "c9d0e1f2-...",
      "name": "Meeting recording",
      "url": "https://open.spotify.com/episode/xyz",
      "platform": "spotify",
      "artist_or_author": "Team Alpha"
    }
  ]
}

sutram_create_folder

Erstellt einen neuen Ordner. Unterstützt das Erstellen verschachtelter Hierarchien in einem einzigen Aufruf.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`name`	string	Ja*	Ordnername (zum Erstellen eines einzelnen Ordners)
`path`	string	Ja*	Schrägstrich-getrennter Pfad für verschachteltes Erstellen (z.B. `"A/B/C"`)
`parent_folder_id`	string	Nein	Übergeordneter Ordner-UUID. Weglassen für Stammebene.
`tags`	object	Nein	Frei definierbare Schlüssel-Wert-Tags (z.B. `{"patient": "John", "exam_type": "USG"}`). Bei Verwendung von `path` werden Tags nur auf den tiefsten Ordner angewendet.

*Verwenden Sie entweder name (einzelner Ordner) oder path (verschachtelte Hierarchie), nicht beides.

Verschachteltes Erstellen: Bei Verwendung von path werden Zwischenordner automatisch erstellt. Wenn ein Ordner im Pfad bereits existiert, wird er wiederverwendet — die Operation ist idempotent.

Beispiel — einzelner Ordner:

{ "name": "Reports", "parent_folder_id": "f1a2b3c4-..." }

Beispiel — verschachtelte Hierarchie mit Tags:

{
  "path": "Dr. Decio Mion Junior/USG ABDOME TOTAL/2024-12-12",
  "tags": {"patient": "João Silva", "exam_type": "USG ABDOME TOTAL", "year": "2024"}
}

Dies erstellt drei Ordner in einem Aufruf und gibt den tiefsten (2024-12-12) mit den angegebenen Tags zurück.

sutram_request_upload

Schritt 1 des direkten Upload-Ablaufs. Validiert die Datei und gibt eine vorsignierte S3-PUT-URL zurück. Die Datei wird direkt vom Client auf S3 hochgeladen — keine Daten passieren die Sutram-Webserver.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`filename`	string	Ja	Dateiname mit Erweiterung (z.B. `report.pdf`)
`file_size`	integer	Ja	Dateigröße in Bytes
`content_type`	string	Nein	MIME-Typ. Wird automatisch aus der Erweiterung erkannt, wenn weggelassen.
`folder_id`	string	Nein	Zielordner-UUID. Weglassen für Stammverzeichnis.

Beispielantwort:

{
  "upload_url": "https://eikon-storage.s3.amazonaws.com/projects/.../files/abc123.pdf?X-Amz-...",
  "s3_key": "projects/a1b2c3d4-.../files/abc123.pdf",
  "file_id": "abc123-...",
  "folder_id": null,
  "expires_in": 900
}

sutram_confirm_upload

Schritt 2 des direkten Upload-Ablaufs. Rufen Sie dies auf, nachdem die Datei auf die vorsignierte URL hochgeladen wurde. Überprüft, ob das S3-Objekt existiert, erstellt den Dateidatensatz, aktualisiert die Speichernutzung und reiht die Komprimierung ein, falls zutreffend.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`file_id`	string	Ja	Datei-UUID von `sutram_request_upload`
`s3_key`	string	Ja	S3-Schlüssel von `sutram_request_upload`
`filename`	string	Ja	Originaler Dateiname mit Erweiterung
`content_type`	string	Ja	MIME-Typ der Datei
`file_size`	integer	Ja	Dateigröße in Bytes
`folder_id`	string	Nein	Zielordner-UUID (muss mit der Anfrage übereinstimmen)

Beispielantwort:

{
  "file": {
    "id": "abc123-...",
    "name": "report.pdf",
    "size": 2450000,
    "content_type": "application/pdf",
    "created_at": "2026-02-27T10:00:00Z"
  }
}

Vollständiger Upload-Ablauf als Beispiel:

# 1. Request upload (via MCP tool call)
#    → Returns upload_url, s3_key, file_id

# 2. Upload file directly to S3
curl -X PUT \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf \
  "https://eikon-storage.s3.amazonaws.com/projects/.../files/abc123.pdf?X-Amz-..."

# 3. Confirm upload (via MCP tool call)
#    → File record created, storage updated, web UI updates in real-time

sutram_create_web_link

Erstellt einen Web-Link im Projekt. Sutram ruft automatisch den Seitentitel und das Favicon von der URL ab.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`url`	string	Ja	URL der Webseite (muss http oder https sein)
`name`	string	Nein	Anzeigename. Wird automatisch vom Seitentitel abgerufen, wenn weggelassen.
`folder_id`	string	Nein	Zielordner-UUID. Weglassen für Stammverzeichnis.

Beispielantwort:

{
  "web_link": {
    "id": "a1b2c3d4-...",
    "name": "Sutram Documentation",
    "url": "https://docs.sutram.io",
    "favicon_url": "https://docs.sutram.io/favicon.ico",
    "fetched_title": "Sutram Documentation",
    "created_at": "2026-02-09T14:30:00Z"
  }
}

sutram_create_video_link

Erstellt einen Video-Link im Projekt. Unterstützt YouTube, Vimeo, DailyMotion, Wistia, Loom und TikTok. Erkennt automatisch die Plattform und extrahiert die Video-ID aus der URL.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`url`	string	Ja	URL des Videos (z.B. `https://www.youtube.com/watch?v=...`)
`name`	string	Nein	Anzeigename. Standardmäßig die URL, wenn weggelassen.
`folder_id`	string	Nein	Zielordner-UUID. Weglassen für Stammverzeichnis.

Beispielantwort:

{
  "video_link": {
    "id": "e5f6a7b8-...",
    "name": "Project overview",
    "url": "https://www.youtube.com/watch?v=abc123",
    "platform": "youtube",
    "video_id": "abc123",
    "thumbnail_url": "https://img.youtube.com/vi/abc123/hqdefault.jpg",
    "created_at": "2026-02-09T14:30:00Z"
  }
}

sutram_create_audio_link

Erstellt einen Audio-Link im Projekt. Unterstützt Spotify, SoundCloud, Apple Podcasts und weitere. Erkennt automatisch die Plattform und extrahiert die Audio-ID aus der URL.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`url`	string	Ja	URL des Audioinhalts (z.B. `https://open.spotify.com/track/...`)
`name`	string	Nein	Anzeigename. Standardmäßig die URL, wenn weggelassen.
`folder_id`	string	Nein	Zielordner-UUID. Weglassen für Stammverzeichnis.

Beispielantwort:

{
  "audio_link": {
    "id": "c9d0e1f2-...",
    "name": "Weekly standup recap",
    "url": "https://open.spotify.com/episode/xyz789",
    "platform": "spotify",
    "artist_or_author": "Team Alpha",
    "thumbnail_url": "https://i.scdn.co/image/abc",
    "created_at": "2026-02-09T14:30:00Z"
  }
}

sutram_create_file_link

Erstellt einen Dateilink (symbolische Referenz) zu einer bestehenden Datei im Projekt. Der Link erscheint als schreibgeschützte Referenz ohne Duplizierung von Speicher oder Versionierung. Die Quelle muss eine Datei sein (kein Link oder anderer Dateilink). Wenn die Quelldatei gelöscht wird, werden alle zugehörigen Dateilinks automatisch entfernt.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`source_content_item_id`	string	Ja	UUID des Quell-Datei-Inhaltselements, auf das verlinkt werden soll
`name`	string	Nein	Anzeigename (standardmäßig der Name der Quelldatei)
`folder_id`	string	Nein	Zielordner-UUID (weglassen für Stammverzeichnis)
`description`	string	Nein	Beschreibung des Dateilinks

Beispielanfrage:

{
  "source_content_item_id": "d5e6f7a8-...",
  "folder_id": "b2c3d4e5-...",
  "name": "Lab results (link)"
}

Beispielantwort:

{
  "file_link": {
    "id": "f1a2b3c4-...",
    "name": "Lab results (link)",
    "source_content_item_id": "d5e6f7a8-...",
    "folder_id": "b2c3d4e5-...",
    "created_at": "2026-03-14T10:00:00Z"
  }
}

sutram_bulk_create_file_links

Erstellt Dateilinks in großer Menge für alle Dateien (oder eine gefilterte Teilmenge) in einem Quellordner und platziert sie in einem Zielordner. Überspringt automatisch Dateien, die bereits einen Link im Zielordner haben (Deduplizierung). Ideal für Arbeitsabläufe wie das Verlinken mehrerer Untersuchungsdateien zu einem zentralen Berichtsordner.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`source_folder_id`	string	Ja	UUID des Quellordners mit den zu verlinkenden Dateien
`target_folder_id`	string	Ja	UUID des Zielordners, in dem Dateilinks erstellt werden
`name_pattern`	string	Nein	Teilstring-Filter (Groß-/Kleinschreibung-unabhängig) auf Quelldateinamen. Nur übereinstimmende Dateien werden verlinkt.
`recursive`	boolean	Nein	Dateien aus Unterordnern des Quellordners einbeziehen (Standard: false)

Beispielanfrage:

{
  "source_folder_id": "a1b2c3d4-...",
  "target_folder_id": "e5f6a7b8-...",
  "name_pattern": "laudo",
  "recursive": true
}

Beispielantwort:

{
  "created": 5,
  "skipped": 2,
  "file_links": [
    {
      "id": "f1a2b3c4-...",
      "name": "laudo-hemograma.pdf",
      "source_content_item_id": "d5e6f7a8-...",
      "folder_id": "e5f6a7b8-..."
    },
    {
      "id": "f2b3c4d5-...",
      "name": "laudo-raio-x.pdf",
      "source_content_item_id": "c4d5e6f7-...",
      "folder_id": "e5f6a7b8-..."
    }
  ]
}

Tipp: Ein erneutes Ausführen desselben Befehls überspringt alle zuvor verlinkten Dateien ("created": 0, "skipped": 7), sodass eine Wiederholung sicher ist.

sutram_list_file_links_for_source

Listet alle Dateilinks auf, die auf eine bestimmte Quelldatei verweisen. Beantwortet die Frage: "Wo wird diese Datei referenziert?" Gibt jeden Link mit seinem Ordnerpfad zurück.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`source_content_item_id`	string	Ja	UUID des Quell-Datei-Inhaltselements

Beispielanfrage:

{
  "source_content_item_id": "d5e6f7a8-..."
}

Beispielantwort:

{
  "source": {
    "id": "d5e6f7a8-...",
    "name": "hemograma-completo.pdf",
    "type": "file"
  },
  "file_links": [
    {
      "id": "f1a2b3c4-...",
      "name": "hemograma-completo.pdf",
      "folder_id": "b2c3d4e5-...",
      "folder_path": "Pacientes/João Silva/Laudos",
      "created_at": "2026-03-14T10:00:00Z"
    },
    {
      "id": "f2b3c4d5-...",
      "name": "hemograma-completo.pdf",
      "folder_id": "c3d4e5f6-...",
      "folder_path": "Relatórios/Março 2026",
      "created_at": "2026-03-14T10:05:00Z"
    }
  ],
  "count": 2
}

sutram_list_file_links_in_folder

Listet alle Dateilinks in einem Ordner auf, angereichert mit Quelldatei-Details (Name, Inhaltstyp, Dateigröße, Ordnerpfad). Im Gegensatz zu sutram_get_folder liefert dies vollständige Informationen über die Quelldatei, auf die jeder Link verweist.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`folder_id`	string	Nein	Ordner-UUID (weglassen für Stammverzeichnis)

Beispielanfrage:

{
  "folder_id": "e5f6a7b8-..."
}

Beispielantwort:

{
  "folder_id": "e5f6a7b8-...",
  "file_links": [
    {
      "id": "f1a2b3c4-...",
      "name": "hemograma-completo.pdf",
      "created_at": "2026-03-14T10:00:00Z",
      "source": {
        "id": "d5e6f7a8-...",
        "name": "hemograma-completo.pdf",
        "content_type": "application/pdf",
        "file_size": 245760,
        "folder_path": "Exames/Laboratório"
      }
    },
    {
      "id": "f2b3c4d5-...",
      "name": "raio-x-torax.dcm",
      "created_at": "2026-03-14T10:05:00Z",
      "source": {
        "id": "c4d5e6f7-...",
        "name": "raio-x-torax.dcm",
        "content_type": "application/dicom",
        "file_size": 5242880,
        "folder_path": "Exames/Imagem"
      }
    }
  ],
  "count": 2
}

sutram_get_item

Ruft vollständige Details eines Inhaltselements nach ID ab. Für Dateien werden Metadaten und eine vorsignierte Download-URL zurückgegeben. Für Links (Web, Video, Audio, Dateilink) werden URL, Plattforminformationen und Metadaten zurückgegeben.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`content_item_id`	string	Ja	UUID des Inhaltselements

Beispielantwort (Datei):

{
  "id": "d5e6f7a8-...",
  "type": "file",
  "name": "site-plan",
  "description": null,
  "tags": {"category": "planta", "year": "2024"},
  "folder_id": "f1a2b3c4-...",
  "created_at": "2026-01-20T10:00:00Z",
  "filename": "site-plan.pdf",
  "file_size": 2450000,
  "content_type": "application/pdf",
  "version": 1,
  "download_url": "https://storage.example.com/projects/.../site-plan.pdf?X-Amz-..."
}

Beispielantwort (Web-Link):

{
  "id": "a1b2c3d4-...",
  "type": "web_link",
  "name": "Project Wiki",
  "description": null,
  "tags": {},
  "folder_id": null,
  "created_at": "2026-02-01T08:00:00Z",
  "url": "https://wiki.example.com/project",
  "fetched_title": "Project Wiki - Home",
  "fetched_description": "Documentation for the project",
  "favicon_url": "https://wiki.example.com/favicon.ico"
}

Beispielantwort (Video-Link):

{
  "id": "e5f6a7b8-...",
  "type": "video_link",
  "name": "Site walkthrough",
  "description": null,
  "tags": {"topic": "neurologia"},
  "folder_id": "f1a2b3c4-...",
  "created_at": "2026-02-05T16:00:00Z",
  "url": "https://www.youtube.com/watch?v=abc123",
  "platform": "youtube",
  "video_id": "abc123",
  "thumbnail_url": "https://img.youtube.com/vi/abc123/hqdefault.jpg",
  "duration_seconds": null,
  "fetched_title": "Construction Site Alpha - Full Tour"
}

sutram_delete

Löscht ein Inhaltselement (Datei, Web-Link, Video-Link, Audio-Link) oder einen Ordner aus dem Projekt.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`item_id`	string	Ja	Inhaltselement- oder Ordner-UUID
`item_type`	string	Ja	`"content_item"` oder `"folder"`. Verwenden Sie `"content_item"` für jeden Inhaltstyp (Dateien, Web-Links, Video-Links, Audio-Links).

sutram_rename

Benennt ein Inhaltselement (Datei, Web-Link, Video-Link, Audio-Link) oder einen Ordner um.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`item_id`	string	Ja	Inhaltselement- oder Ordner-UUID
`item_type`	string	Ja	`"content_item"` oder `"folder"`. Verwenden Sie `"content_item"` für jeden Inhaltstyp (Dateien, Web-Links, Video-Links, Audio-Links).
`new_name`	string	Ja	Neuer Name (für Dateien mit Erweiterung angeben)

sutram_move_contents

Verschiebt alle Inhalte (Unterordner und Dateien) von einem Quellordner in einen Zielordner. Der Quellordner wird geleert, aber nicht gelöscht. Namenskonflikte werden automatisch behandelt.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`source_folder_id`	string	Ja	UUID des zu leerenden Quellordners
`target_folder_id`	string	Ja	UUID des Zielordners, der die Inhalte aufnimmt

Behandlung von Namenskonflikten: Wenn ein Unterordner oder eine Datei mit dem gleichen Namen bereits im Zielordner existiert, benennt Sutram das verschobene Element automatisch um, indem ein numerisches Suffix hinzugefügt wird: Exams wird zu Exams (1), report.pdf wird zu report (1).pdf usw.

Validierungsregeln:

Quelle und Ziel müssen verschiedene Ordner sein
Das Ziel darf kein Unterordner der Quelle sein (verhindert zirkuläre Verschiebungen)
Beide Ordner müssen im aktuellen Projekt existieren

Beispielantwort:

{
  "moved": {
    "folders": 3,
    "content_items": 12
  },
  "renamed": {
    "folders": ["Exams (1)"],
    "files": ["report (1).pdf"]
  },
  "source_folder_id": "abc123-...",
  "target_folder_id": "def456-..."
}

sutram_move_item

Verschiebt ein einzelnes Inhaltselement (Datei oder Link) in einen anderen Ordner. Namenskonflikte werden automatisch behandelt.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`content_item_id`	string	Ja	UUID des zu verschiebenden Inhaltselements
`target_folder_id`	string/null	Nein	UUID des Zielordners (null für Stammverzeichnis)

Behandlung von Namenskonflikten: Wenn eine Datei mit dem gleichen Namen bereits im Zielordner existiert, benennt Sutram die verschobene Datei automatisch um, indem ein numerisches Suffix hinzugefügt wird: report.pdf wird zu report (1).pdf usw.

Beispielantwort (ohne Konflikt):

{
  "moved": true,
  "renamed": false,
  "new_filename": null,
  "content_item": {
    "id": "abc123-...",
    "name": "report",
    "folder_id": "def456-..."
  }
}

Beispielantwort (mit Umbenennung):

{
  "moved": true,
  "renamed": true,
  "new_filename": "report (1).pdf",
  "content_item": {
    "id": "abc123-...",
    "name": "report (1)",
    "folder_id": "def456-..."
  }
}

sutram_set_folder_tags

Setzt frei definierbare Schlüssel-Wert-Tags auf einem Ordner. Ersetzt alle bestehenden Tags. Senden Sie {}, um alle Tags zu löschen.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`folder_id`	string	Ja	Ordner-UUID
`tags`	object	Ja	Zu setzende Schlüssel-Wert-Tags. Senden Sie `{}`, um alle Tags zu löschen.

Limits: Maximal 50 Tags pro Ordner. Schlüssel max. 100 Zeichen, Wert max. 500 Zeichen.

Semantik: Dies ist eine PUT-Operation — sie ersetzt alle bestehenden Tags. Um einen Tag hinzuzufügen, ohne andere zu entfernen, lesen Sie zuerst die aktuellen Tags (über sutram_get_folder), führen Sie Ihre Änderungen zusammen und rufen Sie dann sutram_set_folder_tags mit dem vollständigen Satz auf.

Beispiel — Tags setzen:

{
  "folder_id": "f1a2b3c4-...",
  "tags": {"patient": "João Silva", "exam_type": "USG", "year": "2024"}
}

Beispiel — alle Tags löschen:

{
  "folder_id": "f1a2b3c4-...",
  "tags": {}
}

Beispielantwort:

{
  "id": "f1a2b3c4-...",
  "name": "2024-12-12",
  "tags": {"patient": "João Silva", "exam_type": "USG", "year": "2024"}
}

sutram_search_folders

Sucht Ordner nach Tag. Unterstützt einzelne oder mehrere UND-Bedingungen. Alle Abgleiche sind Groß-/Kleinschreibung-unabhängig für Schlüssel und Werte. Werte unterstützen Teilstringabgleich (z.B. "orto" stimmt mit "Ortopedia" überein). Verwenden Sie folder_id, um die Suche auf Nachfolger eines bestimmten Ordners zu beschränken.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`tag_name`	string	Nein*	Tag-Schlüssel für die Suche (Einzelbedingungsmodus). Groß-/Kleinschreibung-unabhängig.
`tag_value`	string	Nein	Zu vergleichender Wert (Einzelbedingungsmodus). Teilstringabgleich, Groß-/Kleinschreibung-unabhängig.
`conditions`	array	Nein*	Mehrere UND-Bedingungen. Jedes Objekt hat `key` (erforderlich) und `value` (optional).
`folder_id`	string	Nein	Ordner-UUID zur Einschränkung der Suche. Sucht nur in Nachfolgern dieses Ordners.

*Verwenden Sie entweder tag_name (Einzelbedingung) oder conditions (mehrere UND-Bedingungen).

Suchverhalten:

Schlüsselabgleich: Groß-/Kleinschreibung-unabhängiger exakter Abgleich ("Patient" stimmt mit "patient" überein)
Wertabgleich: Groß-/Kleinschreibung-unabhängiger Teilstringabgleich ("orto" stimmt mit "Ortopedia" überein, "joão" stimmt mit "João Silva" überein)
Ohne Wert: Wenn der Wert weggelassen wird, wird jeder Ordner mit dem Schlüssel gefunden, unabhängig vom Wert
Mehrere Bedingungen: Alle Bedingungen müssen zutreffen (UND-Logik)

Beispiel — alle Ordner mit Tag "patient" finden:

{ "tag_name": "patient" }

Beispiel — Ordner für einen bestimmten Patienten finden (Teilstringabgleich):

{ "tag_name": "patient", "tag_value": "joão" }

Dies findet Ordner, bei denen der Tag "patient" "joão" enthält (z.B. "João Silva", "João Pedro").

Beispiel — UND-Suche mit mehreren Bedingungen:

{
  "conditions": [
    { "key": "patient", "value": "joão" },
    { "key": "exam_type", "value": "USG" }
  ]
}

Dies gibt nur Ordner zurück, die beide Bedingungen erfüllen.

Beispiel — nur innerhalb einer bestimmten Ordnerhierarchie suchen:

{ "tag_name": "exam_type", "folder_id": "a1b2c3d4-..." }

Beispielantwort:

{
  "folders": [
    {
      "id": "f1a2b3c4-...",
      "name": "2024-12-12",
      "path": "/Dr. Decio Mion Junior/USG ABDOME TOTAL/2024-12-12",
      "tags": {"patient": "João Silva", "exam_type": "USG", "year": "2024"}
    }
  ],
  "count": 1
}

sutram_get_tag_keys

Gibt alle unterschiedlichen Tag-Schlüssel zurück, die über Ordner im Projekt verwendet werden. Nützlich, um vor einer Suche zu ermitteln, welche Tags verfügbar sind. Verwenden Sie folder_id, um auf Nachfolger eines bestimmten Ordners zu beschränken.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`folder_id`	string	Nein	Ordner-UUID zur Einschränkung. Gibt nur Schlüssel von Nachfolgern dieses Ordners zurück.

Beispiel — alle Tag-Schlüssel im Projekt abrufen:

{}

Beispiel — Tag-Schlüssel innerhalb einer Ordnerhierarchie abrufen:

{ "folder_id": "a1b2c3d4-..." }

Beispielantwort:

{
  "keys": ["exam_type", "patient", "specialty", "year"],
  "count": 4
}

sutram_set_item_tags

Setzt frei definierbare Schlüssel-Wert-Tags auf einem Inhaltselement. Ersetzt alle bestehenden Tags. Senden Sie {}, um alle Tags zu löschen.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`content_item_id`	string	Ja	Inhaltselement-UUID
`tags`	object	Ja	Zu setzende Schlüssel-Wert-Tags. Senden Sie `{}`, um alle Tags zu löschen.

Limits: Maximal 50 Tags pro Element. Schlüssel max. 100 Zeichen, Wert max. 500 Zeichen.

Semantik: Dies ist eine PUT-Operation — sie ersetzt alle bestehenden Tags. Um einen Tag hinzuzufügen, ohne andere zu entfernen, lesen Sie zuerst die aktuellen Tags (über sutram_get_item), führen Sie Ihre Änderungen zusammen und rufen Sie dann sutram_set_item_tags mit dem vollständigen Satz auf.

Beispiel — Tags setzen:

{
  "content_item_id": "d5e6f7a8-...",
  "tags": {"category": "report", "year": "2024", "topic": "neurologia"}
}

Beispiel — alle Tags löschen:

{
  "content_item_id": "d5e6f7a8-...",
  "tags": {}
}

Beispielantwort:

{
  "id": "d5e6f7a8-...",
  "name": "site-plan",
  "tags": {"category": "report", "year": "2024", "topic": "neurologia"}
}

sutram_search_items

Sucht Inhaltselemente nach Tag. Unterstützt einzelne oder mehrere UND-Bedingungen. Alle Abgleiche sind Groß-/Kleinschreibung-unabhängig für Schlüssel und Werte. Werte unterstützen Teilstringabgleich (z.B. "neuro" stimmt mit "Neurologia" überein). Verwenden Sie folder_id, um die Suche auf einen bestimmten Ordner zu beschränken, und type, um nach Inhaltstyp zu filtern.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`tag_name`	string	Nein*	Tag-Schlüssel für die Suche (Einzelbedingungsmodus). Groß-/Kleinschreibung-unabhängig.
`tag_value`	string	Nein	Zu vergleichender Wert (Einzelbedingungsmodus). Teilstringabgleich, Groß-/Kleinschreibung-unabhängig.
`conditions`	array	Nein*	Mehrere UND-Bedingungen. Jedes Objekt hat `key` (erforderlich) und `value` (optional).
`folder_id`	string	Nein	Ordner-UUID zur Einschränkung der Suche.
`type`	string	Nein	Inhaltstyp-Filter: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

*Verwenden Sie entweder tag_name (Einzelbedingung) oder conditions (mehrere UND-Bedingungen).

Beispiel — alle Elemente mit Tag "topic" finden:

{ "tag_name": "topic" }

Beispiel — Elemente für ein bestimmtes Thema finden (Teilstringabgleich):

{ "tag_name": "topic", "tag_value": "neuro" }

Beispiel — UND-Suche mit mehreren Bedingungen:

{
  "conditions": [
    { "key": "topic", "value": "neuro" },
    { "key": "year", "value": "2024" }
  ]
}

Beispiel — nur Video-Links in einem bestimmten Ordner suchen:

{ "tag_name": "topic", "folder_id": "f1a2b3c4-...", "type": "video_link" }

Beispielantwort:

{
  "items": [
    {
      "id": "d5e6f7a8-...",
      "type": "file",
      "name": "site-plan",
      "tags": {"topic": "neurologia", "year": "2024"},
      "folder_id": "f1a2b3c4-..."
    }
  ],
  "count": 1
}

sutram_get_item_tag_keys

Gibt alle unterschiedlichen Tag-Schlüssel zurück, die über Inhaltselemente im Projekt verwendet werden. Nützlich, um vor einer Suche zu ermitteln, welche Tags verfügbar sind. Verwenden Sie folder_id, um auf einen bestimmten Ordner zu beschränken, und type, um nach Inhaltstyp zu filtern.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`folder_id`	string	Nein	Ordner-UUID zur Einschränkung.
`type`	string	Nein	Inhaltstyp-Filter: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

Beispiel — alle Inhalts-Tag-Schlüssel im Projekt abrufen:

{}

Beispiel — Tag-Schlüssel nur für Video-Links abrufen:

{ "type": "video_link" }

Beispielantwort:

{
  "keys": ["category", "format", "topic", "year"],
  "count": 4
}

Dateiversionierung

Sutram unterstützt einen vollständigen Versionierungsablauf für Dateien über MCP. Dies ermöglicht KI-Assistenten, Versionskontrolle zu aktivieren, Dateien zur exklusiven Bearbeitung auszuchecken, Änderungen hochzuladen und Versionen zu veröffentlichen.

Arbeitsablauf

1. Enable versioning     →  sutram_enable_versioning
2. Check out file        →  sutram_checkout_file
3. Upload modification   →  sutram_request_upload + PUT to S3 + sutram_upload_modified_file
4. Check in file         →  sutram_checkin_file
5. Publish version       →  sutram_publish_version
6. Create new version    →  sutram_create_new_version  (starts new cycle at step 2)

Versionierungs-Tools

Tool	Beschreibung	Berechtigung
`sutram_enable_versioning`	Datei von Referenz zu bearbeitbar konvertieren (Versionierung starten)	Besitzer, Mitglied
`sutram_disable_versioning`	Datei zurück in Referenz konvertieren (Versionierung stoppen)	Besitzer, Mitglied
`sutram_checkout_file`	Datei zur exklusiven Bearbeitung auschecken	Besitzer, Admin, Mitglied
`sutram_checkin_file`	Checkout-Sperre freigeben	Checkout-Benutzer
`sutram_cancel_checkout`	Checkout ohne Änderungen abbrechen	Checkout-Benutzer
`sutram_force_release_lock`	Checkout eines anderen Benutzers erzwungen freigeben	Nur Besitzer
`sutram_publish_version`	Dateientwurf veröffentlichen und Versions-Snapshot erstellen	Nur Besitzer
`sutram_create_new_version`	Neue Version aus veröffentlichter Datei starten	Nur Besitzer
`sutram_undo_checkin`	Letzten Check-in rückgängig machen, vorherige Version wiederherstellen	Letzter Check-in-Benutzer
`sutram_list_versions`	Alle veröffentlichten Versionen mit Download-URLs auflisten	Jedes Mitglied
`sutram_upload_modified_file`	Dateiinhalt während des Checkouts ersetzen	Checkout-Benutzer

Parameter

Alle Versionierungs-Tools erfordern content_item_id (UUID des Inhaltselements).

sutram_upload_modified_file erfordert zusätzlich:

Parameter	Typ	Beschreibung
`s3_key`	string	S3-Schlüssel von `sutram_request_upload`
`file_name`	string	Dateiname mit Erweiterung
`file_size`	integer	Dateigröße in Bytes
`content_type`	string	MIME-Typ

Beispiel: Vollständiger Versionierungsablauf

// 1. Enable versioning on a file
→ sutram_enable_versioning { "content_item_id": "abc-123" }
← { "file": { "file_type": "editable", "lifecycle_status": "draft", "version": 1 } }

// 2. Check out the file
→ sutram_checkout_file { "content_item_id": "abc-123" }
← { "file": { "checked_out_by": "Alice", ... } }

// 3. Get presigned URL for the modified file
→ sutram_request_upload { "filename": "report_v2.pdf", "file_size": 5000 }
← { "upload_url": "https://s3...", "s3_key": "projects/.../file.pdf" }

// 4. PUT modified file to S3 (HTTP PUT to upload_url)

// 5. Upload the modification
→ sutram_upload_modified_file {
    "content_item_id": "abc-123",
    "s3_key": "projects/.../file.pdf",
    "file_name": "report_v2.pdf",
    "file_size": 5000,
    "content_type": "application/pdf"
  }

// 6. Check in the file
→ sutram_checkin_file { "content_item_id": "abc-123" }

// 7. Publish the version (owner only)
→ sutram_publish_version { "content_item_id": "abc-123" }
← { "file": { "lifecycle_status": "published", "version": 1 } }

// 8. List versions
→ sutram_list_versions { "content_item_id": "abc-123" }
← { "versions": [{ "version_number": 1, "download_url": "...", ... }], "count": 1 }

Datensatzkategorien & Datensätze

Sutram unterstützt strukturierte Datensätze mit Metadatenschemata und automatisch generierten Slugs. Dies ermöglicht KI-Assistenten, Metadatenfelder zu definieren, Datensatzkategorien zu erstellen und Datensätze programmatisch zu verwalten.

Plananforderung: Datensatz- und Schemaverwaltungs-Tools erfordern einen Plan mit aktivierter Datensatz-Funktion (Plus oder höher). Schreibgeschützte Tools (sutram_get_metadata_definitions, sutram_get_record_categories, sutram_get_record_category_detail) sind in allen Plänen verfügbar.

Konzepte

Metadatendefinitionen — Feldschemata, die die Typen, Bezeichnungen und erlaubten Werte für Metadatenfelder definieren (z.B. "language" als Enum mit den Werten "PT", "EN", "ES").
Datensatzkategorien — Vorlagen, die definieren, welche Metadatenfelder ein Datensatz verwendet, ihre Reihenfolge, wie die Nummernbasis berechnet wird (computed_from) und wie der Slug (Datensatzname) zusammengesetzt wird (slug_from).
Datensätze — Ordner, die mit einer Kategorie erstellt werden, mit validierten Metadaten und einem automatisch generierten Slug.

Slug-Generierung

Datensätze haben einen automatisch generierten Slug (wird als Datensatzname verwendet). Der Slug wird in zwei Schritten erstellt:

Nummernbasis — Bestimmt durch die computed_from-Einträge auf einem berechneten Metadaten-Tag. Dies definiert, welche Feldwerte den Eindeutigkeitsschlüssel für die sequentielle Nummerierung bilden.
Slug-Zusammensetzung — Bestimmt durch die slug_from-Einträge der Kategorie. Dies definiert, welche Feldwerte (einschließlich des berechneten Tags) den endgültigen Slug bilden.

Ohne slug_from (abwärtskompatibel): Slug = number_base + separator + sequence_number (z.B. 0100-200-001).

Mit slug_from: Der Slug wird aus den referenzierten Feldern in Reihenfolge zusammengesetzt (z.B. MD-3010.95-0000-000-SWA-001).

Schema-Tools

Tool	Beschreibung	Berechtigung
`sutram_get_metadata_definitions`	Alle Metadatendefinitionen auflisten	Jedes Mitglied
`sutram_get_record_categories`	Alle Datensatzkategorien auflisten	Jedes Mitglied
`sutram_get_record_category_detail`	Kategorie mit aufgelösten Metadaten (Bezeichnungen, Typen, erlaubte Werte)	Jedes Mitglied
`sutram_upsert_metadata`	Metadatendefinition erstellen oder aktualisieren	Nur Besitzer
`sutram_delete_metadata`	Metadatendefinition löschen (schlägt fehl, wenn in Verwendung)	Nur Besitzer
`sutram_add_enum_values`	Werte zu einer Enum-Definition hinzufügen (zusammenführen, deduplizieren, sortieren)	Nur Besitzer
`sutram_remove_enum_values`	Werte aus einer Enum-Definition nach Code entfernen	Nur Besitzer
`sutram_upsert_record_category`	Datensatzkategorie erstellen oder aktualisieren	Nur Besitzer
`sutram_delete_record_category`	Datensatzkategorie löschen	Nur Besitzer

Datensatz-CRUD-Tools

Tool	Beschreibung	Berechtigung
`sutram_create_record`	Datensatz mit Kategorie, Metadaten und automatisch generiertem Slug erstellen	Besitzer, Admin, Mitglied
`sutram_update_record`	Datensatz-Metadaten aktualisieren (berechnet Slug bei Bedarf neu)	Besitzer, Admin, Mitglied
`sutram_delete_record`	Datensatz und alle seine Inhalte rekursiv löschen	Besitzer, Admin, Mitglied

sutram_get_metadata_definitions

Gibt alle Metadatendefinitionen für das Projekt zurück. Jede Definition hat einen Schlüssel und Eigenschaften: Bezeichnung, Typ (text, enum, boolean, date, computed) und optionale Werte, depends_on, values_map.

Parameter: Keine

sutram_get_record_categories

Gibt alle Datensatzkategorien für das Projekt zurück. Jede Kategorie definiert, welche Metadatenfelder ein Datensatz verwendet, die Slug-Konfiguration und die Reihenfolge.

Parameter: Keine

sutram_get_record_category_detail

Gibt eine Datensatzkategorie mit vollständig aufgelösten Metadaten zurück (Bezeichnungen, Typen, erlaubte Werte aus den Definitionen). Verwenden Sie dies, um zu verstehen, welche Felder vor dem Erstellen eines Datensatzes benötigt werden.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`category_id`	string	Ja	Datensatzkategorie-ID

sutram_upsert_metadata

Erstellt oder aktualisiert eine Metadatendefinition (Feldschema). Für Enum-Typen geben Sie das vollständige values-Array an. Für große Enums bevorzugen Sie sutram_add_enum_values für inkrementelle Ergänzungen.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`key`	string	Ja	Eindeutiger Schlüssel (snake_case, z.B. `"specialty"`)
`definition`	object	Ja	Definition mit `label`, `type` und optionalen Feldern

Unterstützte Typen: text, enum, boolean, date, computed.

Beispiel — einfaches Enum erstellen:

{
  "key": "language",
  "definition": {
    "label": "Language",
    "type": "enum",
    "values": [
      { "label": "Portuguese", "code": "PT" },
      { "label": "English", "code": "EN" }
    ]
  }
}

sutram_delete_metadata

Löscht eine Metadatendefinition. Schlägt fehl, wenn die Definition derzeit von einer Datensatzkategorie verwendet wird.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`key`	string	Ja	Schlüssel der zu löschenden Definition

sutram_add_enum_values

Fügt Werte zu einer bestehenden Enum-Metadatendefinition hinzu. Neue Werte werden mit bestehenden zusammengeführt — Duplikate (nach Code) werden übersprungen. Werte werden nach dem Zusammenführen nach Code sortiert. Verwenden Sie dies anstelle von sutram_upsert_metadata, wenn Sie mit großen Enums arbeiten, um das Senden des gesamten Wertearrays zu vermeiden.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`key`	string	Ja	Schlüssel der Enum-Definition
`values`	array	Ja	Array von `{label, code}`-Objekten zum Hinzufügen

Beispiel — Werte zu einem bestehenden Enum mit 800+ Einträgen hinzufügen:

{
  "key": "area_atividade",
  "values": [
    { "label": "Automação Industrial", "code": "0999" },
    { "label": "Telecomunicações", "code": "1050" }
  ]
}

Beispielantwort:

{
  "key": "area_atividade",
  "added": 2,
  "skipped_duplicates": 0,
  "total_values": 886
}

sutram_remove_enum_values

Entfernt Werte aus einer bestehenden Enum-Metadatendefinition anhand ihrer Codes.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`key`	string	Ja	Schlüssel der Enum-Definition
`codes`	array	Ja	Array von Code-Strings zum Entfernen

Beispiel:

{
  "key": "area_atividade",
  "codes": ["0999", "1050"]
}

Beispielantwort:

{
  "key": "area_atividade",
  "removed": 2,
  "not_found": 0,
  "total_values": 884
}

sutram_upsert_record_category

Erstellt oder aktualisiert eine Datensatzkategorie. Metadaten müssen auf bestehende Definitionen verweisen. Verwenden Sie computed_from bei einem Metadateneintrag, um die Nummernbasis (Eindeutigkeit) zu definieren. Verwenden Sie slug_from auf Kategorieebene, um zu definieren, wie der Slug (Datensatzname) zusammengesetzt wird.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`category_id`	string	Ja	Eindeutige Kategorie-ID (snake_case)
`category`	object	Ja	Kategoriedefinition (siehe Felder unten)

Kategoriefelder:

Feld	Typ	Erforderlich	Beschreibung
`name`	string	Ja	Anzeigename für die Kategorie
`metadata`	array	Ja	Array von Metadatenfeld-Referenzen (siehe unten)
`slug_separator`	string	Nein	Trennzeichen zwischen Slug-Teilen (Standard: `"-"`)
`slug_from`	array	Nein	Definiert die Slug-Zusammensetzung. Jeder Eintrag hat `key` und `use` (`"code"` oder `"label"`). Wenn weggelassen, Slug = number_base + separator + sequence_number

Metadateneintrag-Felder:

Feld	Typ	Erforderlich	Beschreibung
`key`	string	Ja	Schlüssel einer bestehenden Metadatendefinition
`required`	boolean	Nein	Ob dieses Feld erforderlich ist (Standard: false)
`order`	integer	Nein	Anzeigereihenfolge (0-basiert)
`computed_from`	array	Nein	Nur für berechnete Tags. Definiert die Nummernbasis. Jeder Eintrag hat `key` und `use` (`"code"` oder `"label"`)
`sequence_digits`	integer	Nein	Nur für berechnete Tags. Ziffern für die Sequenznummer (2-4, Standard: 2)

Beispiel — Kategorie mit slug_from (N-1710-Stil):

{
  "category_id": "doc_tecnico_n1710",
  "category": {
    "name": "Technical Document N-1710",
    "metadata": [
      { "key": "language", "required": false, "order": 0 },
      { "key": "document_category", "required": true, "order": 1 },
      { "key": "installation", "required": true, "order": 2 },
      { "key": "activity_area", "required": true, "order": 3 },
      { "key": "service_class", "required": true, "order": 4 },
      { "key": "document_origin", "required": true, "order": 5 },
      {
        "key": "coded_number", "required": false, "order": 6,
        "computed_from": [
          { "key": "language", "use": "code" },
          { "key": "document_category", "use": "code" },
          { "key": "installation", "use": "label" },
          { "key": "activity_area", "use": "label" },
          { "key": "service_class", "use": "label" }
        ],
        "sequence_digits": 3
      }
    ],
    "slug_separator": "-",
    "slug_from": [
      { "key": "language", "use": "code" },
      { "key": "document_category", "use": "code" },
      { "key": "installation", "use": "label" },
      { "key": "activity_area", "use": "label" },
      { "key": "service_class", "use": "label" },
      { "key": "document_origin", "use": "label" },
      { "key": "coded_number", "use": "label" }
    ]
  }
}

In diesem Beispiel:

Nummernbasis (aus computed_from): MD-3010.95-0000-000 — bestimmt die sequentielle Eindeutigkeit
Codierte Nummer: 001 (nächste verfügbare Sequenz)
Slug (aus slug_from): MD-3010.95-0000-000-SWA-001 — enthält document_origin + Sequenz

Beispiel — einfache Kategorie ohne slug_from (abwärtskompatibel):

{
  "category_id": "exam",
  "category": {
    "name": "Medical Exam",
    "metadata": [
      { "key": "specialty", "required": true, "order": 0 },
      {
        "key": "exam_number", "order": 1,
        "computed_from": [
          { "key": "specialty", "use": "code" }
        ],
        "sequence_digits": 3
      }
    ],
    "slug_separator": "-"
  }
}

Ohne slug_from wird der Slug automatisch: {number_base}{separator}{sequence} (z.B. CARDIO-001).

sutram_delete_record_category

Löscht eine Datensatzkategorie.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`category_id`	string	Ja	ID der zu löschenden Kategorie

sutram_create_record

Erstellt einen Datensatz mit einer Kategorie, validierten Metadaten und automatisch generiertem Slug. Der Slug wird aus der slug_from-Definition der Kategorie berechnet, oder aus computed_from (Nummernbasis) + Trennzeichen + Sequenznummer. Verwenden Sie zuerst sutram_get_record_category_detail, um die erforderlichen Felder zu sehen.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`category_id`	string	Ja	Datensatzkategorie-ID
`metadata`	object	Ja	Schlüssel-Wert-Paare, die den Metadatenfeldern der Kategorie entsprechen
`parent_folder_id`	string	Nein	Übergeordneter Ordner-UUID (weglassen für Stammverzeichnis)
`name`	string	Nein	Benutzerdefinierter Name (standardmäßig der automatisch generierte Slug)

Beispiel:

{
  "category_id": "doc_tecnico_n1710",
  "metadata": {
    "language": "PT",
    "document_category": "Especificação",
    "installation": "3010.95",
    "activity_area": "0000",
    "service_class": "000",
    "document_origin": "SWA"
  }
}

Die Antwort enthält den berechneten Slug und die Sequenznummer:

{
  "record": {
    "id": "...",
    "name": "MD-3010.95-0000-000-SWA-001",
    "slug": "MD-3010.95-0000-000-SWA-001",
    "category": "doc_tecnico_n1710",
    "metadata": {
      "language": "PT",
      "document_category": "Especificação",
      "coded_number": "001",
      "slug": "MD-3010.95-0000-000-SWA-001",
      ...
    }
  }
}

sutram_update_record

Aktualisiert die Metadaten eines Datensatzes. Berechnet die Nummernbasis und den Slug neu, wenn Metadatenfelder geändert werden, die von computed_from oder slug_from referenziert werden.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`record_id`	string	Ja	Datensatz (Ordner)-UUID
`metadata`	object	Ja	Aktualisierte Schlüssel-Wert-Paare
`name`	string	Nein	Neuer Name (optional)

sutram_delete_record

Löscht einen Datensatz und alle seine Inhalte (Unterordner und Dateien) rekursiv. Diese Aktion kann nicht rückgängig gemacht werden.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`record_id`	string	Ja	Zu löschende Datensatz (Ordner)-UUID

Beispiel: Vollständiger Datensatz-Arbeitsablauf

// 1. Create metadata definitions
→ sutram_upsert_metadata { "key": "language", "definition": { "label": "Language", "type": "enum",
    "values": [{"label": "PT", "code": "PT"}, {"label": "EN", "code": "EN"}] } }
→ sutram_upsert_metadata { "key": "area", "definition": { "label": "Area", "type": "enum",
    "values": [{"label": "Automação", "code": "0100"}, {"label": "Civil", "code": "0200"}] } }
→ sutram_upsert_metadata { "key": "origin", "definition": { "label": "Origin", "type": "text" } }
→ sutram_upsert_metadata { "key": "doc_number", "definition": { "label": "Number", "type": "computed" } }

// 2. Add more values to a large enum incrementally
→ sutram_add_enum_values { "key": "area", "values": [{"label": "Elétrica", "code": "0300"}] }

// 3. Create a record category with computed_from and slug_from
→ sutram_upsert_record_category {
    "category_id": "doc_tecnico",
    "category": {
      "name": "Technical Doc",
      "metadata": [
        { "key": "language", "order": 0 },
        { "key": "area", "required": true, "order": 1 },
        { "key": "origin", "required": true, "order": 2 },
        { "key": "doc_number", "order": 3,
          "computed_from": [
            { "key": "language", "use": "code" },
            { "key": "area", "use": "code" }
          ],
          "sequence_digits": 3 }
      ],
      "slug_separator": "-",
      "slug_from": [
        { "key": "language", "use": "code" },
        { "key": "area", "use": "code" },
        { "key": "origin", "use": "label" },
        { "key": "doc_number", "use": "label" }
      ]
    }
  }

// 4. Check what fields are needed
→ sutram_get_record_category_detail { "category_id": "doc_tecnico" }

// 5. Create a record — slug is auto-generated from slug_from
→ sutram_create_record { "category_id": "doc_tecnico",
    "metadata": { "language": "PT", "area": "Automação", "origin": "SWA" } }
← { "record": { "id": "...", "name": "PT-0100-SWA-001", "slug": "PT-0100-SWA-001",
    "metadata": { "language": "PT", "area": "Automação", "origin": "SWA",
                   "doc_number": "001", "slug": "PT-0100-SWA-001" } } }

// 6. Create another record with same number base → sequence increments
→ sutram_create_record { "category_id": "doc_tecnico",
    "metadata": { "language": "PT", "area": "Automação", "origin": "PPC" } }
← { "record": { "name": "PT-0100-PPC-002", "slug": "PT-0100-PPC-002", ... } }

Beachten Sie:

Die Nummernbasis PT-0100 (aus computed_from: language + area) bestimmt die sequentielle Eindeutigkeit
Der Slug PT-0100-SWA-001 (aus slug_from) enthält origin + die Sequenznummer
Der zweite Datensatz erhält Sequenz 002, weil er die gleiche Nummernbasis PT-0100 teilt

Dokumentkommentare

KI-Assistenten können Kommentare zu Projektdateien auflisten, erstellen, beantworten, lösen und löschen. Über MCP erstellte Kommentare erscheinen in Echtzeit in der Weboberfläche und umgekehrt, dank PubSub-Broadcasting.

Positionstyp-Einschränkung: Über MCP kann KI nur file_level (Kommentar zur gesamten Datei) oder markdown (an Text in Markdown-Dateien verankert) Kommentare erstellen. Positionstypen, die GUI-Koordinaten erfordern (pdf_page, aps_3d, aps_2d, image), können über MCP gelesen, aber nicht erstellt werden.

Kommentar-Tools

Tool	Beschreibung	Berechtigung
`sutram_list_comments`	Alle übergeordneten Kommentare zu einem Inhaltselement auflisten	Jedes Mitglied
`sutram_get_comment_thread`	Einen Kommentar mit seinem vollständigen Antwortstrang abrufen	Jedes Mitglied
`sutram_create_comment`	Einen Datei-Level- oder Markdown-Kommentar erstellen	Jedes Mitglied
`sutram_reply_to_comment`	Auf einen übergeordneten Kommentar antworten	Jedes Mitglied
`sutram_resolve_comment`	Einen Kommentarstrang lösen oder wieder öffnen	Jedes Mitglied
`sutram_delete_comment`	Einen Kommentar und alle seine Antworten löschen	Autor, Besitzer oder Admin

sutram_list_comments

Listet alle übergeordneten Kommentare zu einem Inhaltselement auf. Gibt Kommentarinhalt, Autor, Positionstyp, Auflösungsstatus und Antwortanzahl zurück.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`content_item_id`	string	Ja	UUID des Inhaltselements
`include_resolved`	boolean	Nein	Ob gelöste Kommentare einbezogen werden sollen (Standard: true)

Beispiel:

{
  "content_item_id": "abc-123"
}

Antwort:

{
  "comments": [
    {
      "id": "comment-1",
      "content": "This section needs review",
      "position_type": "file_level",
      "resolved": false,
      "replies_count": 2,
      "user": { "id": "...", "name": "Alice", "email": "alice@example.com" },
      "created_at": "2026-03-10T14:30:00Z"
    }
  ],
  "total": 1
}

sutram_get_comment_thread

Ruft einen einzelnen Kommentar mit seinem vollständigen Antwortstrang, Auflösungsstatus und Autordetails ab.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`comment_id`	string	Ja	UUID des Kommentars

Antwort:

{
  "comment": {
    "id": "comment-1",
    "content": "This section needs review",
    "position_type": "file_level",
    "resolved": false,
    "resolved_at": null,
    "resolved_by": null,
    "replies_count": 1,
    "user": { "id": "...", "name": "Alice", "email": "alice@example.com" },
    "created_at": "2026-03-10T14:30:00Z",
    "replies": [
      {
        "id": "reply-1",
        "content": "I'll take care of it",
        "user": { "id": "...", "name": "Bob", "email": "bob@example.com" },
        "created_at": "2026-03-10T15:00:00Z"
      }
    ]
  }
}

sutram_create_comment

Erstellt einen Kommentar zu einem Inhaltselement. KI kann file_level (Standard) oder markdown-Kommentare erstellen.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`content_item_id`	string	Ja	UUID des Inhaltselements
`content`	string	Ja	Kommentartext
`position_type`	string	Nein	`"file_level"` (Standard) oder `"markdown"`
`text_anchor`	object	Nein	Für Markdown: `{exact_text, prefix, suffix}`
`original_text_snippet`	string	Nein	Für Markdown: der ausgewählte Textausschnitt

Beispiel — Datei-Level-Kommentar:

{
  "content_item_id": "abc-123",
  "content": "This file needs to be updated with the latest specifications."
}

Beispiel — Markdown-Kommentar an Text verankert:

{
  "content_item_id": "abc-123",
  "content": "Typo: should be 'specification' not 'specificaiton'",
  "position_type": "markdown",
  "text_anchor": {
    "exact_text": "specificaiton",
    "prefix": "the latest ",
    "suffix": " document"
  },
  "original_text_snippet": "specificaiton"
}

sutram_reply_to_comment

Antwortet auf einen bestehenden übergeordneten Kommentar. Antworten können nicht verschachtelt werden (keine Antwort-auf-Antwort).

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`comment_id`	string	Ja	UUID des übergeordneten Kommentars
`content`	string	Ja	Antworttext

Beispiel:

{
  "comment_id": "comment-1",
  "content": "Good catch, I've fixed the typo."
}

sutram_resolve_comment

Löst einen Kommentarstrang oder öffnet ihn wieder. Gelöste Kommentare zeigen an, dass das Problem behoben wurde.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`comment_id`	string	Ja	UUID des Kommentars
`action`	string	Ja	`"resolve"` oder `"reopen"`

Beispiel:

{
  "comment_id": "comment-1",
  "action": "resolve"
}

sutram_delete_comment

Löscht einen Kommentar und alle seine Antworten. Nur der Kommentarautor oder Projektbesitzer/Admin kann löschen.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`comment_id`	string	Ja	UUID des Kommentars

Beispiel: Vollständiger Kommentar-Arbeitsablauf

// 1. List comments on a file
→ sutram_list_comments { "content_item_id": "abc-123" }
← { "comments": [...], "total": 3 }

// 2. Read a specific comment thread
→ sutram_get_comment_thread { "comment_id": "comment-1" }
← { "comment": { "content": "Needs review", "replies": [...] } }

// 3. Create a new comment
→ sutram_create_comment {
    "content_item_id": "abc-123",
    "content": "Section 3.2 references an outdated standard."
  }
← { "comment": { "id": "comment-4", "content": "Section 3.2 references...", ... } }

// 4. Reply to it
→ sutram_reply_to_comment {
    "comment_id": "comment-4",
    "content": "Updated to reference ISO 9001:2025."
  }
← { "reply": { "id": "reply-1", "content": "Updated to reference...", ... } }

// 5. Resolve the comment
→ sutram_resolve_comment { "comment_id": "comment-4", "action": "resolve" }
← { "comment": { "id": "comment-4", "resolved": true, ... } }

Alle Kommentaränderungen werden in Echtzeit an Benutzer gesendet, die dasselbe Dokument in der Weboberfläche anzeigen.

Einschränkungen

Die folgenden Operationen sind über MCP noch nicht verfügbar und müssen über die Sutram-Weboberfläche durchgeführt werden. Sie werden in zukünftigen Versionen hinzugefügt:

Teilen: Freigabelinks können nicht generiert werden
Positionierte Kommentare: Das Erstellen von Kommentaren, die an PDF-Seiten, CAD-Koordinaten oder Bildpositionen verankert sind, erfordert die Web-GUI

Berechtigungen

Ihr MCP-Zugriff respektiert die gleichen Berechtigungen wie die Weboberfläche:

Rolle	Durchsuchen	Hochladen/Erstellen	Verschieben	Löschen	Versionierung	Datensatz-Schema	Datensätze	Kommentare
Besitzer	Ja	Ja	Ja	Ja	Voll (veröffentlichen, Freigabe erzwingen)	Voll (CRUD Definitionen & Kategorien)	CRUD	Voll (auflisten, erstellen, antworten, lösen, beliebige löschen)
Admin	Ja	Ja	Ja	Ja	Checkout/Check-in	Nur lesen	CRUD	Voll (auflisten, erstellen, antworten, lösen, beliebige löschen)
Mitglied	Ja	Ja	Ja	Ja	Aktivieren/deaktivieren, Checkout/Check-in	Nur lesen	CRUD	Auflisten, erstellen, antworten, lösen, eigene löschen
Viewer	Kein MCP-Zugriff	—	—	—	—	—	—	—

Viewer können den Fernzugriff nicht nutzen. Wenn Sie MCP-Zugriff benötigen, bitten Sie den Projektbesitzer, Ihre Rolle aufzustufen.

Sicherheit

Schlüssel sind unabhängig: Das Widerrufen eines Benutzerschlüssels betrifft andere Benutzer nicht. Das Widerrufen eines Projektschlüssels deaktiviert den Fernzugriff für alle in diesem Projekt.
Ein Projektschlüssel pro Projekt: Es existiert nur ein aktiver Projektschlüssel gleichzeitig. Das Neugenerieren macht den vorherigen ungültig.
Schlüssel werden nie im Klartext gespeichert: Projektschlüssel sind verschlüsselt. Benutzerschlüssel werden gehasht — sie können nach der Erstellung nicht mehr abgerufen werden.
Aktivitätsverfolgung: Jeder Schlüssel zeichnet auf, wann er zuletzt verwendet wurde.
Nur HTTPS: Alle MCP-Verbindungen verwenden verschlüsseltes HTTPS.

Zugriff widerrufen

Um Ihren persönlichen Schlüssel zu widerrufen:

Gehen Sie zu Einstellungen > API-Schlüssel
Klicken Sie auf "Schlüssel widerrufen"
Erstellen Sie bei Bedarf einen neuen

Um den Fernzugriff für ein Projekt zu deaktivieren (nur Besitzer):

Gehen Sie zu Einstellungen > Projekte
Öffnen Sie das Projekt-Dropdown
Klicken Sie auf "Fernzugriff"
Klicken Sie auf "Schlüssel widerrufen"

Fehlerbehebung

"Authentifizierung fehlgeschlagen"

Überprüfen Sie, ob beide Schlüssel korrekt sind und nicht widerrufen wurden
Stellen Sie sicher, dass Sie ein aktives Mitglied des Projekts sind
Viewer können den Fernzugriff nicht nutzen — überprüfen Sie Ihre Rolle auf der Projektseite

"Projektschlüssel nicht verfügbar"

Der Projektschlüssel wurde möglicherweise vom Besitzer widerrufen
Bitten Sie den Projektbesitzer, ihn in den Projekteinstellungen neu zu generieren

"Speicherkontingent überschritten"

Das Speicherlimit Ihres Kontos wurde erreicht
Löschen Sie ungenutzte Dateien oder stufen Sie Ihren Plan auf

Tools erscheinen nicht in Claude Code

Claude Code unterstützt type: "url" noch nicht — verwenden Sie die mcp-remote-Brückenkonfiguration (siehe Claude Code-Einrichtung)
Stellen Sie sicher, dass Node.js installiert ist (npx muss in Ihrem PATH verfügbar sein)
Überprüfen Sie, ob die .mcp.json-Datei in dem Ordner liegt, von dem aus Sie Claude Code starten

Tools erscheinen nicht in Claude Desktop

Starten Sie Claude Desktop nach der Bearbeitung der Konfigurationsdatei neu
Überprüfen Sie, ob die JSON-Syntax gültig ist (keine nachgestellten Kommas, korrekte Anführungszeichen)
Überprüfen Sie, ob die Endpunkt-URL korrekt ist
Wenn type: "url" nicht funktioniert, versuchen Sie die mcp-remote-Brückenkonfiguration (siehe Claude Desktop-Einrichtung)

Verbindungszeitüberschreitung

Überprüfen Sie Ihre Internetverbindung
Überprüfen Sie, ob der Sutram-Dienst unter https://sutram.io erreichbar ist

Unterstützte Dateitypen

Sutram erkennt MIME-Typen automatisch anhand von Dateierweiterungen. Gängige unterstützte Formate:

Kategorie	Erweiterungen
Bilder	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`
Dokumente	`.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`
Text	`.txt`, `.csv`, `.json`, `.xml`, `.md`
Medien	`.mp4`, `.mp3`, `.wav`
Archive	`.zip`
CAD	`.dwg`, `.dxf`, `.rvt`, `.ifc`

Dateien mit nicht erkannten Erweiterungen werden als application/octet-stream hochgeladen.

Unterstützte Link-Plattformen

Videoplattformen

YouTube, Vimeo, DailyMotion, Wistia, Loom und TikTok. Die Plattform wird automatisch aus der URL erkannt, und Vorschaubilder werden wenn möglich extrahiert.

Audioplattformen

Spotify, SoundCloud, Apple Podcasts, Anchor und andere. Die Plattform wird automatisch aus der URL erkannt.

Web-Links

Jede gültige HTTP/HTTPS-URL. Seitentitel, Beschreibung und Favicon werden automatisch abgerufen.

Beispiele

Medizinische Untersuchungen von Krankenhausportalen migrieren

"Lade meine Ultraschalluntersuchung vom Krankenhausportal herunter und organisiere sie in Sutram unter dem Ordner des anfordernden Arztes."

Der KI-Assistent wird:

Auf das Krankenhausportal zugreifen (über den Browser)
Den PDF-Bericht und die Bilddateien herunterladen
sutram_create_folder verwenden, um die Ordnerstruktur in einem Aufruf aufzubauen: Arztname / Untersuchungstyp / JJJJ-MM-TT
sutram_request_upload + sutram_confirm_upload verwenden, um jede Datei direkt auf S3 hochzuladen
Temporäre lokale Dateien aufräumen

Dieser Arbeitsablauf stellt sicher, dass medizinische Daten ordnungsgemäß organisiert sind und keine sensiblen Dateien auf dem lokalen Computer verbleiben.

Eine lokale Datei hochladen

"Lade die Datei report.pdf von meinem Desktop in den Ordner 'Reports' in Sutram hoch."

Claude wird die Datei lesen, sutram_get_folder verwenden, um den "Reports"-Ordner zu finden, dann sutram_request_upload aufrufen, um eine vorsignierte URL zu erhalten, die Datei direkt über HTTP PUT auf S3 hochladen und sutram_confirm_upload aufrufen, um den Vorgang abzuschließen.

Projektinhalte organisieren

"Erstelle eine Ordnerstruktur für unser Bauprojekt: Plans, Reports und Photos. Dann lade diese Baustellenfotos hoch."

Claude wird sutram_create_folder für jeden übergeordneten Ordner verwenden, dann sutram_request_upload + sutram_confirm_upload, um jedes Foto in den richtigen Ordner hochzuladen.

Alte Dateien aufräumen

"Lösche alle Dateien im Ordner 'Temp'."

Claude wird sutram_get_folder verwenden, um den Ordnerinhalt aufzulisten, dann sutram_delete für jede Datei.

Ordnerstruktur reorganisieren

"Verschiebe alle Inhalte aus dem Ordner '2024' nach '2024-Archive', um die Hauptansicht aufzuräumen."

Claude wird sutram_move_contents verwenden, um alle Unterordner und Dateien in einer einzigen Operation vom Quell- zum Zielordner zu übertragen. Wenn Elemente Namenskonflikte haben, werden sie automatisch mit numerischen Suffixen umbenannt.

Eine bestimmte Datei verschieben

"Verschiebe die Datei 'contract.pdf' in den Ordner 'Legal'."

Claude wird sutram_get_folder verwenden, um die Datei und den Zielordner zu finden, dann sutram_move_item, um die Datei zu verschieben. Wenn eine Datei mit dem gleichen Namen bereits im Zielordner existiert, wird sie automatisch umbenannt (z.B. contract (1).pdf).

Einen Web-Link speichern

"Speichere diesen Artikel in meinem Projekt: https://example.com/building-codes-2026"

Claude wird sutram_create_web_link mit der URL verwenden. Sutram ruft automatisch den Seitentitel und das Favicon ab, sodass der Link mit seinem korrekten Namen im Projekt erscheint.

Video-Referenzen organisieren

"Füge diese YouTube-Videos zum Ordner 'Training' hinzu: [video1 URL], [video2 URL]."

Claude wird sutram_get_folder verwenden, um den "Training"-Ordner zu finden, dann sutram_create_video_link für jede URL aufrufen. Sutram erkennt, dass es YouTube-Videos sind und extrahiert automatisch Vorschaubilder.

Eine Datei herunterladen

"Gib mir den Download-Link für die Datei 'site-plan.pdf'."

Claude wird sutram_get_folder verwenden, um die Datei zu finden, dann sutram_get_item, um eine vorsignierte Download-URL abzurufen. Die URL ist temporär und kann zum direkten Herunterladen der Datei verwendet werden.

Ordner taggen und suchen

"Organisiere meine medizinischen Untersuchungen nach Patient und Untersuchungstyp, dann finde alle Ordner für Patient João."

Claude wird:

sutram_create_folder mit path und tags verwenden, um strukturierte Ordner mit Metadaten zu erstellen
sutram_set_folder_tags verwenden, um Tags auf bestehenden Ordnern hinzuzufügen oder zu aktualisieren
sutram_search_folders mit tag_name: "patient" und tag_value: "João" verwenden, um alle passenden Ordner zu finden (Teilstringabgleich — findet auch "João Pedro", "João Silva")

Tags ermöglichen KI-Assistenten, reichhaltige, durchsuchbare Organisationsstrukturen zu erstellen, ohne sich ausschließlich auf Ordnernamen zu verlassen.

Tags entdecken und UND-Suchen durchführen

"Finde alle USG-Untersuchungen für Patient João innerhalb des Dr. Mion-Ordners."

Claude wird:

sutram_get_tag_keys mit der Ordner-ID verwenden, um verfügbare Tag-Schlüssel in diesem Bereich zu ermitteln

sutram_search_folders mit mehreren UND-Bedingungen verwenden:

{
  "conditions": [
    { "key": "patient", "value": "João" },
    { "key": "exam_type", "value": "USG" }
  ],
  "folder_id": "dr-mion-folder-id"
}

Nur Ordner zurückgeben, die beide Bedingungen innerhalb der angegebenen Hierarchie erfüllen

Dateien über Skript hochladen

Beim Hochladen von Dateien über einen KI-Assistenten verwendet der Assistent den zweistufigen vorsignierten URL-Ablauf: sutram_request_upload, um eine vorsignierte S3-PUT-URL zu erhalten, dann die Datei direkt auf S3 hochladen und schließlich sutram_confirm_upload aufrufen, um den Dateidatensatz zu erstellen. Dieser Ansatz vermeidet den Base64-Kodierungsaufwand und hat keine praktische Dateigrößenbeschränkung über das Speicherkontingent Ihres Plans hinaus.

Für Automatisierung oder Batch-Uploads außerhalb des KI-Assistenten-Kontexts können Sie den MCP-Endpunkt direkt über HTTP aufrufen.

Wie der MCP-HTTP-Endpunkt funktioniert

Der Sutram MCP-Server verwendet den Streamable HTTP-Transport (JSON-RPC 2.0 über HTTPS):

Sitzung initialisieren — POST https://app.sutram.io/mcp mit Methode initialize
Sitzungs-ID erfassen — aus dem mcp-session-id-Antwortheader
Benachrichtigung senden — notifications/initialized (vom MCP-Protokoll gefordert)
Tools aufrufen — POST mit Methode tools/call, Tool-Name und Argumente übergeben

Alle Anfragen müssen die Authentifizierungs-Header (x-project-key und x-user-key) und nach der Initialisierung den mcp-session-id-Header enthalten.

Beispiel: Node.js-Upload-Skript

import { readFileSync, statSync } from "node:fs";
import { basename, extname } from "node:path";
import { lookup } from "mime-types";

const ENDPOINT = "https://app.sutram.io/mcp";
const HEADERS = {
  "x-project-key": "sk_proj_YOUR_PROJECT_KEY",
  "x-user-key": "sk_user_YOUR_USER_KEY",
};

let sessionId = null;
let requestId = 0;

async function mcpRequest(method, params = {}) {
  const headers = {
    "Content-Type": "application/json",
    Accept: "application/json, text/event-stream",
    ...HEADERS,
  };
  if (sessionId) headers["mcp-session-id"] = sessionId;

  const response = await fetch(ENDPOINT, {
    method: "POST",
    headers,
    body: JSON.stringify({ jsonrpc: "2.0", method, params, id: ++requestId }),
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);

  const sid = response.headers.get("mcp-session-id");
  if (sid) sessionId = sid;

  const contentType = response.headers.get("content-type") || "";
  if (contentType.includes("text/event-stream")) {
    // Parse SSE: find the last "data:" line with a JSON-RPC response
    const text = await response.text();
    const events = text.split("\n\n").filter(Boolean);
    for (const event of events.reverse()) {
      const dataLine = event.split("\n").find((l) => l.startsWith("data: "));
      if (dataLine) return JSON.parse(dataLine.slice(6));
    }
  }
  return response.json();
}

async function mcpNotify(method, params = {}) {
  const headers = { "Content-Type": "application/json", ...HEADERS };
  if (sessionId) headers["mcp-session-id"] = sessionId;
  await fetch(ENDPOINT, {
    method: "POST",
    headers,
    body: JSON.stringify({ jsonrpc: "2.0", method, params }),
  });
}

// ── Usage ──

async function main() {
  // 1. Initialize MCP session
  await mcpRequest("initialize", {
    protocolVersion: "2024-11-05",
    capabilities: {},
    clientInfo: { name: "my-upload-script", version: "1.0.0" },
  });
  await mcpNotify("notifications/initialized");

  // 2. Request a presigned upload URL
  const filePath = process.argv[2];
  const folderId = process.argv[3] || null;
  const filename = basename(filePath);
  const fileSize = statSync(filePath).size;
  const contentType = lookup(extname(filePath)) || "application/octet-stream";

  const reqResult = await mcpRequest("tools/call", {
    name: "sutram_request_upload",
    arguments: { filename, file_size: fileSize, content_type: contentType, folder_id: folderId },
  });

  const { upload_url, s3_key, file_id } = JSON.parse(reqResult.result.content[0].text);

  // 3. Upload file directly to S3
  const fileContent = readFileSync(filePath);
  const putResponse = await fetch(upload_url, {
    method: "PUT",
    headers: { "Content-Type": contentType },
    body: fileContent,
  });

  if (!putResponse.ok) throw new Error(`S3 upload failed: ${putResponse.status}`);

  // 4. Confirm the upload
  const confirmResult = await mcpRequest("tools/call", {
    name: "sutram_confirm_upload",
    arguments: { file_id, s3_key, filename, content_type: contentType, file_size: fileSize, folder_id: folderId },
  });

  console.log(JSON.stringify(confirmResult, null, 2));
}

main();

Speichern Sie als upload.mjs und führen Sie aus:

node upload.mjs /path/to/report.pdf "target-folder-uuid"

Claude Code-Skill-Integration

Wenn Sie Claude Code verwenden, können Sie dieses Skript als Skill einbinden, sodass der Assistent es automatisch aufrufen kann, wenn er Dateien hochladen muss. Platzieren Sie das Skript in .claude/skills/sutram-upload/scripts/upload.mjs und erstellen Sie eine SKILL.md, die Claude anweist, wie es aufzurufen ist. So delegiert der Assistent bei einer hochzuladenden Datei die umfangreiche I/O an das externe Skript, während die Orchestrierung in der Konversation bleibt.

Kernpunkte

Keine Dateigrößenbeschränkung über das Speicherkontingent Ihres Sutram-Plans hinaus
Dateien werden direkt über vorsignierte URL auf S3 hochgeladen — keine Base64-Kodierung, keine Daten über den Webserver
Das Skript handhabt den vollständigen MCP-Handshake (initialize → notify → tool call)
Die Antwort kann je nach Verarbeitungszeit als JSON oder Server-Sent Events (SSE) kommen — das Skript behandelt beides
Anmeldedaten können aus .mcp.json gelesen werden, um Hardcoding zu vermeiden

REST API

Zusätzlich zu MCP-Tools bietet Sutram eine REST API für den schreibgeschützten Zugriff auf Projektinhalte. Sie verwendet die gleiche Dual-Key-Authentifizierung und ist ideal für externe Apps, Dashboards und Skripte.

Basis-URL: https://sutram.io/api/v1

Endpunkte:

Endpunkt	Beschreibung
`GET /api/v1/project`	Projektinformationen
`GET /api/v1/folders`	Stammordner auflisten
`GET /api/v1/folders/:id`	Ordnerdetails mit Unterordnern und Elementen
`GET /api/v1/content`	Inhaltselemente mit Filterung, Tag-Suche und Paginierung auflisten
`GET /api/v1/content/:id`	Inhaltselement-Details mit vorsignierten Download-URLs

Vollständige Dokumentation: REST API v1 Referenz