Guide du Sutram MCP Server

Version : 0.111.0 Date : 2026-03-14 Statut : En developpement

Apercu general

L'acces a distance Sutram permet aux assistants IA et aux outils d'automatisation de se connecter a vos projets via le Model Context Protocol (MCP). Une fois configure, votre assistant IA peut parcourir les dossiers, telecharger des fichiers, ajouter des liens web/video/audio, gerer le contenu et interagir avec les commentaires de documents dans vos projets Sutram — le tout avec une authentification et des permissions appropriees.

Fonctionnement

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)

Deux cles API sont requises pour chaque connexion :

Cle	Objectif	Qui la cree	Ou la trouver
Cle de projet (`sk_proj_...`)	Identifie le projet	Proprietaire du projet	Page du projet ou parametres du projet
Cle utilisateur (`sk_user_...`)	Vous identifie	Chaque utilisateur cree la sienne	Parametres utilisateur > Cle API

Les deux cles doivent etre valides, et vous devez etre un membre actif du projet (pas un viewer) pour vous connecter.

Premiers pas

Etape 1 : Creer votre cle API personnelle

Allez dans Parametres (icone d'engrenage dans le menu en haut a droite)
Cliquez sur la carte Cle API
Cliquez sur Creer une cle
Copiez la cle immediatement — elle ne sera affichee qu'une seule fois

Votre cle personnelle ressemble a : sk_user_zQD0BjH56nQhOgX3uxni...

Important : Stockez votre cle en securite. Si vous la perdez, vous pouvez revoquer l'ancienne et creer une nouvelle cle depuis la meme page de parametres.

Etape 2 : Obtenir la cle du projet

Le proprietaire du projet doit d'abord activer l'acces a distance pour le projet :

Allez dans Parametres > onglet Projets
Ouvrez le menu deroulant (trois points) a cote du projet
Cliquez sur Activer l'acces a distance
Copiez la cle de projet qui apparait

Une fois l'acces a distance active, tout membre du projet (proprietaire, administrateur ou membre) peut copier la cle du projet :

Ouvrez le projet
Cliquez sur l'icone de signal verte a cote du badge de role dans l'en-tete
Une fenetre modale affichera la cle du projet — cliquez sur le bouton de copie

La cle de projet ressemble a : sk_proj_ej8NWMisd2rJgMwAJ22T...

Configurer votre client IA

Chaque projet Sutram devrait avoir sa propre configuration MCP locale. Comme la cle de projet est liee a un projet specifique, l'approche recommandee est de creer un dossier de travail dedie pour chaque integration et d'y placer le fichier .mcp.json.

Exemple : Si vous utilisez Sutram pour stocker des examens medicaux, creez un dossier local pour ce flux de travail :

~/projects/medical-exams/
└── .mcp.json          ← Cles Sutram pour votre projet de sante

Cela garde les identifiants limites au bon contexte et evite de melanger des projets sans rapport.

Claude Code (CLI) — Recommande

Creez un fichier .mcp.json dans votre dossier de travail :

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

Remarque : Claude Code ne prend pas encore en charge type: "url" nativement. La configuration ci-dessus utilise mcp-remote comme pont pour se connecter via stdio. Cela necessite que Node.js (npx) soit installe. Le package mcp-remote est telecharge automatiquement lors de la premiere utilisation.

Ensuite, lancez Claude Code depuis ce dossier. Les outils Sutram seront disponibles uniquement dans ce contexte.

Cursor

Creez un fichier .cursor/mcp.json dans votre dossier de travail :

{
  "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 utilise un fichier de configuration global. Ajoutez une entree pour chaque projet Sutram, en utilisant un nom descriptif pour les distinguer :

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

Si votre version de Claude Desktop prend en charge 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"
      }
    }
  }
}

Si type: "url" n'est pas reconnu, utilisez le pont mcp-remote a la place :

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

Redemarrez Claude Desktop apres avoir enregistre le fichier.

Astuce : La cle utilisateur (sk_user_...) est la meme pour toutes les entrees — elle vous identifie. La cle de projet (sk_proj_...) change par projet.

Autres clients MCP

Sutram utilise le transport MCP Streamable HTTP. Tout client compatible MCP prenant en charge le transport HTTP peut se connecter en utilisant :

Point de terminaison : https://app.sutram.io/mcp
Methode : POST (JSON-RPC 2.0)
Authentification : En-tetes personnalises x-project-key et x-user-key
Version du protocole : 2024-11-05

Pour les clients ne prenant en charge que le transport stdio, utilisez mcp-remote comme pont :

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"

Outils disponibles

Une fois connecte, votre assistant IA a acces a ces outils. Vous pouvez egalement recuperer cette liste de maniere programmatique en envoyant la requete MCP standard tools/list au point de terminaison du serveur.

Reference rapide (A–Z)

