Guia do Sutram MCP Server

Versão: 0.113.0 Data: 2026-08-20 Status: Em produção

Visão Geral

Este é o guia de referência das ferramentas expostas pelo servidor MCP do Sutram. Uma vez conectado, seu assistente de IA pode navegar por pastas, fazer upload de arquivos, adicionar links web/vídeo/áudio, gerenciar registros estruturados e metadados, construir a wiki / grafo de conhecimento, operar fluxos de governança (Classes de Documentos), versionar arquivos, participar do chat do projeto e interagir com comentários — tudo com autenticação e permissões adequadas.

Como conectar: este documento cobre o que cada ferramenta faz. Para conectar o Sutram ao Claude (ou a outro cliente MCP) — pelo conector OAuth ou pela ponte por chave de API — veja Conectando o Sutram ao Claude.

Requisito de plano: o acesso MCP requer o plano Pro ou superior. Visualizadores conectam com uma superfície somente-leitura (ferramentas de escrita de conteúdo ficam ocultas e negadas; comentários e chat permanecem disponíveis).

Ferramentas Disponíveis

Uma vez conectado, seu assistente de IA tem acesso a estas ferramentas. Você também pode obter esta lista programaticamente enviando a requisição MCP padrão tools/list para o endpoint do servidor.

Referência Rápida (A–Z)

#	Ferramenta	Categoria	Descrição
1	`sutram_add_enum_values`	Schema	Adiciona novos valores a uma definição de metadados enum existente
2	`sutram_bulk_create_file_links`	File Links	Cria file links em massa de uma pasta de origem para uma pasta de destino
3	`sutram_cancel_checkout`	Versionamento	Cancela o checkout sem fazer upload de alterações
4	`sutram_checkin_file`	Versionamento	Libera um arquivo do checkout (checkin)
5	`sutram_checkout_file`	Versionamento	Faz checkout de um arquivo para edição exclusiva
6	`sutram_confirm_upload`	Conteúdo	Passo 2 do upload: confirma que o arquivo foi enviado ao S3
7	`sutram_create_audio_link`	Conteúdo	Cria um link de áudio (Spotify, SoundCloud, etc.)
8	`sutram_create_comment`	Comentários	Cria um comentário no nível do arquivo ou em markdown em um item de conteúdo
9	`sutram_create_document`	Governança	Cria um documento governado (família + 1ª versão) em uma Classe de Documento
10	`sutram_create_document_version`	Versionamento	Cria uma nova revisão de um documento governado
11	`sutram_create_documents`	Governança	Cria em lote vários documentos governados da mesma Classe
12	`sutram_create_file_link`	File Links	Cria um file link (referência simbólica) para um arquivo existente
13	`sutram_create_folder`	Pastas	Cria uma nova pasta ou caminho aninhado
14	`sutram_create_new_version`	Versionamento	Cria uma nova versão a partir de um arquivo publicado
15	`sutram_create_record`	Registros	Cria um novo registro em uma categoria
16	`sutram_create_video_link`	Conteúdo	Cria um link de vídeo (YouTube, Vimeo, etc.)
17	`sutram_create_web_link`	Conteúdo	Cria um link web com título obtido automaticamente
18	`sutram_create_wiki_node`	Wiki	Cria um nó de wiki (entidade/conceito) que menções `[[slug]]` referenciam
19	`sutram_delete`	Conteúdo	Exclui um item de conteúdo ou pasta
20	`sutram_delete_comment`	Comentários	Exclui um comentário e todas as suas respostas
21	`sutram_delete_metadata`	Schema	Exclui uma definição de metadados
22	`sutram_delete_record`	Registros	Exclui um registro
23	`sutram_delete_record_category`	Schema	Exclui uma categoria de registros
24	`sutram_delete_wiki_node`	Wiki	Exclui (soft-delete) um nó de wiki
25	`sutram_disable_versioning`	Versionamento	Converte o arquivo de volta para referência (somente leitura)
26	`sutram_enable_versioning`	Versionamento	Converte o arquivo de referência para editável
27	`sutram_force_release_lock`	Versionamento	Libera forçadamente o checkout de outro usuário (apenas proprietário)
28	`sutram_get_backlinks`	Wiki	Lista os backlinks de um item (quem o menciona via `[[slug]]`)
29	`sutram_get_chat_thread`	Chat	Obtém uma mensagem do chat com sua thread de respostas
30	`sutram_get_chat_unread_count`	Chat	Retorna quantas mensagens do chat ainda não foram lidas
31	`sutram_get_comment_thread`	Comentários	Obtém um comentário com sua thread completa de respostas
32	`sutram_get_folder`	Pastas	Retorna o conteúdo de uma pasta
33	`sutram_get_item`	Conteúdo	Obtém detalhes completos e URL de download de um item de conteúdo
34	`sutram_get_item_tag_keys`	Tags	Retorna todas as chaves de tag distintas usadas em itens de conteúdo
35	`sutram_get_metadata_definitions`	Schema	Retorna todas as definições de campos de metadados
36	`sutram_get_outgoing_mentions`	Wiki	Lista as menções `[[slug]]` que saem de uma origem (resolvidas ou pendentes)
37	`sutram_get_record_categories`	Schema	Retorna todas as categorias de registros
38	`sutram_get_record_category_detail`	Schema	Retorna uma categoria com metadados resolvidos (e o lifecycle, se governada)
39	`sutram_get_tag_keys`	Tags	Retorna todas as chaves de tag distintas usadas em pastas
40	`sutram_get_wiki_node`	Wiki	Retorna um nó de wiki por id ou slug, com síntese e texto integral
41	`sutram_graduate_document_class`	Governança	Gradua uma categoria de registros para Classe de Documento governada
42	`sutram_grant_class_role`	Governança	Concede um papel de classe a um membro ativo do projeto, opcionalmente com escopo por metadado
43	`sutram_list_chat_messages`	Chat	Lista as mensagens do chat do projeto
44	`sutram_list_class_grants`	Governança	Lista as concessões de papel de classe de uma Classe de Documento (quem tem qual papel, com escopo)
45	`sutram_list_comments`	Comentários	Lista todos os comentários de nível superior em um item de conteúdo
46	`sutram_list_document_classes`	Governança	Lista as Classes de Documento acessíveis
47	`sutram_list_file_links_for_source`	File Links	Lista todos os file links que apontam para um arquivo de origem
48	`sutram_list_file_links_in_folder`	File Links	Lista file links em uma pasta com detalhes do arquivo de origem
49	`sutram_list_governed_documents`	Governança	Lista os documentos governados de uma Classe de Documento
50	`sutram_list_versions`	Versionamento	Lista todas as versões de um arquivo
51	`sutram_mark_chat_visited`	Chat	Marca o chat como lido (zera o contador de não lidas)
52	`sutram_move_contents`	Pastas	Move todo o conteúdo de uma pasta para outra
53	`sutram_move_item`	Conteúdo	Move um único item de conteúdo para outra pasta
54	`sutram_patch_record_metadata`	Registros	Atualiza campos específicos de um registro (merge), preservando os demais
55	`sutram_project_info`	Projeto	Retorna nome, descrição e configurações do projeto
56	`sutram_publish_version`	Versionamento	Publica um arquivo rascunho, criando um snapshot de versão
57	`sutram_remove_enum_values`	Schema	Remove valores de uma definição de metadados enum
58	`sutram_rename`	Conteúdo	Renomeia um item de conteúdo ou pasta
59	`sutram_reply_to_chat_message`	Chat	Responde a uma mensagem de nível superior do chat
60	`sutram_reply_to_comment`	Comentários	Responde a um comentário de nível superior existente
61	`sutram_request_upload`	Conteúdo	Passo 1 do upload: retorna uma URL S3 PUT pré-assinada
62	`sutram_resolve_comment`	Comentários	Resolve ou reabre uma thread de comentário
63	`sutram_resolve_slug`	Descoberta	Resolve um slug de menção `[[slug]]` para o item que ele aponta
64	`sutram_revert_document_class`	Governança	Reverte uma Classe de Documento para categoria de registros comum
65	`sutram_revoke_class_role`	Governança	Revoga uma concessão de papel de classe (usuário + papel) em uma Classe de Documento
66	`sutram_search_folders`	Tags	Busca pastas por tag (condição única ou condições AND)
67	`sutram_search_items`	Tags	Busca itens de conteúdo por tag
68	`sutram_search_wiki`	Wiki	Busca full-text sobre o conteúdo da wiki (a partir de uma pergunta)
69	`sutram_search_wiki_nodes`	Wiki	Lista/filtra os nós de wiki por nome ou categoria
70	`sutram_send_chat_message`	Chat	Publica uma nova mensagem no chat do projeto
71	`sutram_set_document_class_lifecycle`	Governança	Define o ciclo de vida completo de uma Classe de Documento
72	`sutram_set_folder_tags`	Tags	Define tags chave-valor em uma pasta
73	`sutram_set_item_tags`	Tags	Define tags chave-valor em um item de conteúdo
74	`sutram_set_wiki_relation_labels`	Wiki	Define o vocabulário de relações (rótulos passivo→ativo) da wiki
75	`sutram_sync_wiki_source`	Wiki	Popula o `source_text` de um nó espelho a partir do arquivo do registro
76	`sutram_transition_document`	Governança	Dispara uma transição de ciclo de vida em um documento governado
77	`sutram_undo_checkin`	Versionamento	Desfaz o último checkin, restaurando a versão anterior
78	`sutram_update_record`	Registros	Substitui os metadados de um registro
79	`sutram_update_wiki_node`	Wiki	Atualiza um nó de wiki (nome, categoria, corpo, relações tipadas)
80	`sutram_upload_modified_file`	Versionamento	Substitui o conteúdo do arquivo durante o checkout
81	`sutram_upsert_metadata`	Schema	Cria ou atualiza uma definição de campo de metadados
82	`sutram_upsert_record_category`	Schema	Cria ou atualiza uma categoria de registros

