Guida al Sutram MCP Server

Versione: 0.111.0 Data: 2026-03-14 Stato: In sviluppo

Panoramica

L'Accesso Remoto di Sutram consente agli assistenti IA e agli strumenti di automazione di connettersi ai propri progetti attraverso il Model Context Protocol (MCP). Una volta configurato, l'assistente IA può navigare le cartelle, caricare file, aggiungere link web/video/audio, gestire contenuti e interagire con i commenti dei documenti nei progetti Sutram — il tutto con autenticazione e permessi appropriati.

Come funziona

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)

Sono necessarie due chiavi API per ogni connessione:

Chiave	Scopo	Chi la crea	Dove trovarla
Chiave Progetto (`sk_proj_...`)	Identifica il progetto	Il proprietario del progetto	Pagina del progetto o impostazioni del progetto
Chiave Utente (`sk_user_...`)	Identifica l'utente	Ogni utente crea la propria	Impostazioni Utente > Chiave API

Entrambe le chiavi devono essere valide e l'utente deve essere un membro attivo del progetto (non un viewer) per connettersi.

Per Iniziare

Passo 1: Creare la propria Chiave API personale

Andare su Impostazioni (icona ingranaggio nel menu in alto a destra)
Fare clic sulla scheda Chiave API
Fare clic su Crea Chiave
Copiare la chiave immediatamente — verrà mostrata solo una volta

La chiave personale ha questo aspetto: sk_user_zQD0BjH56nQhOgX3uxni...

Importante: Conservare la chiave in modo sicuro. In caso di smarrimento, è possibile revocare quella vecchia e crearne una nuova dalla stessa pagina delle impostazioni.

Passo 2: Ottenere la chiave del progetto

Il proprietario del progetto deve prima abilitare l'accesso remoto per il progetto:

Andare su Impostazioni > scheda Progetti
Aprire il menu a discesa (tre puntini) accanto al progetto
Fare clic su Abilita Accesso Remoto
Copiare la chiave del progetto che appare

Una volta abilitato l'accesso remoto, qualsiasi membro del progetto (proprietario, admin o membro) può copiare la chiave del progetto:

Aprire il progetto
Fare clic sull'icona del segnale verde accanto al badge del ruolo nell'intestazione
Una finestra modale mostrerà la chiave del progetto — fare clic sul pulsante copia

La chiave del progetto ha questo aspetto: sk_proj_ej8NWMisd2rJgMwAJ22T...

Configurazione del Client IA

Ogni progetto Sutram dovrebbe avere la propria configurazione MCP locale. Poiché la chiave del progetto è legata a un progetto specifico, l'approccio consigliato è creare una cartella workspace dedicata per ogni integrazione e posizionare il file .mcp.json al suo interno.

Esempio: Se si usa Sutram per archiviare esami medici, creare una cartella locale per quel flusso di lavoro:

~/projects/medical-exams/
└── .mcp.json          ← Chiavi Sutram per il progetto salute

Questo mantiene le credenziali limitate al contesto corretto e evita di mescolare progetti non correlati.

Claude Code (CLI) — Consigliato

Creare un file .mcp.json nella cartella workspace:

{
  "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"
      ]
    }
  }
}

Nota: Claude Code non supporta ancora type: "url" nativamente. La configurazione sopra utilizza mcp-remote come ponte per connettersi tramite stdio. Questo richiede che Node.js (npx) sia installato. Il pacchetto mcp-remote viene scaricato automaticamente al primo utilizzo.

Quindi avviare Claude Code da quella cartella. Gli strumenti Sutram saranno disponibili solo in quel contesto.

Cursor

Creare un file .cursor/mcp.json nella cartella workspace:

{
  "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 utilizza un file di configurazione globale. Aggiungere una voce per ogni progetto Sutram, usando un nome descrittivo per distinguerli:

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

Se la versione di Claude Desktop supporta type: "url":

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

Se type: "url" non è riconosciuto, utilizzare invece il ponte mcp-remote:

{
  "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"
      ]
    }
  }
}

Riavviare Claude Desktop dopo aver salvato il file.

Suggerimento: La chiave utente (sk_user_...) è la stessa in tutte le voci — identifica l'utente. La chiave del progetto (sk_proj_...) cambia per ogni progetto.

Altri Client MCP

Sutram utilizza il trasporto MCP Streamable HTTP. Qualsiasi client compatibile con MCP che supporta il trasporto HTTP può connettersi utilizzando:

Endpoint: https://app.sutram.io/mcp
Metodo: POST (JSON-RPC 2.0)
Autenticazione: Intestazioni personalizzate x-project-key e x-user-key
Versione del protocollo: 2024-11-05

Per i client che supportano solo il trasporto stdio, utilizzare mcp-remote come ponte:

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"

Strumenti Disponibili

Una volta connesso, l'assistente IA ha accesso a questi strumenti. È possibile recuperare questo elenco anche programmaticamente inviando la richiesta MCP standard tools/list all'endpoint del server.

Riferimento Rapido (A–Z)