#	Outil	Categorie	Description
1	`sutram_add_enum_values`	Schema	Ajoute de nouvelles valeurs a une definition de metadonnee de type enum existante
2	`sutram_cancel_checkout`	Versionnage	Annule le check-out sans telecharger de modifications
3	`sutram_checkin_file`	Versionnage	Libere un fichier du check-out (check-in)
4	`sutram_checkout_file`	Versionnage	Effectue le check-out d'un fichier pour edition exclusive
5	`sutram_confirm_upload`	Contenu	Etape 2 du telechargement : confirme que le fichier a ete telecharge sur S3
6	`sutram_bulk_create_file_links`	Liens de fichier	Cree en masse des liens de fichier d'un dossier source vers un dossier cible
7	`sutram_cancel_checkout`	Versionnage	Annule le check-out sans telecharger de modifications
8	`sutram_checkin_file`	Versionnage	Libere un fichier du check-out (check-in)
9	`sutram_checkout_file`	Versionnage	Effectue le check-out d'un fichier pour edition exclusive
10	`sutram_confirm_upload`	Contenu	Etape 2 du telechargement : confirme que le fichier a ete telecharge sur S3
11	`sutram_create_audio_link`	Contenu	Cree un lien audio (Spotify, SoundCloud, etc.)
12	`sutram_create_comment`	Commentaires	Cree un commentaire au niveau du fichier ou un commentaire markdown sur un element de contenu
13	`sutram_create_file_link`	Liens de fichier	Cree un lien de fichier (reference symbolique) vers un fichier existant
14	`sutram_create_folder`	Dossiers	Cree un nouveau dossier ou un chemin imbrique
15	`sutram_create_new_version`	Versionnage	Cree une nouvelle version a partir d'un fichier publie
16	`sutram_create_record`	Enregistrements	Cree un nouvel enregistrement dans une categorie
17	`sutram_create_video_link`	Contenu	Cree un lien video (YouTube, Vimeo, etc.)
18	`sutram_create_web_link`	Contenu	Cree un lien web avec titre recupere automatiquement
19	`sutram_delete`	Contenu	Supprime un element de contenu ou un dossier
20	`sutram_delete_comment`	Commentaires	Supprime un commentaire et toutes ses reponses
21	`sutram_delete_metadata`	Schema	Supprime une definition de metadonnee
22	`sutram_delete_record`	Enregistrements	Supprime un enregistrement
23	`sutram_delete_record_category`	Schema	Supprime une categorie d'enregistrement
24	`sutram_disable_versioning`	Versionnage	Reconvertit le fichier en reference (lecture seule)
25	`sutram_enable_versioning`	Versionnage	Convertit le fichier de reference en editable
26	`sutram_force_release_lock`	Versionnage	Force la liberation du check-out d'un autre utilisateur (proprietaire uniquement)
27	`sutram_get_comment_thread`	Commentaires	Obtient un commentaire avec son fil complet de reponses
28	`sutram_get_folder`	Dossiers	Renvoie le contenu d'un dossier
29	`sutram_get_item`	Contenu	Obtient les details complets et l'URL de telechargement d'un element de contenu
30	`sutram_get_item_tag_keys`	Tags	Renvoie toutes les cles de tag distinctes utilisees sur les elements de contenu
31	`sutram_get_metadata_definitions`	Schema	Renvoie toutes les definitions de champs de metadonnees
32	`sutram_get_record_categories`	Schema	Renvoie toutes les categories d'enregistrement
33	`sutram_get_record_category_detail`	Schema	Renvoie une categorie avec les metadonnees entierement resolues
34	`sutram_get_tag_keys`	Tags	Renvoie toutes les cles de tag distinctes utilisees sur les dossiers
35	`sutram_list_comments`	Commentaires	Liste tous les commentaires de niveau superieur sur un element de contenu
36	`sutram_list_file_links_for_source`	Liens de fichier	Liste tous les liens de fichier pointant vers un fichier source
37	`sutram_list_file_links_in_folder`	Liens de fichier	Liste les liens de fichier dans un dossier avec les details du fichier source
38	`sutram_list_versions`	Versionnage	Liste toutes les versions d'un fichier
39	`sutram_move_contents`	Dossiers	Deplace tout le contenu d'un dossier vers un autre
40	`sutram_move_item`	Contenu	Deplace un seul element de contenu vers un autre dossier
41	`sutram_project_info`	Projet	Renvoie le nom du projet, la description et les parametres
42	`sutram_publish_version`	Versionnage	Publie un fichier brouillon, creant un instantane de version
43	`sutram_remove_enum_values`	Schema	Supprime des valeurs d'une definition de metadonnee de type enum
44	`sutram_rename`	Contenu	Renomme un element de contenu ou un dossier
45	`sutram_reply_to_comment`	Commentaires	Repond a un commentaire de niveau superieur existant
46	`sutram_request_upload`	Contenu	Etape 1 du telechargement : renvoie une URL PUT S3 pre-signee
47	`sutram_resolve_comment`	Commentaires	Resout ou rouvre un fil de commentaire
48	`sutram_search_folders`	Tags	Recherche des dossiers par tag (condition unique ou conditions AND)
49	`sutram_search_items`	Tags	Recherche des elements de contenu par tag
50	`sutram_set_folder_tags`	Tags	Definit des tags cle-valeur sur un dossier
51	`sutram_set_item_tags`	Tags	Definit des tags cle-valeur sur un element de contenu
52	`sutram_undo_checkin`	Versionnage	Annule le dernier check-in, restaurant la version precedente
53	`sutram_update_record`	Enregistrements	Met a jour les metadonnees d'un enregistrement
54	`sutram_upload_modified_file`	Versionnage	Remplace le contenu du fichier pendant le check-out
55	`sutram_upsert_metadata`	Schema	Cree ou met a jour une definition de champ de metadonnee
56	`sutram_upsert_record_category`	Schema	Cree ou met a jour une categorie d'enregistrement

Categories : Projet (1) - Dossiers (3) - Contenu (8) - Liens de fichier (4) - Tags (6) - Versionnage (12) - Commentaires (6) - Schema (8) - Enregistrements (4)

Les sections ci-dessous decrivent chaque outil en detail, organises par fonctionnalite.

sutram_project_info

Renvoie les informations sur le projet en cours.

Parametres : Aucun

Exemple de reponse :

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

sutram_get_folder

Parcourt le contenu d'un dossier (sous-dossiers, fichiers et liens). Omettez folder_id pour lister le contenu racine.

Parametres :

Parametre	Type	Requis	Description
`folder_id`	string	Non	UUID du dossier. Omettre pour la racine.

Exemple de reponse :

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

Cree un nouveau dossier. Prend en charge la creation de hierarchies imbriquees en un seul appel.

Parametres :

Parametre	Type	Requis	Description
`name`	string	Oui*	Nom du dossier (pour creer un seul dossier)
`path`	string	Oui*	Chemin separe par des barres obliques pour la creation imbriquee (par ex., `"A/B/C"`)
`parent_folder_id`	string	Non	UUID du dossier parent. Omettre pour le niveau racine.
`tags`	object	Non	Tags cle-valeur libres (par ex., `{"patient": "John", "exam_type": "USG"}`). Lors de l'utilisation de `path`, les tags sont appliques uniquement au dossier terminal (le plus profond).

*Utilisez soit name (dossier unique) soit path (hierarchie imbriquee), pas les deux.

Creation imbriquee : Lors de l'utilisation de path, les dossiers intermediaires sont crees automatiquement. Si un dossier du chemin existe deja, il est reutilise — l'operation est idempotente.

Exemple — dossier unique :

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

Exemple — hierarchie imbriquee avec tags :

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

Cela cree trois dossiers en un seul appel et renvoie le plus profond (2024-12-12) avec les tags specifies.

sutram_request_upload

Etape 1 du flux de telechargement direct. Valide le fichier et renvoie une URL PUT S3 pre-signee. Le fichier est telecharge directement sur S3 par le client — aucune donnee ne passe par les serveurs web Sutram.

Parametres :

Parametre	Type	Requis	Description
`filename`	string	Oui	Nom de fichier avec extension (par ex., `report.pdf`)
`file_size`	integer	Oui	Taille du fichier en octets
`content_type`	string	Non	Type MIME. Detecte automatiquement a partir de l'extension si omis.
`folder_id`	string	Non	UUID du dossier cible. Omettre pour la racine.

Exemple de reponse :

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

Etape 2 du flux de telechargement direct. Appelez ceci apres que le fichier a ete telecharge vers l'URL pre-signee. Verifie que l'objet S3 existe, cree l'enregistrement de fichier, met a jour l'utilisation du stockage et met en file d'attente la compression si applicable.

Parametres :

Parametre	Type	Requis	Description
`file_id`	string	Oui	UUID du fichier provenant de `sutram_request_upload`
`s3_key`	string	Oui	Cle S3 provenant de `sutram_request_upload`
`filename`	string	Oui	Nom de fichier original avec extension
`content_type`	string	Oui	Type MIME du fichier
`file_size`	integer	Oui	Taille du fichier en octets
`folder_id`	string	Non	UUID du dossier cible (doit correspondre a la requete)

Exemple de reponse :

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

Exemple de flux complet de telechargement :

# 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

Cree un lien web dans le projet. Sutram recupere automatiquement le titre de la page et le favicon a partir de l'URL.