Categorias: Projeto (1) · Descoberta (1) · Pastas (3) · Conteúdo (9) · File Links (4) · Tags (6) · Versionamento (12) · Comentários (6) · Schema (9) · Registros (4) · Wiki (10) · Chat (6) · Governança (11)

As seções abaixo descrevem cada ferramenta em detalhe, organizadas por funcionalidade.

sutram_project_info

Retorna informações sobre o projeto atual.

Parâmetros: Nenhum

Exemplo de resposta:

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

sutram_get_folder

Navega pelo conteúdo de uma pasta (subpastas, arquivos e links). Omita folder_id para listar o conteúdo da raiz.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Não	UUID da pasta. Omita para a raiz.

Exemplo de resposta:

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

Cria uma nova pasta. Suporta a criação de hierarquias aninhadas em uma única chamada.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim*	Nome da pasta (para criar uma única pasta)
`path`	string	Sim*	Caminho separado por barras para criação aninhada (ex.: `"A/B/C"`)
`parent_folder_id`	string	Não	UUID da pasta pai. Omita para o nível raiz.
`tags`	object	Não	Tags chave-valor de formato livre (ex.: `{"patient": "John", "exam_type": "USG"}`). Ao usar `path`, as tags são aplicadas apenas à pasta folha (mais profunda).

*Use name (pasta única) ou path (hierarquia aninhada), não ambos.

Criação aninhada: Ao usar path, pastas intermediárias são criadas automaticamente. Se qualquer pasta no caminho já existir, ela é reutilizada — a operação é idempotente.

Exemplo — pasta única:

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

Exemplo — hierarquia aninhada com tags:

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

Isso cria três pastas em uma chamada e retorna a mais profunda (2024-12-12) com as tags especificadas.

sutram_request_upload

Passo 1 do fluxo de upload direto. Valida o arquivo e retorna uma URL S3 PUT pré-assinada. O arquivo é enviado diretamente ao S3 pelo cliente — nenhum dado passa pelos servidores web do Sutram.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`filename`	string	Sim	Nome do arquivo com extensão (ex.: `report.pdf`)
`file_size`	integer	Sim	Tamanho do arquivo em bytes
`content_type`	string	Não	Tipo MIME. Detectado automaticamente pela extensão se omitido.
`folder_id`	string	Não	UUID da pasta de destino. Omita para a raiz.

Exemplo de resposta:

{
  "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 do fluxo de upload direto. Chame após o arquivo ter sido enviado para a URL pré-assinada. Verifica se o objeto S3 existe, cria o registro do arquivo, atualiza o uso de armazenamento e enfileira compressão se aplicável.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`file_id`	string	Sim	UUID do arquivo de `sutram_request_upload`
`s3_key`	string	Sim	Chave S3 de `sutram_request_upload`
`filename`	string	Sim	Nome original do arquivo com extensão
`content_type`	string	Sim	Tipo MIME do arquivo
`file_size`	integer	Sim	Tamanho do arquivo em bytes
`folder_id`	string	Não	UUID da pasta de destino (deve corresponder à requisição)

Exemplo de resposta:

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

Exemplo completo do fluxo de upload:

# 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

Cria um link web no projeto. O Sutram busca automaticamente o título da página e o favicon a partir da URL.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL da página web (deve ser http ou https)
`name`	string	Não	Nome de exibição. Obtido automaticamente do título da página se omitido.
`folder_id`	string	Não	UUID da pasta de destino. Omita para a raiz.

Exemplo de resposta:

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

Cria um link de vídeo no projeto. Suporta YouTube, Vimeo, DailyMotion, Wistia, Loom e TikTok. Detecta automaticamente a plataforma e extrai o ID do vídeo a partir da URL.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL do vídeo (ex.: `https://www.youtube.com/watch?v=...`)
`name`	string	Não	Nome de exibição. Usa a URL como padrão se omitido.
`folder_id`	string	Não	UUID da pasta de destino. Omita para a raiz.

Exemplo de resposta:

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

Cria um link de áudio no projeto. Suporta Spotify, SoundCloud, Apple Podcasts e outros. Detecta automaticamente a plataforma e extrai o ID do áudio a partir da URL.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL do conteúdo de áudio (ex.: `https://open.spotify.com/track/...`)
`name`	string	Não	Nome de exibição. Usa a URL como padrão se omitido.
`folder_id`	string	Não	UUID da pasta de destino. Omita para a raiz.

Exemplo de resposta:

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

Cria um file link (referência simbólica) para um arquivo existente no projeto. O link aparece como uma referência somente leitura sem duplicar armazenamento ou versionamento. A origem deve ser um arquivo (não um link ou outro file link). Se o arquivo de origem for excluído, todos os seus file links são removidos automaticamente.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`source_content_item_id`	string	Sim	UUID do item de conteúdo do arquivo de origem para vincular
`name`	string	Não	Nome de exibição (usa o nome do arquivo de origem como padrão)
`folder_id`	string	Não	UUID da pasta de destino (omita para a raiz)
`description`	string	Não	Descrição do file link

Exemplo de requisição:

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

Exemplo de resposta:

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

Cria file links em massa para todos os arquivos (ou um subconjunto filtrado) em uma pasta de origem, colocando-os em uma pasta de destino. Pula automaticamente arquivos que já possuem um link na pasta de destino (deduplicação). Ideal para fluxos de trabalho como vincular múltiplos arquivos de exames a uma pasta centralizada de laudos.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`source_folder_id`	string	Sim	UUID da pasta de origem contendo os arquivos a vincular
`target_folder_id`	string	Sim	UUID da pasta de destino onde os file links serão criados
`name_pattern`	string	Não	Filtro de substring (case-insensitive) nos nomes dos arquivos de origem. Apenas arquivos correspondentes são vinculados.
`recursive`	boolean	Não	Incluir arquivos de subpastas da pasta de origem (padrão: false)

Exemplo de requisição:

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

Exemplo de resposta:

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

Dica: Executar o mesmo comando novamente pulará todos os arquivos previamente vinculados ("created": 0, "skipped": 7), tornando seguro re-executar.

sutram_list_file_links_for_source

Lista todos os file links que apontam para um determinado arquivo de origem. Responde à pergunta: "onde este arquivo é referenciado?" Retorna cada link com seu caminho de pasta.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`source_content_item_id`	string	Sim	UUID do item de conteúdo do arquivo de origem

Exemplo de requisição:

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

Exemplo de resposta:

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

Lista todos os file links em uma pasta, enriquecidos com detalhes do arquivo de origem (nome, tipo de conteúdo, tamanho, caminho da pasta). Diferente de sutram_get_folder, este fornece informações completas sobre o arquivo de origem para o qual cada link aponta.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Não	UUID da pasta (omita para a raiz)

Exemplo de requisição:

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

Exemplo de resposta:

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

Obtém detalhes completos de um item de conteúdo por ID. Para arquivos, retorna metadados e uma URL de download pré-assinada. Para links (web, vídeo, áudio, file_link), retorna a URL, informações da plataforma e metadados.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo

Exemplo de resposta (arquivo):

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

Exemplo de resposta (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"
}

Exemplo de resposta (link de vídeo):

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

Exclui um item de conteúdo (arquivo, link web, link de vídeo, link de áudio) ou pasta do projeto.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`item_id`	string	Sim	UUID do item de conteúdo ou pasta
`item_type`	string	Sim	`"content_item"` ou `"folder"`. Use `"content_item"` para qualquer tipo de conteúdo (arquivos, links web, links de vídeo, links de áudio).

sutram_rename

Renomeia um item de conteúdo (arquivo, link web, link de vídeo, link de áudio) ou pasta.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`item_id`	string	Sim	UUID do item de conteúdo ou pasta
`item_type`	string	Sim	`"content_item"` ou `"folder"`. Use `"content_item"` para qualquer tipo de conteúdo (arquivos, links web, links de vídeo, links de áudio).
`new_name`	string	Sim	Novo nome (para arquivos, inclua a extensão)

sutram_move_contents

Move todo o conteúdo (subpastas e arquivos) de uma pasta de origem para uma pasta de destino. A pasta de origem é esvaziada mas não excluída. Conflitos de nome são tratados automaticamente.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`source_folder_id`	string	Sim	UUID da pasta de origem a esvaziar
`target_folder_id`	string	Sim	UUID da pasta de destino para receber o conteúdo

Tratamento de conflitos de nome: Se uma subpasta ou arquivo com o mesmo nome já existir na pasta de destino, o Sutram renomeia automaticamente o item movido adicionando um sufixo numérico: Exams se torna Exams (1), report.pdf se torna report (1).pdf, e assim por diante.

Regras de validação:

Origem e destino devem ser pastas diferentes
O destino não pode ser uma subpasta da origem (previne movimentações circulares)
Ambas as pastas devem existir no projeto atual

Exemplo de resposta:

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

Move um único item de conteúdo (arquivo ou link) para outra pasta. Conflitos de nome são tratados automaticamente.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo a mover
`target_folder_id`	string/null	Não	UUID da pasta de destino (null para a raiz)

Tratamento de conflitos de nome: Se um arquivo com o mesmo nome já existir na pasta de destino, o Sutram renomeia automaticamente o arquivo movido adicionando um sufixo numérico: report.pdf se torna report (1).pdf, e assim por diante.

Exemplo de resposta (sem conflito):

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

Exemplo de resposta (com renomeação):

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

sutram_set_folder_tags

Define tags chave-valor de formato livre em uma pasta. Substitui todas as tags existentes. Envie {} para limpar todas as tags.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Sim	UUID da pasta
`tags`	object	Sim	Tags chave-valor a definir. Envie `{}` para limpar todas as tags.

Limites: Máximo de 50 tags por pasta. Chave com máximo de 100 caracteres, valor com máximo de 500 caracteres.

Semântica: Esta é uma operação PUT — substitui todas as tags existentes. Para adicionar uma tag sem remover as outras, primeiro leia as tags atuais (via sutram_get_folder), mescle suas alterações e então chame sutram_set_folder_tags com o conjunto completo.

Exemplo — definir tags:

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

Exemplo — limpar todas as tags:

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

Exemplo de resposta:

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

sutram_search_folders

Busca pastas por tag. Suporta condição única ou múltiplas condições AND. Toda a correspondência é case-insensitive para chaves e valores. Valores suportam correspondência por substring (ex.: "orto" corresponde a "Ortopedia"). Use folder_id para restringir a busca aos descendentes de uma pasta específica.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`tag_name`	string	Não*	Chave da tag a buscar (modo de condição única). Case-insensitive.
`tag_value`	string	Não	Valor a corresponder (modo de condição única). Correspondência por substring, case-insensitive.
`conditions`	array	Não*	Múltiplas condições AND. Cada objeto tem `key` (obrigatório) e `value` (opcional).
`folder_id`	string	Não	UUID da pasta para delimitar a busca. Busca apenas descendentes desta pasta.

*Use tag_name (condição única) ou conditions (múltiplas condições AND).

Comportamento da busca:

Correspondência de chave: Correspondência exata case-insensitive ("Patient" corresponde a "patient")
Correspondência de valor: Correspondência por substring case-insensitive ("orto" corresponde a "Ortopedia", "joão" corresponde a "João Silva")
Sem valor: Quando o valor é omitido, corresponde a qualquer pasta que tenha a chave independentemente do valor
Múltiplas condições: Todas as condições devem corresponder (lógica AND)

Exemplo — encontrar todas as pastas com tag "patient":

{ "tag_name": "patient" }

Exemplo — encontrar pastas para um paciente específico (correspondência por substring):

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

Isso corresponde a pastas onde a tag "patient" contém "joão" (ex.: "João Silva", "João Pedro").

Exemplo — busca AND com múltiplas condições:

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

Isso retorna apenas pastas que correspondem a ambas as condições.

Exemplo — buscar apenas dentro de uma hierarquia de pastas específica:

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

Exemplo de resposta:

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

Retorna todas as chaves de tag distintas usadas em pastas no projeto. Útil para descobrir quais tags estão disponíveis antes de realizar uma busca. Use folder_id para restringir aos descendentes de uma pasta específica.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Não	UUID da pasta para delimitar. Retorna apenas chaves de descendentes desta pasta.

Exemplo — obter todas as chaves de tag no projeto:

{}

Exemplo — obter chaves de tag dentro de uma hierarquia de pastas:

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

Exemplo de resposta:

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

sutram_set_item_tags

Define tags chave-valor de formato livre em um item de conteúdo. Substitui todas as tags existentes. Envie {} para limpar todas as tags.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo
`tags`	object	Sim	Tags chave-valor a definir. Envie `{}` para limpar todas as tags.

Limites: Máximo de 50 tags por item. Chave com máximo de 100 caracteres, valor com máximo de 500 caracteres.

Semântica: Esta é uma operação PUT — substitui todas as tags existentes. Para adicionar uma tag sem remover as outras, primeiro leia as tags atuais (via sutram_get_item), mescle suas alterações e então chame sutram_set_item_tags com o conjunto completo.

Exemplo — definir tags:

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

Exemplo — limpar todas as tags:

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

Exemplo de resposta:

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

sutram_search_items

Busca itens de conteúdo por tag. Suporta condição única ou múltiplas condições AND. Toda a correspondência é case-insensitive para chaves e valores. Valores suportam correspondência por substring (ex.: "neuro" corresponde a "Neurologia"). Use folder_id para restringir a busca a uma pasta específica, e type para filtrar por tipo de conteúdo.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`tag_name`	string	Não*	Chave da tag a buscar (modo de condição única). Case-insensitive.
`tag_value`	string	Não	Valor a corresponder (modo de condição única). Correspondência por substring, case-insensitive.
`conditions`	array	Não*	Múltiplas condições AND. Cada objeto tem `key` (obrigatório) e `value` (opcional).
`folder_id`	string	Não	UUID da pasta para delimitar a busca.
`type`	string	Não	Filtro de tipo de conteúdo: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

*Use tag_name (condição única) ou conditions (múltiplas condições AND).

Exemplo — encontrar todos os itens com tag "topic":

{ "tag_name": "topic" }

Exemplo — encontrar itens para um tópico específico (correspondência por substring):

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

Exemplo — busca AND com múltiplas condições:

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

Exemplo — buscar apenas links de vídeo em uma pasta específica:

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

Exemplo de resposta:

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

sutram_get_item_tag_keys

Retorna todas as chaves de tag distintas usadas em itens de conteúdo no projeto. Útil para descobrir quais tags estão disponíveis antes de realizar uma busca. Use folder_id para restringir a uma pasta específica, e type para filtrar por tipo de conteúdo.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Não	UUID da pasta para delimitar.
`type`	string	Não	Filtro de tipo de conteúdo: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

Exemplo — obter todas as chaves de tag de conteúdo no projeto:

{}

Exemplo — obter chaves de tag apenas para links de vídeo:

{ "type": "video_link" }

Exemplo de resposta:

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

Versionamento de Arquivos

O Sutram suporta um fluxo completo de versionamento para arquivos via MCP. Isso permite que assistentes de IA habilitem controle de versão, façam checkout de arquivos para edição exclusiva, façam upload de modificações e publiquem versões.

Fluxo de Trabalho

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)