#	Strumento	Categoria	Descrizione
1	`sutram_add_enum_values`	Schema	Aggiunge nuovi valori a una definizione di metadati enum esistente
2	`sutram_cancel_checkout`	Versionamento	Annulla il checkout senza caricare modifiche
3	`sutram_checkin_file`	Versionamento	Rilascia un file dal checkout (check-in)
4	`sutram_checkout_file`	Versionamento	Effettua il checkout di un file per la modifica esclusiva
5	`sutram_confirm_upload`	Contenuti	Passo 2 del caricamento: conferma che il file è stato caricato su S3
6	`sutram_bulk_create_file_links`	File Link	Crea in blocco file link da una cartella sorgente a una cartella destinazione
7	`sutram_cancel_checkout`	Versionamento	Annulla il checkout senza caricare modifiche
8	`sutram_checkin_file`	Versionamento	Rilascia un file dal checkout (check-in)
9	`sutram_checkout_file`	Versionamento	Effettua il checkout di un file per la modifica esclusiva
10	`sutram_confirm_upload`	Contenuti	Passo 2 del caricamento: conferma che il file è stato caricato su S3
11	`sutram_create_audio_link`	Contenuti	Crea un link audio (Spotify, SoundCloud, ecc.)
12	`sutram_create_comment`	Commenti	Crea un commento a livello di file o markdown su un elemento di contenuto
13	`sutram_create_file_link`	File Link	Crea un file link (riferimento simbolico) a un file esistente
14	`sutram_create_folder`	Cartelle	Crea una nuova cartella o percorso annidato
15	`sutram_create_new_version`	Versionamento	Crea una nuova versione da un file pubblicato
16	`sutram_create_record`	Record	Crea un nuovo record in una categoria
17	`sutram_create_video_link`	Contenuti	Crea un link video (YouTube, Vimeo, ecc.)
18	`sutram_create_web_link`	Contenuti	Crea un link web con titolo recuperato automaticamente
19	`sutram_delete`	Contenuti	Elimina un elemento di contenuto o una cartella
20	`sutram_delete_comment`	Commenti	Elimina un commento e tutte le sue risposte
21	`sutram_delete_metadata`	Schema	Elimina una definizione di metadati
22	`sutram_delete_record`	Record	Elimina un record
23	`sutram_delete_record_category`	Schema	Elimina una categoria di record
24	`sutram_disable_versioning`	Versionamento	Converte il file in riferimento (sola lettura)
25	`sutram_enable_versioning`	Versionamento	Converte il file da riferimento a modificabile
26	`sutram_force_release_lock`	Versionamento	Forza il rilascio del checkout di un altro utente (solo proprietario)
27	`sutram_get_comment_thread`	Commenti	Ottiene un commento con il thread completo delle risposte
28	`sutram_get_folder`	Cartelle	Restituisce i contenuti di una cartella
29	`sutram_get_item`	Contenuti	Ottiene i dettagli completi e l'URL di download di un elemento di contenuto
30	`sutram_get_item_tag_keys`	Tag	Restituisce tutte le chiavi tag distinte usate sugli elementi di contenuto
31	`sutram_get_metadata_definitions`	Schema	Restituisce tutte le definizioni dei campi metadati
32	`sutram_get_record_categories`	Schema	Restituisce tutte le categorie di record
33	`sutram_get_record_category_detail`	Schema	Restituisce una categoria con metadati completamente risolti
34	`sutram_get_tag_keys`	Tag	Restituisce tutte le chiavi tag distinte usate sulle cartelle
35	`sutram_list_comments`	Commenti	Elenca tutti i commenti di primo livello su un elemento di contenuto
36	`sutram_list_file_links_for_source`	File Link	Elenca tutti i file link che puntano a un file sorgente
37	`sutram_list_file_links_in_folder`	File Link	Elenca i file link in una cartella con dettagli del file sorgente
38	`sutram_list_versions`	Versionamento	Elenca tutte le versioni di un file
39	`sutram_move_contents`	Cartelle	Sposta tutti i contenuti da una cartella a un'altra
40	`sutram_move_item`	Contenuti	Sposta un singolo elemento di contenuto in un'altra cartella
41	`sutram_project_info`	Progetto	Restituisce nome, descrizione e impostazioni del progetto
42	`sutram_publish_version`	Versionamento	Pubblica un file bozza, creando uno snapshot della versione
43	`sutram_remove_enum_values`	Schema	Rimuove valori da una definizione di metadati enum
44	`sutram_rename`	Contenuti	Rinomina un elemento di contenuto o una cartella
45	`sutram_reply_to_comment`	Commenti	Risponde a un commento di primo livello esistente
46	`sutram_request_upload`	Contenuti	Passo 1 del caricamento: restituisce un URL PUT S3 pre-firmato
47	`sutram_resolve_comment`	Commenti	Risolve o riapre un thread di commento
48	`sutram_search_folders`	Tag	Cerca cartelle per tag (singolo o condizioni AND)
49	`sutram_search_items`	Tag	Cerca elementi di contenuto per tag
50	`sutram_set_folder_tags`	Tag	Imposta tag chiave-valore su una cartella
51	`sutram_set_item_tags`	Tag	Imposta tag chiave-valore su un elemento di contenuto
52	`sutram_undo_checkin`	Versionamento	Annulla l'ultimo check-in, ripristinando la versione precedente
53	`sutram_update_record`	Record	Aggiorna i metadati di un record
54	`sutram_upload_modified_file`	Versionamento	Sostituisce il contenuto del file durante il checkout
55	`sutram_upsert_metadata`	Schema	Crea o aggiorna una definizione di campo metadati
56	`sutram_upsert_record_category`	Schema	Crea o aggiorna una categoria di record

Categorie: Progetto (1) · Cartelle (3) · Contenuti (8) · File Link (4) · Tag (6) · Versionamento (12) · Commenti (6) · Schema (8) · Record (4)

Le sezioni seguenti descrivono ogni strumento in dettaglio, organizzati per funzionalità.

sutram_project_info

Restituisce informazioni sul progetto corrente.

Parametri: Nessuno

Esempio di risposta:

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

sutram_get_folder

Naviga i contenuti di una cartella (sottocartelle, file e link). Omettere folder_id per elencare i contenuti della radice.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`folder_id`	string	No	UUID della cartella. Omettere per la radice.

Esempio di risposta:

{
  "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

Crea una nuova cartella. Supporta la creazione di gerarchie annidate in una singola chiamata.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`name`	string	Sì*	Nome della cartella (per creare una singola cartella)
`path`	string	Sì*	Percorso separato da barra per creazione annidata (es. `"A/B/C"`)
`parent_folder_id`	string	No	UUID della cartella genitore. Omettere per il livello radice.
`tags`	object	No	Tag chiave-valore di forma libera (es. `{"patient": "John", "exam_type": "USG"}`). Quando si usa `path`, i tag vengono applicati solo alla cartella foglia (la più profonda).

*Usare name (cartella singola) o path (gerarchia annidata), non entrambi.

Creazione annidata: Quando si usa path, le cartelle intermedie vengono create automaticamente. Se una cartella nel percorso esiste già, viene riutilizzata — l'operazione è idempotente.

Esempio — cartella singola:

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

Esempio — gerarchia annidata con tag:

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

Questo crea tre cartelle in una singola chiamata e restituisce quella più profonda (2024-12-12) con i tag specificati.

sutram_request_upload

Passo 1 del flusso di caricamento diretto. Valida il file e restituisce un URL PUT S3 pre-firmato. Il file viene caricato direttamente su S3 dal client — nessun dato passa attraverso i server web di Sutram.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`filename`	string	Sì	Nome del file con estensione (es. `report.pdf`)
`file_size`	integer	Sì	Dimensione del file in byte
`content_type`	string	No	Tipo MIME. Rilevato automaticamente dall'estensione se omesso.
`folder_id`	string	No	UUID della cartella destinazione. Omettere per la radice.

Esempio di risposta:

{
  "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

Passo 2 del flusso di caricamento diretto. Chiamare questo dopo che il file è stato caricato all'URL pre-firmato. Verifica che l'oggetto S3 esista, crea il record del file, aggiorna l'utilizzo dello storage e accoda la compressione se applicabile.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`file_id`	string	Sì	UUID del file da `sutram_request_upload`
`s3_key`	string	Sì	Chiave S3 da `sutram_request_upload`
`filename`	string	Sì	Nome del file originale con estensione
`content_type`	string	Sì	Tipo MIME del file
`file_size`	integer	Sì	Dimensione del file in byte
`folder_id`	string	No	UUID della cartella destinazione (deve corrispondere alla richiesta)

Esempio di risposta:

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

Esempio completo del flusso di caricamento:

# 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

Crea un link web nel progetto. Sutram recupera automaticamente il titolo della pagina e la favicon dall'URL.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`url`	string	Sì	URL della pagina web (deve essere http o https)
`name`	string	No	Nome visualizzato. Recuperato automaticamente dal titolo della pagina se omesso.
`folder_id`	string	No	UUID della cartella destinazione. Omettere per la radice.

Esempio di risposta:

{
  "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

Crea un link video nel progetto. Supporta YouTube, Vimeo, DailyMotion, Wistia, Loom e TikTok. Rileva automaticamente la piattaforma e estrae l'ID del video dall'URL.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`url`	string	Sì	URL del video (es. `https://www.youtube.com/watch?v=...`)
`name`	string	No	Nome visualizzato. Per impostazione predefinita usa l'URL se omesso.
`folder_id`	string	No	UUID della cartella destinazione. Omettere per la radice.

Esempio di risposta:

{
  "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

Crea un link audio nel progetto. Supporta Spotify, SoundCloud, Apple Podcasts e altri. Rileva automaticamente la piattaforma e estrae l'ID audio dall'URL.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`url`	string	Sì	URL del contenuto audio (es. `https://open.spotify.com/track/...`)
`name`	string	No	Nome visualizzato. Per impostazione predefinita usa l'URL se omesso.
`folder_id`	string	No	UUID della cartella destinazione. Omettere per la radice.

Esempio di risposta:

{
  "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

Crea un file link (riferimento simbolico) a un file esistente nel progetto. Il link appare come un riferimento in sola lettura senza duplicare lo storage o il versionamento. La sorgente deve essere un file (non un link o un altro file link). Se il file sorgente viene eliminato, tutti i suoi file link vengono automaticamente rimossi.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`source_content_item_id`	string	Sì	UUID dell'elemento di contenuto file sorgente a cui collegare
`name`	string	No	Nome visualizzato (predefinito: nome del file sorgente)
`folder_id`	string	No	UUID della cartella destinazione (omettere per la radice)
`description`	string	No	Descrizione del file link

Esempio di richiesta:

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

Esempio di risposta:

{
  "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

Crea in blocco file link per tutti i file (o un sottoinsieme filtrato) in una cartella sorgente, posizionandoli in una cartella destinazione. Salta automaticamente i file che hanno già un link nella cartella destinazione (deduplicazione). Ideale per flussi di lavoro come collegare più file di esami a una cartella di referti centralizzata.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`source_folder_id`	string	Sì	UUID della cartella sorgente contenente i file da collegare
`target_folder_id`	string	Sì	UUID della cartella destinazione dove verranno creati i file link
`name_pattern`	string	No	Filtro per sottostringa (case-insensitive) sui nomi dei file sorgente. Solo i file corrispondenti vengono collegati.
`recursive`	boolean	No	Include file dalle sottocartelle della cartella sorgente (predefinito: false)

Esempio di richiesta:

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

Esempio di risposta:

{
  "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-..."
    }
  ]
}

Suggerimento: Eseguendo lo stesso comando di nuovo, tutti i file già collegati vengono saltati ("created": 0, "skipped": 7), rendendo sicura la riesecuzione.

sutram_list_file_links_for_source

Elenca tutti i file link che puntano a un dato file sorgente. Risponde alla domanda: "dove viene referenziato questo file?" Restituisce ogni link con il suo percorso cartella.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`source_content_item_id`	string	Sì	UUID dell'elemento di contenuto file sorgente

Esempio di richiesta:

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

Esempio di risposta:

{
  "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

Elenca tutti i file link in una cartella, arricchiti con i dettagli del file sorgente (nome, tipo di contenuto, dimensione file, percorso cartella). A differenza di sutram_get_folder, questo fornisce informazioni complete sul file sorgente a cui punta ogni link.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`folder_id`	string	No	UUID della cartella (omettere per la radice)

Esempio di richiesta:

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

Esempio di risposta:

{
  "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

Ottiene i dettagli completi di un elemento di contenuto tramite ID. Per i file, restituisce metadati e un URL di download pre-firmato. Per i link (web, video, audio, file_link), restituisce l'URL, le informazioni sulla piattaforma e i metadati.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`content_item_id`	string	Sì	UUID dell'elemento di contenuto

Esempio di risposta (file):

{
  "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-..."
}

Esempio di risposta (link web):

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

Esempio di risposta (link video):

{
  "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

Elimina un elemento di contenuto (file, link web, link video, link audio) o una cartella dal progetto.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`item_id`	string	Sì	UUID dell'elemento di contenuto o della cartella
`item_type`	string	Sì	`"content_item"` o `"folder"`. Usare `"content_item"` per qualsiasi tipo di contenuto (file, link web, link video, link audio).

sutram_rename

Rinomina un elemento di contenuto (file, link web, link video, link audio) o una cartella.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`item_id`	string	Sì	UUID dell'elemento di contenuto o della cartella
`item_type`	string	Sì	`"content_item"` o `"folder"`. Usare `"content_item"` per qualsiasi tipo di contenuto (file, link web, link video, link audio).
`new_name`	string	Sì	Nuovo nome (per i file, includere l'estensione)

sutram_move_contents

Sposta tutti i contenuti (sottocartelle e file) da una cartella sorgente a una cartella destinazione. La cartella sorgente viene svuotata ma non eliminata. I conflitti di nome vengono gestiti automaticamente.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`source_folder_id`	string	Sì	UUID della cartella sorgente da svuotare
`target_folder_id`	string	Sì	UUID della cartella destinazione che riceve i contenuti

Gestione dei conflitti di nome: Se una sottocartella o un file con lo stesso nome esiste già nella cartella destinazione, Sutram rinomina automaticamente l'elemento spostato aggiungendo un suffisso numerico: Exams diventa Exams (1), report.pdf diventa report (1).pdf, e così via.

Regole di validazione:

Sorgente e destinazione devono essere cartelle diverse
La destinazione non può essere una sottocartella della sorgente (previene spostamenti circolari)
Entrambe le cartelle devono esistere nel progetto corrente

Esempio di risposta:

{
  "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

Sposta un singolo elemento di contenuto (file o link) in un'altra cartella. I conflitti di nome vengono gestiti automaticamente.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`content_item_id`	string	Sì	UUID dell'elemento di contenuto da spostare
`target_folder_id`	string/null	No	UUID della cartella destinazione (null per la radice)

Gestione dei conflitti di nome: Se un file con lo stesso nome esiste già nella cartella destinazione, Sutram rinomina automaticamente il file spostato aggiungendo un suffisso numerico: report.pdf diventa report (1).pdf, e così via.

Esempio di risposta (senza conflitto):

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

Esempio di risposta (con rinomina):

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

sutram_set_folder_tags

Imposta tag chiave-valore di forma libera su una cartella. Sostituisce tutti i tag esistenti. Inviare {} per cancellare tutti i tag.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`folder_id`	string	Sì	UUID della cartella
`tags`	object	Sì	Tag chiave-valore da impostare. Inviare `{}` per cancellare tutti i tag.

Limiti: Massimo 50 tag per cartella. Chiave max 100 caratteri, valore max 500 caratteri.

Semantica: Questa è un'operazione PUT — sostituisce tutti i tag esistenti. Per aggiungere un tag senza rimuovere gli altri, prima leggere i tag correnti (tramite sutram_get_folder), unire le modifiche, quindi chiamare sutram_set_folder_tags con il set completo.

Esempio — impostare tag:

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

Esempio — cancellare tutti i tag:

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

Esempio di risposta:

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

sutram_search_folders

Cerca cartelle per tag. Supporta condizioni singole o multiple AND. Tutta la corrispondenza è case-insensitive sia per le chiavi che per i valori. I valori supportano la corrispondenza per sottostringa (es. "orto" corrisponde a "Ortopedia"). Usare folder_id per limitare la ricerca ai discendenti di una cartella specifica.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`tag_name`	string	No*	Chiave tag da cercare (modalità condizione singola). Case-insensitive.
`tag_value`	string	No	Valore da abbinare (modalità condizione singola). Corrispondenza per sottostringa, case-insensitive.
`conditions`	array	No*	Condizioni AND multiple. Ogni oggetto ha `key` (obbligatorio) e `value` (opzionale).
`folder_id`	string	No	UUID della cartella per limitare la ricerca. Cerca solo tra i discendenti di questa cartella.

*Usare tag_name (condizione singola) o conditions (condizioni AND multiple).

Comportamento della ricerca:

Corrispondenza chiave: Corrispondenza esatta case-insensitive ("Patient" corrisponde a "patient")
Corrispondenza valore: Corrispondenza per sottostringa case-insensitive ("orto" corrisponde a "Ortopedia", "joão" corrisponde a "João Silva")
Senza valore: Quando il valore è omesso, corrisponde a qualsiasi cartella che abbia la chiave indipendentemente dal valore
Condizioni multiple: Tutte le condizioni devono corrispondere (logica AND)

Esempio — trovare tutte le cartelle con tag "patient":

{ "tag_name": "patient" }

Esempio — trovare cartelle per un paziente specifico (corrispondenza per sottostringa):

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

Questo corrisponde alle cartelle dove il tag "patient" contiene "joão" (es. "João Silva", "João Pedro").

Esempio — ricerca AND con condizioni multiple:

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

Questo restituisce solo le cartelle che corrispondono a entrambe le condizioni.

Esempio — cercare solo all'interno di una gerarchia di cartelle specifica:

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

Esempio di risposta:

{
  "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

Restituisce tutte le chiavi tag distinte usate nelle cartelle del progetto. Utile per scoprire quali tag sono disponibili prima di effettuare una ricerca. Usare folder_id per limitare ai discendenti di una cartella specifica.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`folder_id`	string	No	UUID della cartella per limitare. Restituisce solo le chiavi dai discendenti di questa cartella.

Esempio — ottenere tutte le chiavi tag nel progetto:

{}

Esempio — ottenere le chiavi tag all'interno di una gerarchia di cartelle:

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

Esempio di risposta:

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

sutram_set_item_tags

Imposta tag chiave-valore di forma libera su un elemento di contenuto. Sostituisce tutti i tag esistenti. Inviare {} per cancellare tutti i tag.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`content_item_id`	string	Sì	UUID dell'elemento di contenuto
`tags`	object	Sì	Tag chiave-valore da impostare. Inviare `{}` per cancellare tutti i tag.

Limiti: Massimo 50 tag per elemento. Chiave max 100 caratteri, valore max 500 caratteri.

Semantica: Questa è un'operazione PUT — sostituisce tutti i tag esistenti. Per aggiungere un tag senza rimuovere gli altri, prima leggere i tag correnti (tramite sutram_get_item), unire le modifiche, quindi chiamare sutram_set_item_tags con il set completo.

Esempio — impostare tag:

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

Esempio — cancellare tutti i tag:

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

Esempio di risposta:

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

sutram_search_items

Cerca elementi di contenuto per tag. Supporta condizioni singole o multiple AND. Tutta la corrispondenza è case-insensitive sia per le chiavi che per i valori. I valori supportano la corrispondenza per sottostringa (es. "neuro" corrisponde a "Neurologia"). Usare folder_id per limitare la ricerca a una cartella specifica, e type per filtrare per tipo di contenuto.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`tag_name`	string	No*	Chiave tag da cercare (modalità condizione singola). Case-insensitive.
`tag_value`	string	No	Valore da abbinare (modalità condizione singola). Corrispondenza per sottostringa, case-insensitive.
`conditions`	array	No*	Condizioni AND multiple. Ogni oggetto ha `key` (obbligatorio) e `value` (opzionale).
`folder_id`	string	No	UUID della cartella per limitare la ricerca.
`type`	string	No	Filtro per tipo di contenuto: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

*Usare tag_name (condizione singola) o conditions (condizioni AND multiple).

Esempio — trovare tutti gli elementi con tag "topic":

{ "tag_name": "topic" }

Esempio — trovare elementi per un argomento specifico (corrispondenza per sottostringa):

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

Esempio — ricerca AND con condizioni multiple:

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

Esempio — cercare solo link video in una cartella specifica:

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

Esempio di risposta:

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

sutram_get_item_tag_keys

Restituisce tutte le chiavi tag distinte usate negli elementi di contenuto del progetto. Utile per scoprire quali tag sono disponibili prima di effettuare una ricerca. Usare folder_id per limitare a una cartella specifica, e type per filtrare per tipo di contenuto.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`folder_id`	string	No	UUID della cartella per limitare.
`type`	string	No	Filtro per tipo di contenuto: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

Esempio — ottenere tutte le chiavi tag dei contenuti nel progetto:

{}

Esempio — ottenere le chiavi tag solo per i link video:

{ "type": "video_link" }

Esempio di risposta:

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

Versionamento dei File

Sutram supporta un flusso di lavoro completo di versionamento per i file tramite MCP. Questo permette agli assistenti IA di abilitare il controllo di versione, effettuare il checkout dei file per la modifica esclusiva, caricare modifiche e pubblicare versioni.

Flusso di Lavoro

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)

Strumenti di Versionamento

Strumento	Descrizione	Permesso
`sutram_enable_versioning`	Converte il file da riferimento a modificabile (avvia il versionamento)	Owner, Member
`sutram_disable_versioning`	Converte il file nuovamente in riferimento (ferma il versionamento)	Owner, Member
`sutram_checkout_file`	Effettua il checkout del file per la modifica esclusiva	Owner, Admin, Member
`sutram_checkin_file`	Rilascia il blocco di checkout	Utente del checkout
`sutram_cancel_checkout`	Annulla il checkout senza modifiche	Utente del checkout
`sutram_force_release_lock`	Forza il rilascio del checkout di un altro utente	Solo Owner
`sutram_publish_version`	Pubblica un file bozza, creando uno snapshot della versione	Solo Owner
`sutram_create_new_version`	Avvia una nuova versione da un file pubblicato	Solo Owner
`sutram_undo_checkin`	Annulla l'ultimo check-in, ripristina la versione precedente	Ultimo utente del checkin
`sutram_list_versions`	Elenca tutte le versioni pubblicate con URL di download	Qualsiasi membro
`sutram_upload_modified_file`	Sostituisce il contenuto del file durante il checkout	Utente del checkout

Parametri

Tutti gli strumenti di versionamento richiedono content_item_id (UUID dell'elemento di contenuto).

sutram_upload_modified_file richiede inoltre:

Parametro	Tipo	Descrizione
`s3_key`	string	Chiave S3 da `sutram_request_upload`
`file_name`	string	Nome del file con estensione
`file_size`	integer	Dimensione del file in byte
`content_type`	string	Tipo MIME

Esempio: Flusso Completo di Versionamento

// 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 }

Categorie di Record e Record

Sutram supporta record strutturati con schemi di metadati e slug generati automaticamente. Questo permette agli assistenti IA di definire campi metadati, creare categorie di record e gestire record programmaticamente.

Requisito del piano: Gli strumenti di gestione record e schema richiedono un piano con la funzionalità Record abilitata (Plus o superiore). Gli strumenti in sola lettura (sutram_get_metadata_definitions, sutram_get_record_categories, sutram_get_record_category_detail) sono disponibili su tutti i piani.

Concetti

Definizioni di metadati — Schemi di campo che definiscono i tipi, le etichette e i valori consentiti per i campi metadati (es. "language" come enum con valori "PT", "EN", "ES").
Categorie di record — Template che definiscono quali campi metadati usa un record, il loro ordine, come viene calcolata la base numerica (computed_from) e come viene composto lo slug (nome del record) (slug_from).
Record — Cartelle create con una categoria, metadati validati e uno slug generato automaticamente.

Generazione dello Slug

I record hanno uno slug generato automaticamente (usato come nome del record). Lo slug viene costruito in due passaggi:

Base numerica — Determinata dalle voci computed_from su un tag di metadati calcolato. Questo definisce quali valori di campo formano la chiave di unicità per la numerazione sequenziale.
Composizione dello slug — Determinata dalle voci slug_from sulla categoria. Questo definisce quali valori di campo (incluso il tag calcolato) compongono lo slug finale.

Senza slug_from (retrocompatibile): slug = number_base + separator + sequence_number (es. 0100-200-001).

Con slug_from: lo slug è composto dai campi referenziati in ordine (es. MD-3010.95-0000-000-SWA-001).

Strumenti di Schema

Strumento	Descrizione	Permesso
`sutram_get_metadata_definitions`	Elenca tutte le definizioni di metadati	Qualsiasi membro
`sutram_get_record_categories`	Elenca tutte le categorie di record	Qualsiasi membro
`sutram_get_record_category_detail`	Categoria con metadati risolti (etichette, tipi, valori consentiti)	Qualsiasi membro
`sutram_upsert_metadata`	Crea o aggiorna una definizione di metadati	Solo Owner
`sutram_delete_metadata`	Elimina una definizione di metadati (fallisce se in uso)	Solo Owner
`sutram_add_enum_values`	Aggiunge valori a una definizione enum (unione, deduplicazione, ordinamento)	Solo Owner
`sutram_remove_enum_values`	Rimuove valori da una definizione enum per codice	Solo Owner
`sutram_upsert_record_category`	Crea o aggiorna una categoria di record	Solo Owner
`sutram_delete_record_category`	Elimina una categoria di record	Solo Owner

Strumenti CRUD per i Record

Strumento	Descrizione	Permesso
`sutram_create_record`	Crea un record con categoria, metadati e slug generato automaticamente	Owner, Admin, Member
`sutram_update_record`	Aggiorna i metadati del record (ricalcola lo slug se necessario)	Owner, Admin, Member
`sutram_delete_record`	Elimina un record e tutti i suoi contenuti ricorsivamente	Owner, Admin, Member

sutram_get_metadata_definitions

Restituisce tutte le definizioni di metadati per il progetto. Ogni definizione ha una chiave e proprietà: label, type (text, enum, boolean, date, computed) e opzionalmente values, depends_on, values_map.

Parametri: Nessuno

sutram_get_record_categories

Restituisce tutte le categorie di record per il progetto. Ogni categoria definisce quali campi metadati usa un record, la configurazione dello slug e l'ordinamento.

Parametri: Nessuno

sutram_get_record_category_detail

Restituisce una categoria di record con metadati completamente risolti (etichette, tipi, valori consentiti dalle definizioni). Usare questo per capire quali campi sono necessari prima di creare un record.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`category_id`	string	Sì	ID della categoria di record

sutram_upsert_metadata

Crea o aggiorna una definizione di metadati (schema di campo). Per i tipi enum, fornire l'array values completo. Per enum grandi, preferire sutram_add_enum_values per aggiunte incrementali.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`key`	string	Sì	Chiave unica (snake_case, es. `"specialty"`)
`definition`	object	Sì	Definizione con `label`, `type` e campi opzionali

Tipi supportati: text, enum, boolean, date, computed.

Esempio — creare un enum semplice:

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

sutram_delete_metadata

Elimina una definizione di metadati. Fallisce se la definizione è attualmente in uso da una categoria di record.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`key`	string	Sì	Chiave della definizione da eliminare

sutram_add_enum_values

Aggiunge valori a una definizione di metadati enum esistente. I nuovi valori vengono uniti con quelli esistenti — i duplicati (per codice) vengono saltati. I valori vengono ordinati per codice dopo l'unione. Usare questo invece di sutram_upsert_metadata quando si lavora con enum grandi per evitare di inviare l'intero array di valori.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`key`	string	Sì	Chiave della definizione enum
`values`	array	Sì	Array di oggetti `{label, code}` da aggiungere

Esempio — aggiungere valori a un enum esistente con oltre 800 elementi:

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

Esempio di risposta:

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

sutram_remove_enum_values

Rimuove valori da una definizione di metadati enum esistente tramite i loro codici.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`key`	string	Sì	Chiave della definizione enum
`codes`	array	Sì	Array di stringhe di codice da rimuovere

Esempio:

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

Esempio di risposta:

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

sutram_upsert_record_category

Crea o aggiorna una categoria di record. I metadati devono referenziare definizioni esistenti. Usare computed_from su una voce di metadati per definire la base numerica (unicità). Usare slug_from a livello di categoria per definire come viene composto lo slug (nome del record).

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`category_id`	string	Sì	ID unico della categoria (snake_case)
`category`	object	Sì	Definizione della categoria (vedere campi sotto)

Campi della categoria:

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome visualizzato per la categoria
`metadata`	array	Sì	Array di riferimenti ai campi metadati (vedere sotto)
`slug_separator`	string	No	Separatore tra le parti dello slug (predefinito: `"-"`)
`slug_from`	array	No	Definisce la composizione dello slug. Ogni voce ha `key` e `use` (`"code"` o `"label"`). Se omesso, slug = number_base + separator + sequence_number

Campi della voce metadati:

Campo	Tipo	Obbligatorio	Descrizione
`key`	string	Sì	Chiave di una definizione di metadati esistente
`required`	boolean	No	Se questo campo è obbligatorio (predefinito: false)
`order`	integer	No	Ordine di visualizzazione (base 0)
`computed_from`	array	No	Solo per tag calcolati. Definisce la base numerica. Ogni voce ha `key` e `use` (`"code"` o `"label"`)
`sequence_digits`	integer	No	Solo per tag calcolati. Cifre per il numero sequenziale (2-4, predefinito: 2)

Esempio — categoria con slug_from (stile N-1710):

{
  "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 questo esempio:

Base numerica (da computed_from): MD-3010.95-0000-000 — determina l'unicità sequenziale
Numero codificato: 001 (prossima sequenza disponibile)
Slug (da slug_from): MD-3010.95-0000-000-SWA-001 — include document_origin + sequenza

Esempio — categoria semplice senza slug_from (retrocompatibile):

{
  "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": "-"
  }
}

Senza slug_from, lo slug è automaticamente: {number_base}{separator}{sequence} (es. CARDIO-001).

sutram_delete_record_category

Elimina una categoria di record.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`category_id`	string	Sì	ID della categoria da eliminare

sutram_create_record

Crea un record con una categoria, metadati validati e slug generato automaticamente. Lo slug viene calcolato dalla definizione slug_from della categoria, o da computed_from (base numerica) + separatore + numero sequenziale. Usare prima sutram_get_record_category_detail per vedere i campi obbligatori.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`category_id`	string	Sì	ID della categoria di record
`metadata`	object	Sì	Coppie chiave-valore corrispondenti ai campi metadati della categoria
`parent_folder_id`	string	No	UUID della cartella genitore (omettere per la radice)
`name`	string	No	Nome personalizzato (predefinito: slug generato automaticamente)

Esempio:

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

La risposta include lo slug calcolato e il numero sequenziale:

{
  "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

Aggiorna i metadati di un record. Ricalcola la base numerica e lo slug quando i campi metadati referenziati da computed_from o slug_from cambiano.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`record_id`	string	Sì	UUID del record (cartella)
`metadata`	object	Sì	Coppie chiave-valore aggiornate
`name`	string	No	Nuovo nome (opzionale)

sutram_delete_record

Elimina un record e tutti i suoi contenuti (sottocartelle e file) ricorsivamente. Questa azione non può essere annullata.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`record_id`	string	Sì	UUID del record (cartella) da eliminare

Esempio: Flusso Completo dei Record

// 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", ... } }

Si noti come:

La base numerica PT-0100 (da computed_from: language + area) determina l'unicità sequenziale
Lo slug PT-0100-SWA-001 (da slug_from) include origin + il numero sequenziale
Il secondo record ottiene la sequenza 002 perché condivide la stessa base numerica PT-0100

Commenti sui Documenti

Gli assistenti IA possono elencare, creare, rispondere, risolvere ed eliminare commenti sui file del progetto. I commenti creati tramite MCP appaiono in tempo reale nell'interfaccia web e viceversa, grazie alla trasmissione PubSub.

Restrizione sul tipo di posizione: Tramite MCP, l'IA può creare solo commenti file_level (commento sull'intero file) o markdown (ancorato al testo nei file markdown). I tipi di posizione che richiedono coordinate GUI (pdf_page, aps_3d, aps_2d, image) possono essere letti ma non creati tramite MCP.

Strumenti per i Commenti

Strumento	Descrizione	Permesso
`sutram_list_comments`	Elenca tutti i commenti di primo livello su un elemento di contenuto	Qualsiasi membro
`sutram_get_comment_thread`	Ottiene un commento con il thread completo delle risposte	Qualsiasi membro
`sutram_create_comment`	Crea un commento a livello di file o markdown	Qualsiasi membro
`sutram_reply_to_comment`	Risponde a un commento di primo livello	Qualsiasi membro
`sutram_resolve_comment`	Risolve o riapre un thread di commento	Qualsiasi membro
`sutram_delete_comment`	Elimina un commento e tutte le sue risposte	Autore, Owner o Admin

sutram_list_comments

Elenca tutti i commenti di primo livello su un elemento di contenuto. Restituisce il contenuto del commento, l'autore, il tipo di posizione, lo stato di risoluzione e il conteggio delle risposte.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`content_item_id`	string	Sì	UUID dell'elemento di contenuto
`include_resolved`	boolean	No	Se includere i commenti risolti (predefinito: true)

Esempio:

{
  "content_item_id": "abc-123"
}

Risposta:

{
  "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

Ottiene un singolo commento con il thread completo delle risposte, lo stato di risoluzione e i dettagli dell'autore.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`comment_id`	string	Sì	UUID del commento

Risposta:

{
  "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

Crea un commento su un elemento di contenuto. L'IA può creare commenti file_level (predefinito) o markdown.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`content_item_id`	string	Sì	UUID dell'elemento di contenuto
`content`	string	Sì	Testo del commento
`position_type`	string	No	`"file_level"` (predefinito) o `"markdown"`
`text_anchor`	object	No	Per markdown: `{exact_text, prefix, suffix}`
`original_text_snippet`	string	No	Per markdown: il frammento di testo selezionato

Esempio — commento a livello di file:

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

Esempio — commento markdown ancorato al testo:

{
  "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

Risponde a un commento di primo livello esistente. Le risposte non possono essere annidate (nessuna risposta a una risposta).

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`comment_id`	string	Sì	UUID del commento di primo livello
`content`	string	Sì	Testo della risposta

Esempio:

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

sutram_resolve_comment

Risolve o riapre un thread di commento. I commenti risolti indicano che la questione è stata affrontata.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`comment_id`	string	Sì	UUID del commento
`action`	string	Sì	`"resolve"` o `"reopen"`

Esempio:

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

sutram_delete_comment

Elimina un commento e tutte le sue risposte. Solo l'autore del commento o il proprietario/admin del progetto può eliminare.

Parametri:

Parametro	Tipo	Obbligatorio	Descrizione
`comment_id`	string	Sì	UUID del commento

Esempio: Flusso Completo dei Commenti

// 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, ... } }

Tutte le modifiche ai commenti vengono trasmesse in tempo reale agli utenti che visualizzano lo stesso documento nell'interfaccia web.

Limitazioni

Le seguenti operazioni non sono ancora disponibili tramite MCP e devono essere effettuate attraverso l'interfaccia web di Sutram. Saranno aggiunte nelle versioni future:

Condivisione: I link di condivisione non possono essere generati
Commenti posizionati: La creazione di commenti ancorati a pagine PDF, coordinate CAD o posizioni su immagini richiede la GUI web

Permessi

L'accesso MCP rispetta gli stessi permessi dell'interfaccia web:

Ruolo	Navigazione	Caricamento/Creazione	Spostamento	Eliminazione	Versionamento	Schema Record	Record	Commenti
Owner	Sì	Sì	Sì	Sì	Completo (pubblicazione, rilascio forzato)	Completo (CRUD definizioni e categorie)	CRUD	Completo (elenco, creazione, risposta, risoluzione, eliminazione di qualsiasi)
Admin	Sì	Sì	Sì	Sì	Checkout/checkin	Solo lettura	CRUD	Completo (elenco, creazione, risposta, risoluzione, eliminazione di qualsiasi)
Member	Sì	Sì	Sì	Sì	Abilita/disabilita, checkout/checkin	Solo lettura	CRUD	Elenco, creazione, risposta, risoluzione, eliminazione dei propri
Viewer	Nessun accesso MCP	—	—	—	—	—	—	—

I Viewer non possono utilizzare l'accesso remoto. Se è necessario l'accesso MCP, chiedere al proprietario del progetto di aggiornare il proprio ruolo.

Sicurezza

Le chiavi sono indipendenti: Revocare una chiave utente non influisce sugli altri utenti. Revocare una chiave progetto disabilita l'accesso remoto per tutti gli utenti di quel progetto.
Una chiave progetto per progetto: Esiste una sola chiave progetto attiva alla volta. Rigenerarla invalida quella precedente.
Le chiavi non sono mai memorizzate in testo chiaro: Le chiavi progetto sono crittografate. Le chiavi utente sono hashate — non possono essere recuperate dopo la creazione.
Tracciamento delle attività: Ogni chiave registra quando è stata utilizzata l'ultima volta.
Solo HTTPS: Tutte le connessioni MCP utilizzano HTTPS crittografato.

Revoca dell'accesso

Per revocare la propria chiave personale:

Andare su Impostazioni > Chiave API
Fare clic su "Revoca Chiave"
Crearne una nuova se necessario

Per disabilitare l'accesso remoto per un progetto (solo proprietario):

Andare su Impostazioni > Progetti
Aprire il menu a discesa del progetto
Fare clic su "Accesso Remoto"
Fare clic su "Revoca Chiave"

Risoluzione dei Problemi

"Autenticazione fallita"

Verificare che entrambe le chiavi siano corrette e non siano state revocate
Assicurarsi di essere un membro attivo del progetto
I Viewer non possono utilizzare l'accesso remoto — controllare il proprio ruolo nella pagina del progetto

"Chiave progetto non disponibile"

La chiave del progetto potrebbe essere stata revocata dal proprietario
Chiedere al proprietario del progetto di rigenerarla dalle impostazioni del progetto

"Quota di storage superata"

Il limite di storage dell'account è stato raggiunto
Eliminare file non utilizzati o aggiornare il piano

Gli strumenti non appaiono in Claude Code

Claude Code non supporta ancora type: "url" — utilizzare la configurazione del ponte mcp-remote (vedere Configurazione Claude Code)
Assicurarsi che Node.js sia installato (npx deve essere disponibile nel PATH)
Verificare che il file .mcp.json sia nella cartella da cui si avvia Claude Code

Gli strumenti non appaiono in Claude Desktop

Riavviare Claude Desktop dopo aver modificato il file di configurazione
Verificare che la sintassi JSON sia valida (nessuna virgola finale, virgolette corrette)
Verificare che l'URL dell'endpoint sia corretto
Se type: "url" non funziona, provare la configurazione del ponte mcp-remote (vedere Configurazione Claude Desktop)

Timeout della connessione

Controllare la connessione internet
Verificare che il servizio Sutram sia accessibile su https://sutram.io

Tipi di File Supportati

Sutram rileva automaticamente i tipi MIME dalle estensioni dei file. Formati comuni supportati:

Categoria	Estensioni
Immagini	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`
Documenti	`.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`
Testo	`.txt`, `.csv`, `.json`, `.xml`, `.md`
Media	`.mp4`, `.mp3`, `.wav`
Archivi	`.zip`
CAD	`.dwg`, `.dxf`, `.rvt`, `.ifc`

I file con estensioni non riconosciute vengono caricati come application/octet-stream.

Piattaforme Link Supportate

Piattaforme video

YouTube, Vimeo, DailyMotion, Wistia, Loom e TikTok. La piattaforma viene rilevata automaticamente dall'URL e le miniature vengono estratte quando disponibili.

Piattaforme audio

Spotify, SoundCloud, Apple Podcasts, Anchor e altre. La piattaforma viene rilevata automaticamente dall'URL.

Link web

Qualsiasi URL HTTP/HTTPS valido. Titolo della pagina, descrizione e favicon vengono recuperati automaticamente.

Esempi

Migrare esami medici dai portali ospedalieri

"Scarica il mio esame ecografico dal portale ospedaliero e organizzalo in Sutram nella cartella del medico richiedente."

L'assistente IA:

Accede al portale ospedaliero (tramite browser)
Scarica il referto PDF e i file immagine
Usa sutram_create_folder per costruire la struttura delle cartelle in una singola chiamata: Nome Medico / Tipo Esame / AAAA-MM-GG
Usa sutram_request_upload + sutram_confirm_upload per caricare ogni file direttamente su S3
Pulisce i file temporanei locali

Questo flusso di lavoro garantisce che i dati medici siano correttamente organizzati e che nessun file sensibile rimanga sul computer locale.

Caricare un file locale

"Carica il file report.pdf dal mio desktop nella cartella 'Reports' in Sutram."

Claude leggerà il file, userà sutram_get_folder per trovare la cartella "Reports", poi sutram_request_upload per ottenere un URL pre-firmato, caricherà il file direttamente su S3 tramite HTTP PUT, e chiamerà sutram_confirm_upload per finalizzare.

Organizzare il contenuto del progetto

"Crea una struttura di cartelle per il nostro progetto edilizio: Planimetrie, Referti e Foto. Poi carica queste foto del cantiere."

Claude userà sutram_create_folder per ogni cartella di primo livello, poi sutram_request_upload + sutram_confirm_upload per caricare ogni foto nella cartella giusta.

Pulire vecchi file

"Elimina tutti i file nella cartella 'Temp'."

Claude userà sutram_get_folder per elencare il contenuto della cartella, poi sutram_delete per ogni file.

Riorganizzare la struttura delle cartelle

"Sposta tutti i contenuti dalla cartella '2024' in '2024-Archivio' per liberare spazio nella vista principale."

Claude userà sutram_move_contents per trasferire tutte le sottocartelle e i file dalla sorgente alla cartella destinazione in una singola operazione. Se alcuni elementi hanno nomi in conflitto, vengono automaticamente rinominati con suffissi numerici.

Spostare un file specifico

"Sposta il file 'contract.pdf' nella cartella 'Legale'."

Claude userà sutram_get_folder per trovare il file e la cartella destinazione, poi sutram_move_item per spostare il file. Se un file con lo stesso nome esiste già nella cartella destinazione, verrà automaticamente rinominato (es. contract (1).pdf).

Salvare un link web

"Salva questo articolo nel mio progetto: https://example.com/building-codes-2026"

Claude userà sutram_create_web_link con l'URL. Sutram recupera automaticamente il titolo della pagina e la favicon, così il link appare con il suo nome corretto nel progetto.

Organizzare riferimenti video

"Aggiungi questi video YouTube alla cartella 'Formazione': [URL video1], [URL video2]."

Claude userà sutram_get_folder per trovare la cartella "Formazione", poi chiamerà sutram_create_video_link per ogni URL. Sutram rileva che sono video YouTube ed estrae le miniature automaticamente.

Scaricare un file

"Dammi il link di download per il file 'site-plan.pdf'."

Claude userà sutram_get_folder per trovare il file, poi sutram_get_item per recuperare un URL di download pre-firmato. L'URL è temporaneo e può essere usato per scaricare il file direttamente.

Taggare e cercare cartelle

"Organizza i miei esami medici per paziente e tipo di esame, poi trova tutte le cartelle per il paziente Giovanni."

Claude:

Userà sutram_create_folder con path e tags per creare cartelle strutturate con metadati
Userà sutram_set_folder_tags per aggiungere o aggiornare tag sulle cartelle esistenti
Userà sutram_search_folders con tag_name: "patient" e tag_value: "Giovanni" per trovare tutte le cartelle corrispondenti (corrispondenza per sottostringa — trova anche "Giovanni Pietro", "Giovanni Rossi")

I tag consentono agli assistenti IA di creare strutture organizzative ricche e ricercabili senza affidarsi solo ai nomi delle cartelle.

Scoprire tag ed effettuare ricerche AND

"Trova tutti gli esami USG per il paziente Giovanni all'interno della cartella del Dr. Mion."

Claude:

Userà sutram_get_tag_keys con l'ID della cartella per scoprire le chiavi tag disponibili in quell'ambito

Userà sutram_search_folders con condizioni AND multiple:

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

Restituirà solo le cartelle che corrispondono a entrambe le condizioni all'interno della gerarchia specificata

Caricamento File tramite Script

Quando si caricano file attraverso un assistente IA, l'assistente utilizza il flusso a due passaggi con URL pre-firmato: sutram_request_upload per ottenere un URL PUT S3 pre-firmato, poi carica il file direttamente su S3, e infine chiama sutram_confirm_upload per creare il record del file. Questo approccio evita l'overhead della codifica base64 e non ha limiti pratici sulla dimensione del file oltre la quota di storage del piano.

Per l'automazione o i caricamenti batch al di fuori del contesto dell'assistente IA, è possibile chiamare l'endpoint MCP direttamente tramite HTTP.

Come funziona l'endpoint HTTP MCP

Il server MCP di Sutram utilizza il trasporto Streamable HTTP (JSON-RPC 2.0 su HTTPS):

Inizializzare una sessione — POST https://app.sutram.io/mcp con metodo initialize
Catturare l'ID di sessione — dall'intestazione della risposta mcp-session-id
Inviare una notifica — notifications/initialized (richiesto dal protocollo MCP)
Chiamare gli strumenti — POST con metodo tools/call, passando il nome dello strumento e gli argomenti

Tutte le richieste devono includere le intestazioni di autenticazione (x-project-key e x-user-key) e, dopo l'inizializzazione, l'intestazione mcp-session-id.

Esempio: Script di caricamento Node.js

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();

Salvare come upload.mjs ed eseguire:

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

Integrazione skill di Claude Code

Se si utilizza Claude Code, è possibile incapsulare questo script come una skill in modo che l'assistente possa invocarlo automaticamente quando deve caricare file. Posizionare lo script in .claude/skills/sutram-upload/scripts/upload.mjs e creare un SKILL.md che istruisca Claude su come chiamarlo. In questo modo, quando l'assistente incontra un file da caricare, delega l'I/O pesante allo script esterno mantenendo l'orchestrazione nella conversazione.

Punti chiave

Nessun limite di dimensione file oltre la quota di storage del piano Sutram
I file vengono caricati direttamente su S3 tramite URL pre-firmato — nessuna codifica base64, nessun dato attraverso il server web
Lo script gestisce l'intero handshake MCP (initialize → notify → tool call)
La risposta può arrivare come JSON o Server-Sent Events (SSE) a seconda del tempo di elaborazione — lo script gestisce entrambi
Le credenziali possono essere lette da .mcp.json per evitare di codificarle nel codice

REST API

Oltre agli strumenti MCP, Sutram fornisce una REST API per il consumo in sola lettura dei contenuti del progetto. Utilizza la stessa autenticazione a doppia chiave ed è ideale per app esterne, dashboard e script.

URL Base: https://sutram.io/api/v1

Endpoint:

Endpoint	Descrizione
`GET /api/v1/project`	Informazioni sul progetto
`GET /api/v1/folders`	Elenco cartelle di primo livello
`GET /api/v1/folders/:id`	Dettaglio cartella con sottocartelle e elementi
`GET /api/v1/content`	Elenco elementi di contenuto con filtri, ricerca per tag e paginazione
`GET /api/v1/content/:id`	Dettaglio elemento di contenuto con URL di download pre-firmati

Documentazione completa: Riferimento REST API v1