Parametres :

Parametre	Type	Requis	Description
`url`	string	Oui	URL de la page web (doit etre http ou https)
`name`	string	Non	Nom d'affichage. Recupere automatiquement a partir du titre de la page si omis.
`folder_id`	string	Non	UUID du dossier cible. Omettre pour la racine.

Exemple de reponse :

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

Cree un lien video dans le projet. Prend en charge YouTube, Vimeo, DailyMotion, Wistia, Loom et TikTok. Detecte automatiquement la plateforme et extrait l'ID de la video a partir de l'URL.

Parametres :

Parametre	Type	Requis	Description
`url`	string	Oui	URL de la video (par ex., `https://www.youtube.com/watch?v=...`)
`name`	string	Non	Nom d'affichage. Par defaut, l'URL si omis.
`folder_id`	string	Non	UUID du dossier cible. Omettre pour la racine.

Exemple de reponse :

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

Cree un lien audio dans le projet. Prend en charge Spotify, SoundCloud, Apple Podcasts et plus encore. Detecte automatiquement la plateforme et extrait l'ID audio a partir de l'URL.

Parametres :

Parametre	Type	Requis	Description
`url`	string	Oui	URL du contenu audio (par ex., `https://open.spotify.com/track/...`)
`name`	string	Non	Nom d'affichage. Par defaut, l'URL si omis.
`folder_id`	string	Non	UUID du dossier cible. Omettre pour la racine.

Exemple de reponse :

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

Cree un lien de fichier (reference symbolique) vers un fichier existant dans le projet. Le lien apparait comme une reference en lecture seule sans dupliquer le stockage ni le versionnage. La source doit etre un fichier (pas un lien ni un autre lien de fichier). Si le fichier source est supprime, tous ses liens de fichier sont automatiquement supprimes.

Parametres :

Parametre	Type	Requis	Description
`source_content_item_id`	string	Oui	UUID de l'element de contenu du fichier source a lier
`name`	string	Non	Nom d'affichage (par defaut le nom du fichier source)
`folder_id`	string	Non	UUID du dossier cible (omettre pour la racine)
`description`	string	Non	Description du lien de fichier

Exemple de requete :

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

Exemple de reponse :

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

Cree en masse des liens de fichier pour tous les fichiers (ou un sous-ensemble filtre) dans un dossier source, en les placant dans un dossier cible. Ignore automatiquement les fichiers qui ont deja un lien dans le dossier cible (deduplication). Ideal pour les flux de travail comme la liaison de plusieurs fichiers d'examen a un dossier centralise de rapports.

Parametres :

Parametre	Type	Requis	Description
`source_folder_id`	string	Oui	UUID du dossier source contenant les fichiers a lier
`target_folder_id`	string	Oui	UUID du dossier cible ou les liens de fichier seront crees
`name_pattern`	string	Non	Filtre par sous-chaine (insensible a la casse) sur les noms de fichiers source. Seuls les fichiers correspondants sont lies.
`recursive`	boolean	Non	Inclure les fichiers des sous-dossiers du dossier source (par defaut : false)

Exemple de requete :

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

Exemple de reponse :

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

Astuce : Relancer la meme commande ignorera tous les fichiers precedemment lies ("created": 0, "skipped": 7), ce qui rend l'operation sure a re-executer.

sutram_list_file_links_for_source

Liste tous les liens de fichier pointant vers un fichier source donne. Repond a la question : « ou ce fichier est-il reference ? » Renvoie chaque lien avec son chemin de dossier.

Parametres :

Parametre	Type	Requis	Description
`source_content_item_id`	string	Oui	UUID de l'element de contenu du fichier source

Exemple de requete :

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

Exemple de reponse :

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

Liste tous les liens de fichier dans un dossier, enrichis avec les details du fichier source (nom, type de contenu, taille du fichier, chemin du dossier). Contrairement a sutram_get_folder, ceci fournit des informations completes sur le fichier source vers lequel chaque lien pointe.

Parametres :

Parametre	Type	Requis	Description
`folder_id`	string	Non	UUID du dossier (omettre pour la racine)

Exemple de requete :

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

Exemple de reponse :

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

Obtient les details complets d'un element de contenu par ID. Pour les fichiers, renvoie les metadonnees et une URL de telechargement pre-signee. Pour les liens (web, video, audio, lien de fichier), renvoie l'URL, les informations de plateforme et les metadonnees.

Parametres :

Parametre	Type	Requis	Description
`content_item_id`	string	Oui	UUID de l'element de contenu

Exemple de reponse (fichier) :

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

Exemple de reponse (lien 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"
}