Ferramentas de Versionamento

Ferramenta	Descrição	Permissão
`sutram_enable_versioning`	Converte arquivo de referência para editável (inicia versionamento)	Proprietário, Admin, Membro
`sutram_disable_versioning`	Converte arquivo de volta para referência (para versionamento)	Proprietário, Admin, Membro
`sutram_checkout_file`	Faz checkout do arquivo para edição exclusiva	Proprietário, Admin, Membro
`sutram_checkin_file`	Libera o bloqueio de checkout	Usuário do checkout
`sutram_cancel_checkout`	Cancela o checkout sem alterações	Usuário do checkout
`sutram_force_release_lock`	Libera forçadamente o checkout de outro usuário	Proprietário, Admin
`sutram_publish_version`	Publica um arquivo rascunho, criando um snapshot de versão	Proprietário, Admin, Membro
`sutram_create_new_version`	Inicia nova versão a partir de arquivo publicado	Proprietário, Admin, Membro
`sutram_undo_checkin`	Desfaz o último checkin, restaura a versão anterior	Usuário do último checkin
`sutram_list_versions`	Lista todas as versões publicadas com URLs de download	Qualquer participante
`sutram_upload_modified_file`	Substitui o conteúdo do arquivo durante o checkout	Usuário do checkout

Parâmetros

Todas as ferramentas de versionamento requerem content_item_id (UUID do item de conteúdo).

sutram_upload_modified_file adicionalmente requer:

Parâmetro	Tipo	Descrição
`s3_key`	string	Chave S3 de `sutram_request_upload`
`file_name`	string	Nome do arquivo com extensão
`file_size`	integer	Tamanho do arquivo em bytes
`content_type`	string	Tipo MIME

Exemplo: Fluxo Completo de 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 }

Categorias de Registros e Registros

O Sutram suporta registros estruturados com schemas de metadados e slugs gerados automaticamente. Isso permite que assistentes de IA definam campos de metadados, criem categorias de registros e gerenciem registros programaticamente.

Requisito de plano: As ferramentas de gerenciamento de registros e schema requerem um plano com o recurso Records habilitado (Pro ou superior). As ferramentas somente leitura (sutram_get_metadata_definitions, sutram_get_record_categories, sutram_get_record_category_detail) estão disponíveis em todos os planos.

Conceitos

Definições de metadados — Schemas de campo que definem os tipos, rótulos e valores permitidos para campos de metadados (ex.: "language" como enum com valores "PT", "EN", "ES").
Categorias de registros — Templates que definem quais campos de metadados um registro usa, sua ordem, como a base numérica é calculada (computed_from) e como o slug (nome do registro) é composto (slug_from).
Registros — Pastas criadas com uma categoria, metadados validados e um slug gerado automaticamente.

Geração de Slug

Registros possuem um slug gerado automaticamente (usado como nome do registro). O slug é construído em duas etapas:

Base numérica — Determinada pelas entradas computed_from em uma tag de metadados computada. Isso define quais valores de campo formam a chave de unicidade para numeração sequencial.
Composição do slug — Determinada pelas entradas slug_from na categoria. Isso define quais valores de campo (incluindo a tag computada) compõem o slug final.

Sem slug_from (compatível com versões anteriores): slug = number_base + separator + sequence_number (ex.: 0100-200-001).

Com slug_from: slug é composto a partir dos campos referenciados em ordem (ex.: MD-3010.95-0000-000-SWA-001).

Ferramentas de Schema

Ferramenta	Descrição	Permissão
`sutram_get_metadata_definitions`	Lista todas as definições de metadados	Qualquer participante
`sutram_get_record_categories`	Lista todas as categorias de registros	Qualquer participante
`sutram_get_record_category_detail`	Categoria com metadados resolvidos (rótulos, tipos, valores permitidos)	Qualquer participante
`sutram_upsert_metadata`	Cria ou atualiza uma definição de metadados	Proprietário, Admin
`sutram_delete_metadata`	Exclui uma definição de metadados (falha se estiver em uso)	Proprietário, Admin
`sutram_add_enum_values`	Adiciona valores a uma definição enum (mescla, deduplica, ordena)	Proprietário, Admin
`sutram_remove_enum_values`	Remove valores de uma definição enum por código	Proprietário, Admin
`sutram_upsert_record_category`	Cria ou atualiza uma categoria de registros	Proprietário, Admin
`sutram_delete_record_category`	Exclui uma categoria de registros	Proprietário, Admin

Ferramentas CRUD de Registros

Ferramenta	Descrição	Permissão
`sutram_create_record`	Cria um registro com categoria, metadados e slug gerado automaticamente	Proprietário, Admin, Membro
`sutram_update_record`	Substitui todos os metadados de um registro (recalcula o slug se necessário)	Proprietário, Admin, Membro
`sutram_patch_record_metadata`	Atualiza campos específicos de um registro (merge), preservando os demais	Proprietário, Admin, Membro
`sutram_delete_record`	Exclui um registro e todo seu conteúdo recursivamente	Proprietário, Admin, Membro

sutram_get_metadata_definitions

Retorna todas as definições de metadados do projeto. Cada definição possui uma chave e propriedades: rótulo, tipo (text, enum, boolean, date, computed) e opcionalmente values, depends_on, values_map.

Parâmetros: Nenhum

sutram_get_record_categories

Retorna todas as categorias de registros do projeto. Cada categoria define quais campos de metadados um registro usa, configuração de slug e ordenação.

Parâmetros: Nenhum

sutram_get_record_category_detail

Retorna uma categoria de registros com metadados completamente resolvidos (rótulos, tipos, valores permitidos a partir das definições). Use isso para entender quais campos são necessários antes de criar um registro.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	ID da categoria de registros

sutram_upsert_metadata

Cria ou atualiza uma definição de metadados (schema de campo). Para tipos enum, forneça o array completo de values. Para enums grandes, prefira sutram_add_enum_values para adições incrementais.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave única (snake_case, ex.: `"specialty"`)
`definition`	object	Sim	Definição com `label`, `type` e campos opcionais

Tipos suportados: text, enum, boolean, date, computed.

Exemplo — criar um enum simples:

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

sutram_delete_metadata

Exclui uma definição de metadados. Falha se a definição estiver atualmente em uso por alguma categoria de registros.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave da definição a excluir

sutram_add_enum_values

Adiciona valores a uma definição de metadados enum existente. Novos valores são mesclados com os existentes — duplicatas (por código) são ignoradas. Os valores são ordenados por código após a mesclagem. Use isso em vez de sutram_upsert_metadata ao trabalhar com enums grandes para evitar enviar o array inteiro de valores.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave da definição enum
`values`	array	Sim	Array de objetos `{label, code}` a adicionar

Exemplo — adicionar valores a um enum existente com mais de 800 itens:

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

Exemplo de resposta:

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

sutram_remove_enum_values

Remove valores de uma definição de metadados enum existente pelos seus códigos.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave da definição enum
`codes`	array	Sim	Array de strings de código a remover

Exemplo:

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

Exemplo de resposta:

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

sutram_upsert_record_category

Cria ou atualiza uma categoria de registros. Os metadados devem referenciar definições existentes. Use computed_from em uma entrada de metadados para definir a base numérica (unicidade). Use slug_from no nível da categoria para definir como o slug (nome do registro) é composto.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	ID único da categoria (snake_case)
`category`	object	Sim	Definição da categoria (veja campos abaixo)

Campos da categoria:

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome de exibição da categoria
`metadata`	array	Sim	Array de referências a campos de metadados (veja abaixo)
`slug_separator`	string	Não	Separador entre partes do slug (padrão: `"-"`)
`slug_from`	array	Não	Define a composição do slug. Cada entrada tem `key` e `use` (`"code"` ou `"label"`). Se omitido, slug = number_base + separator + sequence_number

Campos de entrada de metadados:

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave de uma definição de metadados existente
`required`	boolean	Não	Se este campo é obrigatório (padrão: false)
`order`	integer	Não	Ordem de exibição (base 0)
`computed_from`	array	Não	Apenas para tags computadas. Define a base numérica. Cada entrada tem `key` e `use` (`"code"` ou `"label"`)
`sequence_digits`	integer	Não	Apenas para tags computadas. Dígitos para o número sequencial (2-4, padrão: 2)

Exemplo — categoria com slug_from (estilo 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" }
    ]
  }
}

Neste exemplo:

Base numérica (de computed_from): MD-3010.95-0000-000 — determina a unicidade sequencial
Número codificado: 001 (próxima sequência disponível)
Slug (de slug_from): MD-3010.95-0000-000-SWA-001 — inclui document_origin + sequência

Exemplo — categoria simples sem slug_from (compatível com versões anteriores):

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

Sem slug_from, o slug é automaticamente: {number_base}{separator}{sequence} (ex.: CARDIO-001).

sutram_delete_record_category

Exclui uma categoria de registros.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	ID da categoria a excluir

sutram_create_record

Cria um registro com uma categoria, metadados validados e slug gerado automaticamente. O slug é calculado a partir da definição slug_from da categoria, ou de computed_from (base numérica) + separador + número sequencial. Use sutram_get_record_category_detail primeiro para ver os campos obrigatórios.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	ID da categoria de registros
`metadata`	object	Sim	Pares chave-valor correspondentes aos campos de metadados da categoria
`parent_folder_id`	string	Não	UUID da pasta pai (omita para a raiz)
`name`	string	Não	Nome personalizado (usa o slug gerado automaticamente como padrão)

Exemplo:

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

A resposta inclui o slug calculado e o número sequencial:

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

Substitui todo o mapa de metadados de um registro pelo objeto informado. Recalcula a base numérica e o slug quando campos referenciados por computed_from ou slug_from são alterados. Para mudar apenas um campo sem reescrever os demais, use sutram_patch_record_metadata.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`record_id`	string	Sim	UUID do registro (pasta)
`metadata`	object	Sim	Mapa completo de metadados (substitui o anterior)
`name`	string	Não	Novo nome (opcional)

sutram_patch_record_metadata

Atualiza um ou mais campos de metadados de um registro fazendo merge com os metadados existentes (ao contrário de sutram_update_record, que substitui o mapa inteiro). Informe apenas as chaves que quer alterar; as demais permanecem intactas. Defina uma chave como null para removê-la. Se você alterar um campo que não compõe o slug, o slug e o número sequencial permanecem inalterados; se alterar um campo que compõe o slug, ele é recalculado como em sutram_update_record.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`record_id`	string	Sim	UUID do registro (pasta)
`metadata`	object	Sim	Apenas as chaves a definir ou remover (`null` remove), ex.: `{"status": "approved"}`
`name`	string	Não	Novo nome (opcional; por padrão o nome acompanha o slug recalculado só se já o espelhava)

Exemplo — alterar apenas um campo:

{
  "record_id": "abc-123",
  "metadata": { "status": "approved" }
}

sutram_delete_record

Exclui um registro e todo o seu conteúdo (subpastas e arquivos) recursivamente. Esta ação não pode ser desfeita.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`record_id`	string	Sim	UUID do registro (pasta) a excluir

Exemplo: Fluxo Completo de Registros

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

Observe como:

A base numérica PT-0100 (de computed_from: language + area) determina a unicidade sequencial
O slug PT-0100-SWA-001 (de slug_from) inclui origin + o número sequencial
O segundo registro recebe a sequência 002 porque compartilha a mesma base numérica PT-0100

Wiki e Grafo de Conhecimento

A Wiki do Sutram é uma camada de grafo de conhecimento sobre o projeto. Além de arquivos e registros, você cria nós de wiki (entidades, conceitos ou páginas de síntese) e os conecta por menções [[slug]], formando uma rede navegável de backlinks e relações tipadas. É a memória estruturada que permite a uma IA responder perguntas ancorada nas fontes do próprio projeto.

Conceitos

Nó de wiki (WikiNode) — Uma entidade referenciável abstrata (um conceito, tema ou página de síntese) para a qual menções [[slug]] apontam. Não é pasta nem arquivo: tem slug, categoria opcional, metadados e um corpo markdown opcional.
Menção [[slug]] — Referência inline, dentro do markdown de um nó, a outro item pelo seu slug. Uma menção cujo alvo ainda não existe fica pendente até ele ser criado.
Backlink — O inverso da menção: todos os itens que apontam para um alvo (o painel "Mencionado em (N)").
Relação tipada — Uma menção com rótulo (ex.: revoga, altera, regulamenta) que dá semântica à aresta do grafo.
Síntese × texto integral — O content_markdown é a síntese curada do nó; o source_text é o texto integral do documento espelhado, indexado pela busca full-text (sutram_search_wiki).