Exemple de reponse (lien 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

Supprime un element de contenu (fichier, lien web, lien video, lien audio) ou un dossier du projet.

Parametres :

Parametre	Type	Requis	Description
`item_id`	string	Oui	UUID de l'element de contenu ou du dossier
`item_type`	string	Oui	`"content_item"` ou `"folder"`. Utilisez `"content_item"` pour tout type de contenu (fichiers, liens web, liens video, liens audio).

sutram_rename

Renomme un element de contenu (fichier, lien web, lien video, lien audio) ou un dossier.

Parametres :

Parametre	Type	Requis	Description
`item_id`	string	Oui	UUID de l'element de contenu ou du dossier
`item_type`	string	Oui	`"content_item"` ou `"folder"`. Utilisez `"content_item"` pour tout type de contenu (fichiers, liens web, liens video, liens audio).
`new_name`	string	Oui	Nouveau nom (pour les fichiers, incluez l'extension)

sutram_move_contents

Deplace tout le contenu (sous-dossiers et fichiers) d'un dossier source vers un dossier cible. Le dossier source est vide mais non supprime. Les conflits de noms sont geres automatiquement.

Parametres :

Parametre	Type	Requis	Description
`source_folder_id`	string	Oui	UUID du dossier source a vider
`target_folder_id`	string	Oui	UUID du dossier cible pour recevoir le contenu

Gestion des conflits de noms : Si un sous-dossier ou un fichier portant le meme nom existe deja dans le dossier cible, Sutram renomme automatiquement l'element deplace en ajoutant un suffixe numerique : Exams devient Exams (1), report.pdf devient report (1).pdf, et ainsi de suite.

Regles de validation :

La source et la cible doivent etre des dossiers differents
La cible ne peut pas etre un sous-dossier de la source (empeche les deplacements circulaires)
Les deux dossiers doivent exister dans le projet en cours

Exemple de reponse :

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

Deplace un seul element de contenu (fichier ou lien) vers un autre dossier. Les conflits de noms sont geres automatiquement.

Parametres :

Parametre	Type	Requis	Description
`content_item_id`	string	Oui	UUID de l'element de contenu a deplacer
`target_folder_id`	string/null	Non	UUID du dossier cible (null pour la racine)

Gestion des conflits de noms : Si un fichier portant le meme nom existe deja dans le dossier cible, Sutram renomme automatiquement le fichier deplace en ajoutant un suffixe numerique : report.pdf devient report (1).pdf, et ainsi de suite.

Exemple de reponse (sans conflit) :

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

Exemple de reponse (avec renommage) :

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

sutram_set_folder_tags

Definit des tags cle-valeur libres sur un dossier. Remplace tous les tags existants. Envoyez {} pour effacer tous les tags.

Parametres :

Parametre	Type	Requis	Description
`folder_id`	string	Oui	UUID du dossier
`tags`	object	Oui	Tags cle-valeur a definir. Envoyez `{}` pour effacer tous les tags.

Limites : Maximum 50 tags par dossier. Cle max 100 caracteres, valeur max 500 caracteres.

Semantique : Il s'agit d'une operation PUT — elle remplace tous les tags existants. Pour ajouter un tag sans supprimer les autres, lisez d'abord les tags actuels (via sutram_get_folder), fusionnez vos modifications, puis appelez sutram_set_folder_tags avec l'ensemble complet.

Exemple — definir des tags :

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

Exemple — effacer tous les tags :

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

Exemple de reponse :

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

sutram_search_folders

Recherche des dossiers par tag. Prend en charge les conditions uniques ou multiples AND. Toute correspondance est insensible a la casse pour les cles et les valeurs. Les valeurs prennent en charge la correspondance par sous-chaine (par ex., "orto" correspond a "Ortopedia"). Utilisez folder_id pour restreindre la recherche aux descendants d'un dossier specifique.

Parametres :

Parametre	Type	Requis	Description
`tag_name`	string	Non*	Cle de tag a rechercher (mode condition unique). Insensible a la casse.
`tag_value`	string	Non	Valeur a faire correspondre (mode condition unique). Correspondance par sous-chaine, insensible a la casse.
`conditions`	array	Non*	Conditions AND multiples. Chaque objet a `key` (requis) et `value` (optionnel).
`folder_id`	string	Non	UUID du dossier pour delimiter la recherche. Recherche uniquement les descendants de ce dossier.

*Utilisez soit tag_name (condition unique) soit conditions (conditions AND multiples).

Comportement de la recherche :

Correspondance de cle : Correspondance exacte insensible a la casse ("Patient" correspond a "patient")
Correspondance de valeur : Correspondance par sous-chaine insensible a la casse ("orto" correspond a "Ortopedia", "joao" correspond a "Joao Silva")
Sans valeur : Lorsque la valeur est omise, correspond a tout dossier qui possede la cle quelle que soit la valeur
Conditions multiples : Toutes les conditions doivent correspondre (logique AND)

Exemple — trouver tous les dossiers tagges avec "patient" :

{ "tag_name": "patient" }

Exemple — trouver les dossiers pour un patient specifique (correspondance par sous-chaine) :

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

Cela correspond aux dossiers ou le tag "patient" contient "joao" (par ex., "Joao Silva", "Joao Pedro").

Exemple — recherche AND avec conditions multiples :

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

Cela renvoie uniquement les dossiers qui correspondent aux deux conditions.

Exemple — rechercher uniquement dans une hierarchie de dossier specifique :

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

Exemple de reponse :

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

Renvoie toutes les cles de tag distinctes utilisees dans les dossiers du projet. Utile pour decouvrir quels tags sont disponibles avant d'effectuer une recherche. Utilisez folder_id pour restreindre aux descendants d'un dossier specifique.

Parametres :

Parametre	Type	Requis	Description
`folder_id`	string	Non	UUID du dossier pour delimiter. Renvoie uniquement les cles des descendants de ce dossier.

Exemple — obtenir toutes les cles de tag du projet :

{}

Exemple — obtenir les cles de tag dans une hierarchie de dossier :

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

Exemple de reponse :

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

sutram_set_item_tags

Definit des tags cle-valeur libres sur un element de contenu. Remplace tous les tags existants. Envoyez {} pour effacer tous les tags.

Parametres :

Parametre	Type	Requis	Description
`content_item_id`	string	Oui	UUID de l'element de contenu
`tags`	object	Oui	Tags cle-valeur a definir. Envoyez `{}` pour effacer tous les tags.

Limites : Maximum 50 tags par element. Cle max 100 caracteres, valeur max 500 caracteres.

Semantique : Il s'agit d'une operation PUT — elle remplace tous les tags existants. Pour ajouter un tag sans supprimer les autres, lisez d'abord les tags actuels (via sutram_get_item), fusionnez vos modifications, puis appelez sutram_set_item_tags avec l'ensemble complet.

Exemple — definir des tags :

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

Exemple — effacer tous les tags :

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

Exemple de reponse :

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

sutram_search_items

Recherche des elements de contenu par tag. Prend en charge les conditions uniques ou multiples AND. Toute correspondance est insensible a la casse pour les cles et les valeurs. Les valeurs prennent en charge la correspondance par sous-chaine (par ex., "neuro" correspond a "Neurologia"). Utilisez folder_id pour restreindre la recherche a un dossier specifique, et type pour filtrer par type de contenu.

Parametres :

Parametre	Type	Requis	Description
`tag_name`	string	Non*	Cle de tag a rechercher (mode condition unique). Insensible a la casse.
`tag_value`	string	Non	Valeur a faire correspondre (mode condition unique). Correspondance par sous-chaine, insensible a la casse.
`conditions`	array	Non*	Conditions AND multiples. Chaque objet a `key` (requis) et `value` (optionnel).
`folder_id`	string	Non	UUID du dossier pour delimiter la recherche.
`type`	string	Non	Filtre par type de contenu : `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

*Utilisez soit tag_name (condition unique) soit conditions (conditions AND multiples).

Exemple — trouver tous les elements tagges avec "topic" :

{ "tag_name": "topic" }

Exemple — trouver les elements pour un sujet specifique (correspondance par sous-chaine) :

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

Exemple — recherche AND avec conditions multiples :

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

Exemple — rechercher uniquement les liens video dans un dossier specifique :

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

Exemple de reponse :

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

sutram_get_item_tag_keys

Renvoie toutes les cles de tag distinctes utilisees sur les elements de contenu dans le projet. Utile pour decouvrir quels tags sont disponibles avant d'effectuer une recherche. Utilisez folder_id pour restreindre a un dossier specifique, et type pour filtrer par type de contenu.

Parametres :

Parametre	Type	Requis	Description
`folder_id`	string	Non	UUID du dossier pour delimiter.
`type`	string	Non	Filtre par type de contenu : `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

Exemple — obtenir toutes les cles de tag de contenu dans le projet :

{}

Exemple — obtenir les cles de tag pour les liens video uniquement :

{ "type": "video_link" }

Exemple de reponse :

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

Versionnage de fichiers

Sutram prend en charge un flux de travail complet de versionnage pour les fichiers via MCP. Cela permet aux assistants IA d'activer le controle de version, d'effectuer le check-out de fichiers pour une edition exclusive, de telecharger des modifications et de publier des versions.

Flux de travail

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)

Outils de versionnage

Outil	Description	Permission
`sutram_enable_versioning`	Convertir le fichier de reference en editable (demarrer le versionnage)	Owner, Member
`sutram_disable_versioning`	Reconvertir le fichier en reference (arreter le versionnage)	Owner, Member
`sutram_checkout_file`	Effectuer le check-out d'un fichier pour edition exclusive	Owner, Admin, Member
`sutram_checkin_file`	Liberer le verrou de check-out	Utilisateur du check-out
`sutram_cancel_checkout`	Annuler le check-out sans modifications	Utilisateur du check-out
`sutram_force_release_lock`	Forcer la liberation du check-out d'un autre utilisateur	Owner uniquement
`sutram_publish_version`	Publier un fichier brouillon, creant un instantane de version	Owner uniquement
`sutram_create_new_version`	Demarrer une nouvelle version a partir d'un fichier publie	Owner uniquement
`sutram_undo_checkin`	Annuler le dernier check-in, restaurer la version precedente	Dernier utilisateur du check-in
`sutram_list_versions`	Lister toutes les versions publiees avec URL de telechargement	Tout membre
`sutram_upload_modified_file`	Remplacer le contenu du fichier pendant le check-out	Utilisateur du check-out

Parametres

Tous les outils de versionnage necessitent content_item_id (UUID de l'element de contenu).

sutram_upload_modified_file necessite en outre :

Parametre	Type	Description
`s3_key`	string	Cle S3 provenant de `sutram_request_upload`
`file_name`	string	Nom de fichier avec extension
`file_size`	integer	Taille du fichier en octets
`content_type`	string	Type MIME

Exemple : Flux complet de versionnage

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

Categories d'enregistrement et enregistrements

Sutram prend en charge les enregistrements structures avec des schemas de metadonnees et des slugs generes automatiquement. Cela permet aux assistants IA de definir des champs de metadonnees, de creer des categories d'enregistrement et de gerer des enregistrements de maniere programmatique.

Exigence de forfait : Les outils de gestion des enregistrements et schemas necessitent un forfait avec la fonctionnalite Records activee (Plus ou superieur). Les outils en lecture seule (sutram_get_metadata_definitions, sutram_get_record_categories, sutram_get_record_category_detail) sont disponibles sur tous les forfaits.

Concepts

Definitions de metadonnees — Schemas de champs qui definissent les types, labels et valeurs autorisees pour les champs de metadonnees (par ex., "language" en tant qu'enum avec les valeurs "PT", "EN", "ES").
Categories d'enregistrement — Modeles qui definissent quels champs de metadonnees un enregistrement utilise, leur ordre, comment la base de numerotation est calculee (computed_from), et comment le slug (nom de l'enregistrement) est compose (slug_from).
Enregistrements — Dossiers crees avec une categorie, des metadonnees validees et un slug genere automatiquement.

Generation du slug

Les enregistrements ont un slug genere automatiquement (utilise comme nom de l'enregistrement). Le slug est construit en deux etapes :

Base de numerotation — Determinee par les entrees computed_from sur un tag de metadonnee calcule. Cela definit quelles valeurs de champ forment la cle d'unicite pour la numerotation sequentielle.
Composition du slug — Determinee par les entrees slug_from sur la categorie. Cela definit quelles valeurs de champ (y compris le tag calcule) composent le slug final.

Sans slug_from (retrocompatible) : slug = number_base + separator + sequence_number (par ex., 0100-200-001).

Avec slug_from : le slug est compose a partir des champs references dans l'ordre (par ex., MD-3010.95-0000-000-SWA-001).

Outils de schema

Outil	Description	Permission
`sutram_get_metadata_definitions`	Lister toutes les definitions de metadonnees	Tout membre
`sutram_get_record_categories`	Lister toutes les categories d'enregistrement	Tout membre
`sutram_get_record_category_detail`	Categorie avec metadonnees resolues (labels, types, valeurs autorisees)	Tout membre
`sutram_upsert_metadata`	Creer ou mettre a jour une definition de metadonnee	Owner uniquement
`sutram_delete_metadata`	Supprimer une definition de metadonnee (echoue si en cours d'utilisation)	Owner uniquement
`sutram_add_enum_values`	Ajouter des valeurs a une definition enum (fusion, deduplication, tri)	Owner uniquement
`sutram_remove_enum_values`	Supprimer des valeurs d'une definition enum par code	Owner uniquement
`sutram_upsert_record_category`	Creer ou mettre a jour une categorie d'enregistrement	Owner uniquement
`sutram_delete_record_category`	Supprimer une categorie d'enregistrement	Owner uniquement

Outils CRUD d'enregistrement

Outil	Description	Permission
`sutram_create_record`	Creer un enregistrement avec categorie, metadonnees et slug genere automatiquement	Owner, Admin, Member
`sutram_update_record`	Mettre a jour les metadonnees d'un enregistrement (recalcule le slug si necessaire)	Owner, Admin, Member
`sutram_delete_record`	Supprimer un enregistrement et tout son contenu recursivement	Owner, Admin, Member

sutram_get_metadata_definitions

Renvoie toutes les definitions de metadonnees pour le projet. Chaque definition a une cle et des proprietes : label, type (text, enum, boolean, date, computed), et des valeurs optionnelles, depends_on, values_map.

Parametres : Aucun

sutram_get_record_categories

Renvoie toutes les categories d'enregistrement pour le projet. Chaque categorie definit quels champs de metadonnees un enregistrement utilise, la configuration du slug et l'ordonnancement.

Parametres : Aucun

sutram_get_record_category_detail

Renvoie une categorie d'enregistrement avec les metadonnees entierement resolues (labels, types, valeurs autorisees provenant des definitions). Utilisez ceci pour comprendre quels champs sont necessaires avant de creer un enregistrement.

Parametres :

Parametre	Type	Requis	Description
`category_id`	string	Oui	ID de la categorie d'enregistrement

sutram_upsert_metadata

Cree ou met a jour une definition de metadonnee (schema de champ). Pour les types enum, fournissez le tableau complet values. Pour les grands enums, preferez sutram_add_enum_values pour des ajouts incrementaux.

Parametres :

Parametre	Type	Requis	Description
`key`	string	Oui	Cle unique (snake_case, par ex., `"specialty"`)
`definition`	object	Oui	Definition avec `label`, `type` et champs optionnels

Types pris en charge : text, enum, boolean, date, computed.

Exemple — creer un enum simple :

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

sutram_delete_metadata

Supprime une definition de metadonnee. Echoue si la definition est actuellement utilisee par une categorie d'enregistrement.

Parametres :

Parametre	Type	Requis	Description
`key`	string	Oui	Cle de la definition a supprimer

sutram_add_enum_values

Ajoute des valeurs a une definition de metadonnee de type enum existante. Les nouvelles valeurs sont fusionnees avec les existantes — les doublons (par code) sont ignores. Les valeurs sont triees par code apres la fusion. Utilisez ceci au lieu de sutram_upsert_metadata lorsque vous travaillez avec de grands enums pour eviter d'envoyer le tableau de valeurs entier.

Parametres :

Parametre	Type	Requis	Description
`key`	string	Oui	Cle de la definition enum
`values`	array	Oui	Tableau d'objets `{label, code}` a ajouter

Exemple — ajouter des valeurs a un enum existant avec 800+ elements :

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

Exemple de reponse :

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

sutram_remove_enum_values

Supprime des valeurs d'une definition de metadonnee de type enum existante par leurs codes.

Parametres :

Parametre	Type	Requis	Description
`key`	string	Oui	Cle de la definition enum
`codes`	array	Oui	Tableau de chaines de code a supprimer

Exemple :

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

Exemple de reponse :

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

sutram_upsert_record_category

Cree ou met a jour une categorie d'enregistrement. Les metadonnees doivent referencer des definitions existantes. Utilisez computed_from sur une entree de metadonnee pour definir la base de numerotation (unicite). Utilisez slug_from au niveau de la categorie pour definir comment le slug (nom de l'enregistrement) est compose.

Parametres :

Parametre	Type	Requis	Description
`category_id`	string	Oui	ID unique de la categorie (snake_case)
`category`	object	Oui	Definition de la categorie (voir champs ci-dessous)

Champs de la categorie :

Champ	Type	Requis	Description
`name`	string	Oui	Nom d'affichage de la categorie
`metadata`	array	Oui	Tableau de references de champs de metadonnees (voir ci-dessous)
`slug_separator`	string	Non	Separateur entre les parties du slug (par defaut : `"-"`)
`slug_from`	array	Non	Definit la composition du slug. Chaque entree a `key` et `use` (`"code"` ou `"label"`). Si omis, slug = number_base + separator + sequence_number

Champs d'entree de metadonnees :

Champ	Type	Requis	Description
`key`	string	Oui	Cle d'une definition de metadonnee existante
`required`	boolean	Non	Si ce champ est requis (par defaut : false)
`order`	integer	Non	Ordre d'affichage (base 0)
`computed_from`	array	Non	Pour les tags calcules uniquement. Definit la base de numerotation. Chaque entree a `key` et `use` (`"code"` ou `"label"`)
`sequence_digits`	integer	Non	Pour les tags calcules uniquement. Chiffres pour le numero de sequence (2-4, par defaut : 2)

Exemple — categorie avec slug_from (style 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" }
    ]
  }
}

Dans cet exemple :

Base de numerotation (depuis computed_from) : MD-3010.95-0000-000 — determine l'unicite sequentielle
Numero code : 001 (prochaine sequence disponible)
Slug (depuis slug_from) : MD-3010.95-0000-000-SWA-001 — inclut document_origin + sequence

Exemple — categorie simple sans slug_from (retrocompatible) :

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

Sans slug_from, le slug est automatiquement : {number_base}{separator}{sequence} (par ex., CARDIO-001).

sutram_delete_record_category

Supprime une categorie d'enregistrement.

Parametres :

Parametre	Type	Requis	Description
`category_id`	string	Oui	ID de la categorie a supprimer

sutram_create_record

Cree un enregistrement avec une categorie, des metadonnees validees et un slug genere automatiquement. Le slug est calcule a partir de la definition slug_from de la categorie, ou a partir de computed_from (base de numerotation) + separateur + numero de sequence. Utilisez d'abord sutram_get_record_category_detail pour voir les champs requis.

Parametres :

Parametre	Type	Requis	Description
`category_id`	string	Oui	ID de la categorie d'enregistrement
`metadata`	object	Oui	Paires cle-valeur correspondant aux champs de metadonnees de la categorie
`parent_folder_id`	string	Non	UUID du dossier parent (omettre pour la racine)
`name`	string	Non	Nom personnalise (par defaut le slug genere automatiquement)

Exemple :

{
  "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 reponse inclut le slug calcule et le numero de sequence :

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

Met a jour les metadonnees d'un enregistrement. Recalcule la base de numerotation et le slug lorsque les champs de metadonnees references par computed_from ou slug_from changent.

Parametres :

Parametre	Type	Requis	Description
`record_id`	string	Oui	UUID de l'enregistrement (dossier)
`metadata`	object	Oui	Paires cle-valeur mises a jour
`name`	string	Non	Nouveau nom (optionnel)

sutram_delete_record

Supprime un enregistrement et tout son contenu (sous-dossiers et fichiers) recursivement. Cette action ne peut pas etre annulee.

Parametres :

Parametre	Type	Requis	Description
`record_id`	string	Oui	UUID de l'enregistrement (dossier) a supprimer

Exemple : Flux complet d'enregistrement

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

Notez comment :

La base de numerotation PT-0100 (depuis computed_from : language + area) determine l'unicite sequentielle
Le slug PT-0100-SWA-001 (depuis slug_from) inclut origin + le numero de sequence
Le second enregistrement obtient la sequence 002 car il partage la meme base de numerotation PT-0100

Commentaires sur les documents

Les assistants IA peuvent lister, creer, repondre, resoudre et supprimer des commentaires sur les fichiers du projet. Les commentaires crees via MCP apparaissent en temps reel dans l'interface web et vice versa, grace a la diffusion PubSub.

Restriction de type de position : Via MCP, l'IA ne peut creer que des commentaires file_level (commentaire sur l'ensemble du fichier) ou markdown (ancres au texte dans les fichiers markdown). Les types de position necessitant des coordonnees GUI (pdf_page, aps_3d, aps_2d, image) peuvent etre lus mais pas crees via MCP.

Outils de commentaires

Outil	Description	Permission
`sutram_list_comments`	Lister tous les commentaires de niveau superieur sur un element de contenu	Tout membre
`sutram_get_comment_thread`	Obtenir un commentaire avec son fil complet de reponses	Tout membre
`sutram_create_comment`	Creer un commentaire au niveau du fichier ou un commentaire markdown	Tout membre
`sutram_reply_to_comment`	Repondre a un commentaire de niveau superieur	Tout membre
`sutram_resolve_comment`	Resoudre ou rouvrir un fil de commentaire	Tout membre
`sutram_delete_comment`	Supprimer un commentaire et toutes ses reponses	Auteur, Owner ou Admin

sutram_list_comments

Liste tous les commentaires de niveau superieur sur un element de contenu. Renvoie le contenu du commentaire, l'auteur, le type de position, le statut de resolution et le nombre de reponses.

Parametres :

Parametre	Type	Requis	Description
`content_item_id`	string	Oui	UUID de l'element de contenu
`include_resolved`	boolean	Non	Inclure ou non les commentaires resolus (par defaut : true)

Exemple :

{
  "content_item_id": "abc-123"
}

Reponse :

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

Obtient un commentaire unique avec son fil complet de reponses, le statut de resolution et les details de l'auteur.

Parametres :

Parametre	Type	Requis	Description
`comment_id`	string	Oui	UUID du commentaire

Reponse :

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

Cree un commentaire sur un element de contenu. L'IA peut creer des commentaires file_level (par defaut) ou markdown.

Parametres :

Parametre	Type	Requis	Description
`content_item_id`	string	Oui	UUID de l'element de contenu
`content`	string	Oui	Texte du commentaire
`position_type`	string	Non	`"file_level"` (par defaut) ou `"markdown"`
`text_anchor`	object	Non	Pour markdown : `{exact_text, prefix, suffix}`
`original_text_snippet`	string	Non	Pour markdown : l'extrait de texte selectionne

Exemple — commentaire au niveau du fichier :

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

Exemple — commentaire markdown ancre au texte :

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

Repond a un commentaire de niveau superieur existant. Les reponses ne peuvent pas etre imbriquees (pas de reponse a une reponse).

Parametres :

Parametre	Type	Requis	Description
`comment_id`	string	Oui	UUID du commentaire de niveau superieur
`content`	string	Oui	Texte de la reponse

Exemple :

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

sutram_resolve_comment

Resout ou rouvre un fil de commentaire. Les commentaires resolus indiquent que le probleme a ete traite.

Parametres :

Parametre	Type	Requis	Description
`comment_id`	string	Oui	UUID du commentaire
`action`	string	Oui	`"resolve"` ou `"reopen"`

Exemple :

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

sutram_delete_comment

Supprime un commentaire et toutes ses reponses. Seul l'auteur du commentaire ou le proprietaire/administrateur du projet peut supprimer.

Parametres :

Parametre	Type	Requis	Description
`comment_id`	string	Oui	UUID du commentaire

Exemple : Flux complet de commentaires

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

Toutes les modifications de commentaires sont diffusees en temps reel aux utilisateurs visualisant le meme document dans l'interface web.

Limitations

Les operations suivantes ne sont pas encore disponibles via MCP et doivent etre effectuees via l'interface web Sutram. Elles seront ajoutees dans les versions futures :

Partage : Les liens de partage ne peuvent pas etre generes
Commentaires positionnes : La creation de commentaires ancres aux pages PDF, aux coordonnees CAO ou aux positions sur les images necessite l'interface web

Permissions

Votre acces MCP respecte les memes permissions que l'interface web :

Role	Parcourir	Telecharger/Creer	Deplacer	Supprimer	Versionnage	Schema d'enregistrement	Enregistrements	Commentaires
Owner	Oui	Oui	Oui	Oui	Complet (publier, forcer la liberation)	Complet (CRUD definitions et categories)	CRUD	Complet (lister, creer, repondre, resoudre, supprimer tout)
Admin	Oui	Oui	Oui	Oui	Check-out/check-in	Lecture seule	CRUD	Complet (lister, creer, repondre, resoudre, supprimer tout)
Member	Oui	Oui	Oui	Oui	Activer/desactiver, check-out/check-in	Lecture seule	CRUD	Lister, creer, repondre, resoudre, supprimer les siens
Viewer	Pas d'acces MCP	—	—	—	—	—	—	—

Les viewers ne peuvent pas utiliser l'acces a distance. Si vous avez besoin d'un acces MCP, demandez au proprietaire du projet de mettre a niveau votre role.

Securite

Les cles sont independantes : Revoquer une cle utilisateur n'affecte pas les autres utilisateurs. Revoquer une cle de projet desactive l'acces a distance pour tout le monde sur ce projet.
Une cle de projet par projet : Il n'existe qu'une seule cle de projet active a la fois. La regenerer invalide la precedente.
Les cles ne sont jamais stockees en texte brut : Les cles de projet sont chiffrees. Les cles utilisateur sont hachees — elles ne peuvent pas etre recuperees apres la creation.
Suivi d'activite : Chaque cle enregistre quand elle a ete utilisee pour la derniere fois.
HTTPS uniquement : Toutes les connexions MCP utilisent HTTPS chiffre.

Revoquer l'acces

Pour revoquer votre cle personnelle :

Allez dans Parametres > Cle API
Cliquez sur « Revoquer la cle »
Creez-en une nouvelle si necessaire

Pour desactiver l'acces a distance d'un projet (proprietaire uniquement) :

Allez dans Parametres > Projets
Ouvrez le menu deroulant du projet
Cliquez sur « Acces a distance »
Cliquez sur « Revoquer la cle »

Depannage

« Echec de l'authentification »

Verifiez que les deux cles sont correctes et n'ont pas ete revoquees
Assurez-vous d'etre un membre actif du projet
Les viewers ne peuvent pas utiliser l'acces a distance — verifiez votre role sur la page du projet

« Cle de projet non disponible »

La cle de projet a peut-etre ete revoquee par le proprietaire
Demandez au proprietaire du projet de la regenerer depuis les parametres du projet

« Quota de stockage depasse »

La limite de stockage de votre compte a ete atteinte
Supprimez les fichiers inutilises ou mettez a niveau votre forfait

Les outils n'apparaissent pas dans Claude Code

Claude Code ne prend pas encore en charge type: "url" — utilisez la configuration pont mcp-remote (voir Configuration de Claude Code)
Assurez-vous que Node.js est installe (npx doit etre disponible dans votre PATH)
Verifiez que le fichier .mcp.json est dans le dossier ou vous lancez Claude Code

Les outils n'apparaissent pas dans Claude Desktop

Redemarrez Claude Desktop apres avoir modifie le fichier de configuration
Verifiez que la syntaxe JSON est valide (pas de virgules finales, guillemets corrects)
Verifiez que l'URL du point de terminaison est correcte
Si type: "url" ne fonctionne pas, essayez la configuration pont mcp-remote (voir Configuration de Claude Desktop)

Delai de connexion depasse

Verifiez votre connexion internet
Verifiez que le service Sutram est accessible a https://sutram.io

Types de fichiers pris en charge

Sutram detecte automatiquement les types MIME a partir des extensions de fichier. Formats courants pris en charge :

Categorie	Extensions
Images	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`
Documents	`.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`
Texte	`.txt`, `.csv`, `.json`, `.xml`, `.md`
Medias	`.mp4`, `.mp3`, `.wav`
Archives	`.zip`
CAO	`.dwg`, `.dxf`, `.rvt`, `.ifc`

Les fichiers avec des extensions non reconnues sont telecharges en tant que application/octet-stream.

Plateformes de liens prises en charge

Plateformes video

YouTube, Vimeo, DailyMotion, Wistia, Loom et TikTok. La plateforme est detectee automatiquement a partir de l'URL, et les vignettes sont extraites lorsque disponibles.

Plateformes audio

Spotify, SoundCloud, Apple Podcasts, Anchor et d'autres. La plateforme est detectee automatiquement a partir de l'URL.

Liens web

Toute URL HTTP/HTTPS valide. Le titre de la page, la description et le favicon sont recuperes automatiquement.

Exemples

Migrer des examens medicaux depuis des portails hospitaliers

« Telechargez mon examen d'echographie depuis le portail hospitalier et organisez-le dans Sutram sous le dossier du medecin demandeur. »

L'assistant IA va :

Acceder au portail hospitalier (via navigateur)
Telecharger le rapport PDF et les fichiers image
Utiliser sutram_create_folder pour construire la structure de dossiers en un seul appel : Nom du medecin / Type d'examen / AAAA-MM-JJ
Utiliser sutram_request_upload + sutram_confirm_upload pour telecharger chaque fichier directement sur S3
Nettoyer les fichiers locaux temporaires

Ce flux de travail assure que les donnees medicales sont correctement organisees et qu'aucun fichier sensible ne reste sur l'ordinateur local.

Telecharger un fichier local

« Telechargez le fichier report.pdf de mon bureau vers le dossier 'Reports' dans Sutram. »

Claude lira le fichier, utilisera sutram_get_folder pour trouver le dossier "Reports", puis sutram_request_upload pour obtenir une URL pre-signee, telechargera le fichier directement sur S3 via HTTP PUT, et appellera sutram_confirm_upload pour finaliser.

Organiser le contenu du projet

« Creez une structure de dossiers pour notre projet de construction : Plans, Rapports et Photos. Puis telechargez ces photos du site. »

Claude utilisera sutram_create_folder pour chaque dossier de niveau superieur, puis sutram_request_upload + sutram_confirm_upload pour telecharger chaque photo dans le bon dossier.

Nettoyer d'anciens fichiers

« Supprimez tous les fichiers du dossier 'Temp'. »

Claude utilisera sutram_get_folder pour lister le contenu du dossier, puis sutram_delete pour chaque fichier.

Reorganiser la structure des dossiers

« Deplacez tout le contenu du dossier '2024' dans '2024-Archive' pour liberer de l'espace dans la vue principale. »

Claude utilisera sutram_move_contents pour transferer tous les sous-dossiers et fichiers du dossier source vers le dossier cible en une seule operation. Si des elements ont des noms en conflit, ils sont automatiquement renommes avec des suffixes numeriques.

Deplacer un fichier specifique

« Deplacez le fichier 'contract.pdf' vers le dossier 'Legal'. »

Claude utilisera sutram_get_folder pour trouver le fichier et le dossier cible, puis sutram_move_item pour deplacer le fichier. Si un fichier portant le meme nom existe deja dans le dossier cible, il sera automatiquement renomme (par ex., contract (1).pdf).

Enregistrer un lien web

« Enregistrez cet article dans mon projet : https://example.com/building-codes-2026 »

Claude utilisera sutram_create_web_link avec l'URL. Sutram recupere automatiquement le titre de la page et le favicon, de sorte que le lien apparait avec son nom correct dans le projet.

Organiser des references video

« Ajoutez ces videos YouTube au dossier 'Formation' : [URL video1], [URL video2]. »

Claude utilisera sutram_get_folder pour trouver le dossier "Formation", puis appellera sutram_create_video_link pour chaque URL. Sutram detecte qu'il s'agit de videos YouTube et extrait les vignettes automatiquement.

Telecharger un fichier

« Donnez-moi le lien de telechargement du fichier 'site-plan.pdf'. »

Claude utilisera sutram_get_folder pour trouver le fichier, puis sutram_get_item pour recuperer une URL de telechargement pre-signee. L'URL est temporaire et peut etre utilisee pour telecharger le fichier directement.

Taguer et rechercher des dossiers

« Organisez mes examens medicaux par patient et type d'examen, puis trouvez tous les dossiers pour le patient Joao. »

Claude va :

Utiliser sutram_create_folder avec path et tags pour creer des dossiers structures avec des metadonnees
Utiliser sutram_set_folder_tags pour ajouter ou mettre a jour des tags sur des dossiers existants
Utiliser sutram_search_folders avec tag_name: "patient" et tag_value: "Joao" pour trouver tous les dossiers correspondants (correspondance par sous-chaine — trouve aussi "Joao Pedro", "Joao Silva")

Les tags permettent aux assistants IA de creer des structures organisationnelles riches et recherchables sans se fier uniquement aux noms de dossiers.

Decouvrir les tags et effectuer des recherches AND

« Trouvez tous les examens USG pour le patient Joao dans le dossier du Dr. Mion. »

Claude va :

Utiliser sutram_get_tag_keys avec l'ID du dossier pour decouvrir les cles de tag disponibles dans ce perimetre

Utiliser sutram_search_folders avec plusieurs conditions AND :

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

Renvoyer uniquement les dossiers qui correspondent aux deux conditions dans la hierarchie specifiee

Telecharger des fichiers via script

Lors du telechargement de fichiers via un assistant IA, l'assistant utilise le flux d'URL pre-signee en deux etapes : sutram_request_upload pour obtenir une URL PUT S3 pre-signee, puis telecharge le fichier directement sur S3, et enfin appelle sutram_confirm_upload pour creer l'enregistrement de fichier. Cette approche evite la surcharge d'encodage base64 et n'a pas de limite pratique de taille de fichier au-dela du quota de stockage de votre forfait.

Pour l'automatisation ou les telechargements par lots en dehors du contexte de l'assistant IA, vous pouvez appeler le point de terminaison MCP directement via HTTP.

Fonctionnement du point de terminaison HTTP MCP

Le serveur MCP Sutram utilise le transport Streamable HTTP (JSON-RPC 2.0 sur HTTPS) :

Initialiser une session — POST https://app.sutram.io/mcp avec la methode initialize
Capturer l'ID de session — depuis l'en-tete de reponse mcp-session-id
Envoyer une notification — notifications/initialized (requis par le protocole MCP)
Appeler les outils — POST avec la methode tools/call, en passant le nom de l'outil et les arguments

Toutes les requetes doivent inclure les en-tetes d'authentification (x-project-key et x-user-key) et, apres l'initialisation, l'en-tete mcp-session-id.

Exemple : Script de telechargement 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();

Enregistrez sous upload.mjs et executez :

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

Integration de competence Claude Code

Si vous utilisez Claude Code, vous pouvez encapsuler ce script en tant que competence pour que l'assistant puisse l'invoquer automatiquement lorsqu'il a besoin de telecharger des fichiers. Placez le script dans .claude/skills/sutram-upload/scripts/upload.mjs et creez un SKILL.md qui indique a Claude comment l'appeler. Ainsi, lorsque l'assistant rencontre un fichier a telecharger, il delegue les operations d'E/S lourdes au script externe tout en gardant l'orchestration dans la conversation.

Points cles

Pas de limite de taille de fichier au-dela du quota de stockage de votre forfait Sutram
Les fichiers sont telecharges directement sur S3 via URL pre-signee — pas d'encodage base64, pas de donnees transitant par le serveur web
Le script gere la poignee de main MCP complete (initialize > notify > tool call)
La reponse peut arriver en JSON ou en Server-Sent Events (SSE) selon le temps de traitement — le script gere les deux
Les identifiants peuvent etre lus depuis .mcp.json pour eviter de les coder en dur

API REST

En plus des outils MCP, Sutram fournit une API REST pour la consommation en lecture seule du contenu de projet. Elle utilise la meme authentification a double cle et est ideale pour les applications externes, les tableaux de bord et les scripts.

URL de base : https://sutram.io/api/v1

Points de terminaison :

Point de terminaison	Description
`GET /api/v1/project`	Informations sur le projet
`GET /api/v1/folders`	Lister les dossiers racine
`GET /api/v1/folders/:id`	Detail du dossier avec sous-dossiers et elements
`GET /api/v1/content`	Lister les elements de contenu avec filtrage, recherche par tags et pagination
`GET /api/v1/content/:id`	Detail de l'element de contenu avec URL de telechargement pre-signees

Documentation complete : Reference API REST v1