Fluxo de resposta (answer flow)

Padrão de uso da wiki para responder a uma pergunta:

1. Buscar      →  sutram_search_wiki(pergunta)        // full-text sobre o conteúdo
2. Ler         →  sutram_get_wiki_node(slug | id)     // síntese + texto integral
3. Navegar     →  sutram_get_backlinks / sutram_get_outgoing_mentions
4. Sintetizar a resposta, ancorada nas fontes encontradas

Ferramentas de Wiki

Ferramenta	Descrição
`sutram_create_wiki_node`	Cria um nó de wiki (faz fuzzy-match do nome para evitar duplicatas)
`sutram_update_wiki_node`	Atualiza nome, categoria, metadados, corpo ou relações tipadas de um nó
`sutram_get_wiki_node`	Retorna um nó por `id` ou `slug`, com síntese e texto integral
`sutram_delete_wiki_node`	Soft-delete de um nó (menções voltam a ficar pendentes) — confirme antes
`sutram_search_wiki`	Busca full-text sobre nome + síntese + texto integral (a partir de uma pergunta)
`sutram_search_wiki_nodes`	Lista/filtra nós por substring de nome ou por categoria
`sutram_sync_wiki_source`	Popula o `source_text` de um nó espelho a partir do arquivo do registro
`sutram_set_wiki_relation_labels`	Define o vocabulário de relações (rótulos passivo→ativo) do projeto
`sutram_get_outgoing_mentions`	Lista as menções `[[slug]]` que saem de uma origem (resolvidas/pendentes)
`sutram_get_backlinks`	Lista os backlinks de um item (quem o menciona)
`sutram_resolve_slug`	Resolve um slug de menção para o item que ele aponta (descoberta)

As operações de leitura da wiki estão disponíveis aos membros do projeto; as de escrita seguem as funções de edição (ver Permissões).

sutram_create_wiki_node

Cria um WikiNode — uma entidade referenciável (conceito, tema ou página de síntese) que menções [[slug]] apontam. Antes de criar, faz fuzzy-match do nome contra o catálogo do projeto: se já existir um nó próximo o bastante, ele é retornado (status matched) em vez de criar uma duplicata.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome de exibição (ex.: `"Estrutura de pastas i18n"`)
`slug`	string	Não	Slug explícito (gerado a partir do nome se omitido)
`category`	string	Não	Id da categoria do tipo de nó
`content_markdown`	string	Não	Corpo markdown (a síntese curada). Omita para um nó stub.
`source_text`	string	Não	Texto integral do documento espelhado, indexado pela busca
`metadata`	object	Não	Atributos de formato livre
`created_autonomously`	boolean	Não	Marca o nó como criado pela IA (padrão false)

sutram_update_wiki_node

Atualiza nome, categoria, metadados ou corpo de um nó. O slug é estável e não é regenerado ao renomear. O parâmetro mentions define arestas tipadas de saída que sobrescrevem as menções [[ ]] extraídas do corpo.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	UUID do nó
`name`	string	Não	Novo nome de exibição
`category`	string	Não	Novo id de categoria
`content_markdown`	string	Não	Novo corpo markdown
`source_text`	string	Não	Novo texto integral
`metadata`	object	Não	Mapa de metadados (substitui o anterior)
`mentions`	array	Não	Arestas tipadas: `[{slug, label}]` (ex.: `label: "revoga"`)

sutram_get_wiki_node

Retorna um nó por id ou slug (informe exatamente um), incluindo categoria, metadados, síntese curada e — para nós que espelham um registro — o texto integral do documento, inline no markdown (seção "📄 Texto integral").

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim*	UUID do nó
`slug`	string	Sim*	Slug do nó

*Informe id ou slug.

sutram_delete_wiki_node

Destrutivo. Soft-delete de um nó; menções que apontavam para ele voltam a ficar pendentes. Confirme com o usuário antes de chamar.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	UUID do nó

sutram_search_wiki

Busca full-text sobre o conteúdo da wiki — a forma de encontrar material a partir de uma pergunta quando você não sabe slugs nem ids. Ranqueia nós por aderência de nome, síntese e texto integral à query (stemming em português) e devolve um trecho destacado por resultado.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	Consulta livre. Suporta frases entre aspas, exclusão com `-` e `or`.
`limit`	integer	Não	Máximo de resultados (padrão 10, máx 50)

sutram_search_wiki_nodes

Lista os nós do projeto, opcionalmente filtrados por substring de nome (query) ou por category. Use para navegar o catálogo de entidades/conceitos ou encontrar um nó antes de linká-lo.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Não	Filtro por substring de nome
`category`	string	Não	Filtro por id de categoria
`limit`	integer	Não	Máximo de resultados (padrão 50)

sutram_sync_wiki_source

Popula o source_text (substrato da busca full-text) de um nó espelho a partir do markdown extraído do registro vinculado (padrão texto_full.md), lido no armazenamento. Use após sutram_create_wiki_node quando o corpo do documento é grande demais para passar inline. Idempotente.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim*	UUID do nó
`slug`	string	Sim*	Slug do nó
`record_folder_id`	string	Não	UUID do registro-fonte (padrão: `metadata.record_folder_id` do nó)
`filename`	string	Não	Nome do arquivo no registro (padrão `texto_full.md`)

*Informe id ou slug.

sutram_set_wiki_relation_labels

Define o vocabulário de relações do projeto: um mapa de rótulos passivo→ativo (ex.: {"regulamentado_por": "regulamenta", "revogado_por": "revoga"}). O grafo colapsa arestas inversas para a voz ativa; a página do nó renderiza os backlinks na voz passiva. Chame uma vez por projeto após definir mentions tipadas. Mescla com o mapa existente.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`labels`	object	Sim	Mapa rótulo passivo → rótulo ativo

sutram_get_outgoing_mentions

Retorna as menções de saída de uma origem — os [[slug]] que ela aponta, cada um marcado como resolvido ou pendente. Identifique a origem por slug ou por id + kind.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`slug`	string	Sim*	Slug da origem
`id`	string	Sim*	UUID da origem (com `kind`)
`kind`	string	Não	Tipo da origem: `wiki_node` \| `content_item`

*Informe slug ou id + kind.

sutram_get_backlinks

Retorna os backlinks de um item — as origens cujo markdown o menciona via [[slug]] (painel "Mencionado em (N)"). Identifique o alvo por slug (resolvido automaticamente) ou por id + kind.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`slug`	string	Sim*	Slug do alvo
`id`	string	Sim*	UUID do alvo (com `kind`)
`kind`	string	Não	Tipo do alvo: `wiki_node` \| `content_item` \| `folder`

*Informe slug ou id + kind.

sutram_resolve_slug

Resolve um slug (o token dentro de uma menção [[slug]]) para o item que ele aponta no projeto, retornando seu tipo (content_item ou folder), id e nome. Um slug não resolvido indica uma menção pendente — o alvo ainda não existe.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`slug`	string	Sim	Slug a resolver (ex.: `"estrutura-de-pastas-i18n"`)

Exemplo: Fluxo de Wiki

// 1. Encontrar material a partir de uma pergunta
→ sutram_search_wiki { "query": "estrutura de pastas multilíngue" }

// 2. Ler o nó mais relevante por completo (síntese + texto integral)
→ sutram_get_wiki_node { "slug": "estrutura-de-pastas-i18n" }

// 3. Ver em todos os lugares onde ele é referenciado
→ sutram_get_backlinks { "slug": "estrutura-de-pastas-i18n" }

// 4. Auditar as menções de saída (quais resolvem, quais estão pendentes)
→ sutram_get_outgoing_mentions { "slug": "estrutura-de-pastas-i18n" }

Classes de Documentos e Governança

As Classes de Documentos são a camada de governança formal do Sutram: transformam uma categoria de registros comum em um fluxo governado, com estados de ciclo de vida, papéis por estado, visibilidade need-to-know e trilha de auditoria de cada transição. É o mecanismo para documentos que exigem aprovação formal (submeter → revisar → aprovar) e confidencialidade por estágio.

Requisito de plano: As Classes de Documentos são um recurso do plano Max.

Conceitos

Classe de Documento — Uma categoria de registros "graduada" para um fluxo governado. Define estados, papéis, permissões por estado (state_access) e transições.
Documento governado — Um registro que pertence a uma Classe; existe como uma família com uma ou mais versões, cada uma em um estado do ciclo de vida.
Ciclo de vida (lifecycle) — Conjunto de states (um inicial, opcionalmente terminais), roles, actions (transições from → to com papéis permitidos) e state_access (read/write por papel em cada estado).
Need-to-know — Cada estado revela o documento apenas aos papéis com acesso de leitura naquele estado; um par (estado, papel) ausente em state_access significa sem acesso.
Eixo de versão — Classes versionadas têm um eixo (ex.: rev: A, B, C); novas revisões nascem em um estado de entrada.
Concessão (grant) — Um par (usuário, papel de classe). Um usuário pode ter múltiplas concessões na mesma Classe (ex.: Author com escopo + Viewer sem escopo); os efeitos se combinam (acesso = o melhor entre as concessões que casam).
Escopo por metadado — Restrição opcional de uma concessão: o papel só vale onde o metadado do documento casa com o escopo; fora dele é como se o usuário não tivesse o papel (need-to-know — o documento nem fica visível). O escopo é um OR de grupos, cada grupo um AND de condições sobre metadados enum/boolean; valores de enum são os rótulos, e o valor especial "" casa "sem valor" (chave ausente/vazia).

Ferramentas de Governança

Ferramenta	Descrição
`sutram_list_document_classes`	Lista as Classes de Documento acessíveis (com estatísticas para owner/admin)
`sutram_list_governed_documents`	Lista os documentos de uma Classe (respeita need-to-know; filtros por estado/tag)
`sutram_graduate_document_class`	Gradua uma categoria de registros para Classe governada (preset autor→revisor→aprovador)
`sutram_set_document_class_lifecycle`	Define o ciclo de vida completo de uma Classe (read-modify-write)
`sutram_revert_document_class`	Reverte uma Classe para categoria comum (bloqueado se ainda houver documentos)
`sutram_create_document`	Cria um documento governado (família + 1ª versão) em um estado de entrada
`sutram_create_documents`	Cria em lote vários documentos da mesma Classe (suporta `dry_run`)
`sutram_create_document_version`	Cria uma nova revisão de um documento governado
`sutram_transition_document`	Dispara uma transição (submeter/aprovar/rejeitar) em uma versão
`sutram_list_class_grants`	Lista as concessões (usuário → papel de classe, com escopo) de uma Classe
`sutram_grant_class_role`	Concede um papel de classe a um membro ativo (por email), com escopo opcional
`sutram_revoke_class_role`	Revoga uma concessão (usuário + papel) em uma Classe

Quem pode ler, escrever e disparar cada transição é determinado pela matriz papel × estado definida na própria Classe. Graduar/reverter classes, editar o ciclo de vida e administrar concessões são operações de proprietário e administrador (manage_record_categories), no plano Max.

sutram_list_document_classes

Lista as Classes de Documento que você acessa. Proprietário/admin veem todas as classes governadas (com estatísticas de volume); membro/visualizador veem apenas as classes onde têm papel. Cada item traz uid, category_id, nome, seu papel e doc_count. É o ponto de entrada antes de sutram_list_governed_documents.

Parâmetros: Nenhum

sutram_list_governed_documents

Lista os documentos governados de uma Classe (pelo seu uid). Respeita need-to-know: só retorna documentos em estados que você pode ler. Suporta filtro por estado, condições de tag, modo de versão e paginação.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_uid`	string	Sim	UUID imutável da Classe (de `sutram_list_document_classes`)
`states`	array	Não	Ids de estado a incluir (interseção com os que você pode ler)
`tag_conditions`	array	Não	Filtros `{key, value}` (AND) sobre os metadados da versão
`all_versions`	boolean	Não	false (padrão) = uma linha por família; true = uma por versão
`page`	integer	Não	Página (padrão 1)
`per_page`	integer	Não	Tamanho da página (padrão 50, máx 200)

sutram_graduate_document_class

Gradua uma categoria de registros comum para Classe de Documento governada (plano Max), aplicando o preset padrão (autor → revisor → aprovador), totalmente editável depois com sutram_set_document_class_lifecycle.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	Id da categoria de registros a graduar

sutram_set_document_class_lifecycle

Substitui todo o ciclo de vida de uma Classe — a ferramenta única para governança: estados, papéis, permissões por estado (state_access), transições (actions), eixo de versão e exibição. Read-modify-write: chame sutram_get_record_category_detail primeiro (ele retorna a categoria com o lifecycle), altere o que precisar e reenvie o objeto inteiro.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	Id da Classe de Documento
`lifecycle`	object	Sim	Objeto de ciclo de vida completo (substitui o existente)

Estrutura do lifecycle:

states: [{id, label, color, order, initial?, terminal?}] — exatamente um initial.
roles: [{id, label}]
actions: [{id, label, from:[state], to, allowed_roles:[role], requires_note?}] — from:["*"] = qualquer estado.
state_access: {estado: {papel: "read" | "write"}} — um par ausente = sem acesso.

sutram_revert_document_class

Reverte uma Classe de Documento para categoria de registros comum, removendo a governança (lifecycle + atribuições papel↔usuário). Bloqueado enquanto a Classe ainda tiver documentos governados — exclua-os antes. Não apaga conteúdo; só remove a camada de governança de uma classe vazia.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	Id da Classe a reverter

sutram_create_document

Cria um documento governado (família + primeira versão), em um estado de entrada, com identidade computada (slug). Use para a primeira versão de uma classe versionada e para todo documento de uma classe não versionada. Chame sutram_get_record_category_detail antes para conhecer os campos obrigatórios e o eixo de versão.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	Id da Classe de Documento
`metadata`	object	Sim	Metadados tipados que formam o documento/slug
`version_values`	object	Não	Valores do eixo de versão (ex.: `{"rev": "A"}`) — exigido se a classe tem eixo
`lifecycle_state`	string	Não	Estado de entrada (padrão: estado inicial da classe)
`name`	string	Não	Nome custom (padrão: slug computado)

sutram_create_documents

Cria em lote vários documentos governados da mesma Classe numa única chamada (bootstrap / registro mestre). Cada entrada é a primeira versão de uma família; a sequência de slug avança corretamente. Recomendado: chame com dry_run: true para pré-visualizar, depois dry_run: false para aplicar. Idempotente por slug em classes de slug determinístico.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	Id da Classe (compartilhado por todas as entradas)
`documents`	array	Sim	Documentos a criar (máx 200), cada um `{metadata, version_values?, lifecycle_state?, name?}`
`dry_run`	boolean	Não	Apenas prévia — resolve identidades sem persistir (padrão false)

sutram_create_document_version

Cria uma nova revisão de um documento governado a partir da versão atual: um irmão flutuante com nova revisão, em estado de entrada, herdando a identidade (slug). Use para emitir uma nova revisão (ex.: revisão B de um desenho aprovado). A classe precisa ter eixo de versão e o estado atual precisa permitir versionamento.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`document_id`	string	Sim	UUID da família do documento governado
`version_values`	object	Não	Valores do eixo de versão (ex.: `{"rev": "B"}`) — exigido se há eixo
`copy_forward`	boolean	Não	Copia os arquivos da versão atual para a nova (padrão true)

sutram_transition_document

Dispara uma transição de ciclo de vida em uma versão de documento governado (ex.: submeter, aprovar, rejeitar). Respeita a matriz "quem-pode-disparar" (papel × estado); algumas transições exigem nota. Registra a mudança na trilha de auditoria.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`version_id`	string	Sim	Id da versão a transicionar (de `sutram_list_governed_documents`)
`action`	string	Sim	Id da ação de ciclo de vida a disparar (definida na classe)
`note`	string	Não	Justificativa — exigida por transições que demandam nota

Concessões de papel de classe (novo na v1.62)

Quem tem qual papel em uma Classe é armazenado como concessões — uma linha por (usuário, papel), cada uma com um escopo por metadado opcional. Um usuário acumula concessões na mesma Classe e os efeitos se combinam. Três ferramentas granulares administram as concessões (deliberadamente não replace-all: substituir o conjunto inteiro revogaria acesso de pessoas por omissão). As três são operações de proprietário/administrador; conceder e revogar exigem também o plano Max. Conceder e revogar mudam quem pode ver e agir sobre documentos governados — um assistente só deve chamá-las sob instrução explícita do usuário nomeando a pessoa e o papel. A gestão de membros do projeto (convidar usuários) continua sendo uma operação da interface web; conceder um papel de classe a um membro ativo existente é a fronteira.

Toda concessão, revogação e mudança de escopo é registrada na trilha de auditoria (document_class.role_granted / role_revoked / role_scope_changed).

sutram_list_class_grants

Lista as concessões de uma Classe de Documento: email e nome do membro, papel (id + rótulo), escopo, quem concedeu e quando.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_uid`	string	Sim	UUID imutável da Classe (de `sutram_list_document_classes`); o `category_id` textual é aceito como alias

sutram_grant_class_role

Concede um papel de classe a um membro ativo do projeto (por email), opcionalmente restrito por um escopo de metadado. Idempotente: re-conceder um par (usuário, papel) existente só atualiza o escopo — e apenas quando scope é passado explicitamente (omitido = o escopo existente é preservado; null explícito = limpa, o papel passa a valer para a classe inteira). O escopo é validado contra as definições de metadado da categoria antes de qualquer escrita.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_uid`	string	Sim	UUID imutável da Classe (`category_id` aceito como alias)
`user_email`	string	Sim	Email de um membro ativo do projeto
`role_id`	string	Sim	Id do papel de classe (do `roles[]` do ciclo de vida)
`scope`	object \| null	Não	Escopo por metadado: `{"groups": [[{"key": "...", "values": ["..."]}]]}` — OR de grupos, cada um um AND de condições sobre metadados enum/boolean; `""` casa "sem valor"

sutram_revoke_class_role

Revoga uma concessão (usuário + papel de classe) em uma Classe de Documento. O usuário mantém os demais papéis que tiver na Classe.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_uid`	string	Sim	UUID imutável da Classe (`category_id` aceito como alias)
`user_email`	string	Sim	Email do titular da concessão
`role_id`	string	Sim	Id do papel de classe a revogar

Exemplo: Concessão com Escopo

// Ana revisa apenas documentos de Engenharia Civil; o resto fica invisível para ela
→ sutram_grant_class_role {
    "category_uid": "cls-1",
    "user_email": "ana@exemplo.com",
    "role_id": "reviewer",
    "scope": { "groups": [[ { "key": "disciplina", "values": ["Engenharia Civil"] } ]] }
  }

// Auditar quem tem o quê
→ sutram_list_class_grants { "category_uid": "cls-1" }

Exemplo: Fluxo de Governança

// 1. Listar as Classes de Documento governadas
→ sutram_list_document_classes

// 2. Listar os documentos de uma Classe, filtrando por estado
→ sutram_list_governed_documents { "category_uid": "cls-1", "states": ["em_revisao"] }

// 3. Aprovar uma versão, com justificativa
→ sutram_transition_document {
    "version_id": "ver-9",
    "action": "aprovar",
    "note": "Conforme revisão técnica."
  }

Comentários em Documentos

Assistentes de IA podem listar, criar, responder, resolver e excluir comentários em arquivos do projeto. Comentários criados via MCP aparecem em tempo real na interface web e vice-versa, graças à transmissão PubSub.

Restrição de tipo de posição: Via MCP, a IA pode criar apenas comentários file_level (comentário no arquivo inteiro) ou markdown (ancorado a texto em arquivos markdown). Tipos de posição que requerem coordenadas da GUI (pdf_page, aps_3d, aps_2d, image) podem ser lidos mas não criados via MCP.

Ferramentas de Comentários

Ferramenta	Descrição	Permissão
`sutram_list_comments`	Lista todos os comentários de nível superior em um item de conteúdo	Qualquer participante
`sutram_get_comment_thread`	Obtém um comentário com sua thread completa de respostas	Qualquer participante
`sutram_create_comment`	Cria um comentário no nível do arquivo ou em markdown	Qualquer participante
`sutram_reply_to_comment`	Responde a um comentário de nível superior	Qualquer participante
`sutram_resolve_comment`	Resolve ou reabre uma thread de comentário	Qualquer participante
`sutram_delete_comment`	Exclui um comentário e todas as suas respostas	Autor, Proprietário ou Admin

sutram_list_comments

Lista todos os comentários de nível superior em um item de conteúdo. Retorna conteúdo do comentário, autor, tipo de posição, status de resolução e contagem de respostas.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo
`include_resolved`	boolean	Não	Se deve incluir comentários resolvidos (padrão: true)

Exemplo:

{
  "content_item_id": "abc-123"
}

Resposta:

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

Obtém um único comentário com sua thread completa de respostas, status de resolução e detalhes do autor.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`comment_id`	string	Sim	UUID do comentário

Resposta:

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

Cria um comentário em um item de conteúdo. A IA pode criar comentários file_level (padrão) ou markdown.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo
`content`	string	Sim	Texto do comentário
`position_type`	string	Não	`"file_level"` (padrão) ou `"markdown"`
`text_anchor`	object	Não	Para markdown: `{exact_text, prefix, suffix}`
`original_text_snippet`	string	Não	Para markdown: o trecho de texto selecionado

Exemplo — comentário no nível do arquivo:

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

Exemplo — comentário markdown ancorado a texto:

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

Responde a um comentário de nível superior existente. Respostas não podem ser aninhadas (sem resposta-de-resposta).

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`comment_id`	string	Sim	UUID do comentário de nível superior
`content`	string	Sim	Texto da resposta

Exemplo:

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

sutram_resolve_comment

Resolve ou reabre uma thread de comentário. Comentários resolvidos indicam que o problema foi tratado.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`comment_id`	string	Sim	UUID do comentário
`action`	string	Sim	`"resolve"` ou `"reopen"`

Exemplo:

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

sutram_delete_comment

Exclui um comentário e todas as suas respostas. Apenas o autor do comentário ou o proprietário/admin do projeto pode excluir.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`comment_id`	string	Sim	UUID do comentário

Exemplo: Fluxo Completo de Comentários

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

Todas as alterações de comentários são transmitidas em tempo real para os usuários que estão visualizando o mesmo documento na interface web.

Chat do Projeto

O chat do projeto é um feed de mensagens humano-a-humano, de âmbito do projeto — distinto dos comentários, que ficam ancorados a um documento. Via MCP, a IA pode ler o histórico, verificar não lidas e publicar mensagens.

Aviso — mensagens são externas (outward-facing): sutram_send_chat_message e sutram_reply_to_chat_message são visíveis a outros membros em tempo real e disparam notificação push. Confirme com o usuário antes de publicar em nome dele.

Ferramentas de Chat

Ferramenta	Descrição
`sutram_list_chat_messages`	Lista as mensagens do chat (mais antigas→recentes; busca e paginação)
`sutram_get_chat_thread`	Obtém uma mensagem com sua thread de respostas (um nível)
`sutram_send_chat_message`	Publica uma nova mensagem (texto e/ou anexo de um item do projeto)
`sutram_reply_to_chat_message`	Responde a uma mensagem de nível superior
`sutram_get_chat_unread_count`	Retorna quantas mensagens de outros membros ainda não foram lidas
`sutram_mark_chat_visited`	Marca o chat como lido (zera o contador de não lidas)

sutram_list_chat_messages

Lista mensagens do chat do projeto, das mais antigas para as mais recentes, excluindo as excluídas. Suporta paginação (before_id) e busca por texto (conteúdo ou autor).

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`limit`	integer	Não	Máximo de mensagens (padrão 20, máx 100)
`before_id`	string	Não	Retorna mensagens anteriores a esta (cursor de paginação)
`search`	string	Não	Filtro por texto no conteúdo ou no nome/email do autor

sutram_get_chat_thread

Obtém uma mensagem com sua thread de respostas (um nível). Se a mensagem informada for uma resposta, retorna a thread do pai.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`message_id`	string	Sim	UUID de qualquer mensagem da thread

sutram_send_chat_message

Externa. Publica uma nova mensagem no chat do projeto como o usuário autenticado; outros membros a veem em tempo real e recebem notificação push. Informe content (texto) e/ou anexe um arquivo/link do projeto via content_item_id.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content`	string	Sim*	Texto da mensagem (máx 5000 caracteres)
`content_item_id`	string	Não	UUID de um arquivo/link do projeto a anexar

*content é obrigatório, salvo se content_item_id for informado.

sutram_reply_to_chat_message

Externa. Responde a uma mensagem de nível superior (threading de um nível); o autor original e outros membros são notificados. Você não pode responder à própria mensagem, a uma resposta, nem a uma mensagem excluída.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`message_id`	string	Sim	UUID da mensagem de nível superior respondida
`content`	string	Sim*	Texto da resposta (máx 5000 caracteres)
`content_item_id`	string	Não	UUID de um arquivo/link do projeto a anexar

*content é obrigatório, salvo se content_item_id for informado.

sutram_get_chat_unread_count

Retorna quantas mensagens de outros membros o usuário atual ainda não viu (desde a última visita, ou todas se nunca visitou). Somente leitura.

Parâmetros: Nenhum

sutram_mark_chat_visited

Marca o chat do projeto como lido para o usuário atual, zerando o contador de não lidas. Não publica nada — apenas registra a visita.

Parâmetros: Nenhum

Exemplo: Fluxo de Chat

// 1. Checar quantas mensagens novas há
→ sutram_get_chat_unread_count

// 2. Ler as mensagens recentes
→ sutram_list_chat_messages { "limit": 20 }

// 3. Publicar uma atualização (externa — confirme antes)
→ sutram_send_chat_message { "content": "Guia MCP atualizado: Wiki, Governança e Chat." }

// 4. Marcar o chat como lido
→ sutram_mark_chat_visited

Limitações

As seguintes operações ainda não estão disponíveis via MCP e devem ser realizadas pela interface web do Sutram. Elas serão adicionadas em versões futuras:

Compartilhamento: Links de compartilhamento não podem ser gerados
Comentários posicionados: Criar comentários ancorados a páginas de PDF, coordenadas CAD ou posições em imagens requer a interface web

Permissões

Seu acesso MCP respeita as mesmas permissões da interface web:

Função	Navegar	Upload/Criar	Mover	Excluir	Versionamento	Schema de Registros	Registros	Comentários
Proprietário	Sim	Sim	Sim	Sim	Completo (publicar, liberar forçadamente)	Completo (CRUD de definições e categorias)	CRUD	Completo (listar, criar, responder, resolver, excluir qualquer)
Admin	Sim	Sim	Sim	Sim	Completo (publicar, criar nova versão, liberar forçadamente)	Completo (CRUD de definições e categorias)	CRUD	Completo (listar, criar, responder, resolver, excluir qualquer)
Membro	Sim	Sim	Sim	Sim	Habilitar/desabilitar, checkout/checkin, publicar, criar nova versão	Somente leitura	CRUD	Listar, criar, responder, resolver, excluir próprios
Visualizador	Sim	Não	Não	Não	Somente leitura (listar/baixar)	Somente leitura	Somente leitura	Sim (participação)

Visualizadores conectam com uma superfície somente-leitura: podem navegar, buscar e baixar conteúdo e participar de comentários e chat; as ferramentas de escrita de conteúdo (upload, criar, mover, excluir, versionar, editar records/wiki/governança) ficam ocultas e são negadas.

Famílias adicionais:

Wiki — Leitura (get_wiki_node, search_wiki, get_backlinks, get_outgoing_mentions, resolve_slug) disponível a qualquer participante, inclusive visualizadores; escrita (create_wiki_node, update_wiki_node, delete_wiki_node, sync_wiki_source, set_wiki_relation_labels) segue as funções de edição.
Chat — Leitura e publicação disponíveis a todos os participantes do projeto, inclusive visualizadores (chat é uma ferramenta de participação). Publicar e responder são ações externas (notificam a equipe).
Governança (Classes de Documentos) — Recurso do plano Max. Graduar/reverter classes, editar o ciclo de vida e administrar concessões de papel (list_class_grants, grant_class_role, revoke_class_role) são operações de proprietário e administrador; ler documentos e disparar transições obedecem à matriz papel × estado definida em cada Classe (visibilidade need-to-know), estreitada ainda pelo escopo por metadado da concessão quando definido.

Tipos de Arquivo Suportados

O Sutram detecta automaticamente tipos MIME a partir de extensões de arquivo. Formatos comuns suportados:

Categoria	Extensões
Imagens	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`
Documentos	`.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`
Texto	`.txt`, `.csv`, `.json`, `.xml`, `.md`
Mídia	`.mp4`, `.mp3`, `.wav`
Arquivos compactados	`.zip`
CAD	`.dwg`, `.dxf`, `.rvt`, `.ifc`

Arquivos com extensões não reconhecidas são enviados como application/octet-stream.

Plataformas de Links Suportadas

Plataformas de vídeo

YouTube, Vimeo, DailyMotion, Wistia, Loom e TikTok. A plataforma é detectada automaticamente a partir da URL, e miniaturas são extraídas quando disponíveis.

Plataformas de áudio

Spotify, SoundCloud, Apple Podcasts, Anchor e outros. A plataforma é detectada automaticamente a partir da URL.

Links web

Qualquer URL HTTP/HTTPS válida. Título da página, descrição e favicon são obtidos automaticamente.

Exemplos

Migrar exames médicos de portais hospitalares

"Baixe meu exame de ultrassom do portal do hospital e organize no Sutram na pasta do médico solicitante."

O assistente de IA irá:

Acessar o portal do hospital (via navegador)
Baixar o relatório em PDF e os arquivos de imagem
Usar sutram_create_folder para construir a estrutura de pastas em uma chamada: Nome do Médico / Tipo de Exame / AAAA-MM-DD
Usar sutram_request_upload + sutram_confirm_upload para fazer upload de cada arquivo diretamente ao S3
Limpar os arquivos temporários locais

Esse fluxo de trabalho garante que os dados médicos estejam devidamente organizados e nenhum arquivo sensível permaneça no computador local.

Fazer upload de um arquivo local

"Faça upload do arquivo report.pdf da minha área de trabalho para a pasta 'Reports' no Sutram."

Claude irá ler o arquivo, usar sutram_get_folder para encontrar a pasta "Reports", depois sutram_request_upload para obter uma URL pré-assinada, fazer upload do arquivo diretamente ao S3 via HTTP PUT e chamar sutram_confirm_upload para finalizar.

Organizar conteúdo do projeto

"Crie uma estrutura de pastas para nosso projeto de construção: Plans, Reports e Photos. Depois faça upload dessas fotos do canteiro."

Claude usará sutram_create_folder para cada pasta de nível superior, depois sutram_request_upload + sutram_confirm_upload para fazer upload de cada foto na pasta correta.

Limpar arquivos antigos

"Exclua todos os arquivos na pasta 'Temp'."

Claude usará sutram_get_folder para listar o conteúdo da pasta, depois sutram_delete para cada arquivo.

Reorganizar estrutura de pastas

"Mova todo o conteúdo da pasta '2024' para '2024-Archive' para liberar espaço na visualização principal."

Claude usará sutram_move_contents para transferir todas as subpastas e arquivos da origem para a pasta de destino em uma única operação. Se algum item tiver nome conflitante, será renomeado automaticamente com sufixos numéricos.

Mover um arquivo específico

"Mova o arquivo 'contract.pdf' para a pasta 'Legal'."

Claude usará sutram_get_folder para encontrar o arquivo e a pasta de destino, depois sutram_move_item para mover o arquivo. Se um arquivo com o mesmo nome já existir na pasta de destino, será renomeado automaticamente (ex.: contract (1).pdf).

Salvar um link web

"Salve este artigo no meu projeto: https://example.com/building-codes-2026"

Claude usará sutram_create_web_link com a URL. O Sutram busca automaticamente o título da página e o favicon, então o link aparece com seu nome correto no projeto.

Organizar referências de vídeo

"Adicione esses vídeos do YouTube à pasta 'Training': [URL do vídeo1], [URL do vídeo2]."

Claude usará sutram_get_folder para encontrar a pasta "Training", depois chamará sutram_create_video_link para cada URL. O Sutram detecta que são vídeos do YouTube e extrai miniaturas automaticamente.

Baixar um arquivo

"Me dê o link de download do arquivo 'site-plan.pdf'."

Claude usará sutram_get_folder para encontrar o arquivo, depois sutram_get_item para obter uma URL de download pré-assinada. A URL é temporária e pode ser usada para baixar o arquivo diretamente.

Etiquetar e buscar pastas

"Organize meus exames médicos por paciente e tipo de exame, depois encontre todas as pastas do paciente João."

Claude irá:

Usar sutram_create_folder com path e tags para criar pastas estruturadas com metadados
Usar sutram_set_folder_tags para adicionar ou atualizar tags em pastas existentes
Usar sutram_search_folders com tag_name: "patient" e tag_value: "João" para encontrar todas as pastas correspondentes (correspondência por substring — também encontra "João Pedro", "João Silva")

Tags permitem que assistentes de IA criem estruturas organizacionais ricas e pesquisáveis sem depender apenas de nomes de pastas.

Descobrir tags e realizar buscas AND

"Encontre todos os exames de USG do paciente João dentro da pasta do Dr. Mion."

Claude irá:

Usar sutram_get_tag_keys com o ID da pasta para descobrir as chaves de tag disponíveis naquele escopo

Usar sutram_search_folders com múltiplas condições AND:

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

Retornar apenas pastas que correspondam a ambas as condições dentro da hierarquia especificada

Fazendo Upload de Arquivos via Script

Ao fazer upload de arquivos por meio de um assistente de IA, o assistente usa o fluxo de URL pré-assinada em duas etapas: sutram_request_upload para obter uma URL S3 PUT pré-assinada, depois faz upload do arquivo diretamente ao S3 e finalmente chama sutram_confirm_upload para criar o registro do arquivo. Essa abordagem evita a sobrecarga de codificação base64 e não tem limite prático de tamanho de arquivo além da cota de armazenamento do seu plano.

Para automação ou uploads em lote fora do contexto do assistente de IA, você pode chamar o endpoint MCP diretamente via HTTP.

Nota: o exemplo abaixo usa o endpoint legado /mcp com os headers x-project-key/x-user-key — mantido para scripts diretos. Para conectar um cliente MCP (Claude, Cursor, etc.), use o método recomendado descrito em Conectando o Sutram ao Claude (conector OAuth ou ponte /mcp/v2).

Como o endpoint HTTP MCP funciona

O servidor MCP do Sutram usa o transporte Streamable HTTP (JSON-RPC 2.0 sobre HTTPS):

Inicializar uma sessão — POST https://app.sutram.io/mcp com método initialize
Capturar o ID da sessão — do header de resposta mcp-session-id
Enviar uma notificação — notifications/initialized (exigido pelo protocolo MCP)
Chamar ferramentas — POST com método tools/call, passando o nome da ferramenta e os argumentos

Todas as requisições devem incluir os headers de autenticação (x-project-key e x-user-key) e, após a inicialização, o header mcp-session-id.

Exemplo: Script de upload em 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();

Salve como upload.mjs e execute:

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

Integração com skill do Claude Code

Se você usa Claude Code, pode encapsular este script como uma skill para que o assistente possa invocá-lo automaticamente quando precisar fazer upload de arquivos. Coloque o script em .claude/skills/sutram-upload/scripts/upload.mjs e crie um SKILL.md que instrua Claude sobre como chamá-lo. Assim, quando o assistente encontrar um arquivo para upload, ele delega o I/O pesado ao script externo enquanto mantém a orquestração na conversa.

Pontos principais

Sem limite de tamanho de arquivo além da cota de armazenamento do seu plano Sutram
Arquivos são enviados diretamente ao S3 via URL pré-assinada — sem codificação base64, sem dados passando pelo servidor web
O script lida com o handshake MCP completo (initialize -> notify -> tool call)
A resposta pode vir como JSON ou Server-Sent Events (SSE) dependendo do tempo de processamento — o script trata ambos
Credenciais podem ser lidas do .mcp.json para evitar hardcoding

REST API

Além das ferramentas MCP, o Sutram fornece uma REST API para consumo somente leitura do conteúdo do projeto. Ela usa a mesma autenticação de chave dupla e é ideal para aplicativos externos, dashboards e scripts.

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

Endpoints:

Endpoint	Descrição
`GET /api/v1/project`	Informações do projeto
`GET /api/v1/folders`	Lista pastas raiz
`GET /api/v1/folders/:id`	Detalhes da pasta com subpastas e itens
`GET /api/v1/content`	Lista itens de conteúdo com filtragem, busca por tag e paginação
`GET /api/v1/content/:id`	Detalhes do item de conteúdo com URLs de download pré-assinadas

Documentação completa: Referência da REST API v1