@patricklouback/mcp-inventta-tools

MCP server (stdio) que dá acesso às ferramentas do Inventta Tools — Wiki, arquivos do OneDrive/SharePoint, Planner, e-mail e agentes autônomos — dentro de clientes MCP como Claude Code, Cursor, Codex, Continue, etc.

As tools, o client e o createMcpServer ficam em @inventta/mcp-core; este pacote é um wrapper fino de stdio e o build (esbuild) inlina essa lib no dist/index.js. As mesmas tools também são expostas como conector remoto OAuth para o Claude.ai web (ver abaixo).

Setup automático (recomendado)

Gere um token pessoal (PAT) em https://inventta-tools.avantti.app/settings/tokens e rode:

npx -y @patricklouback/mcp-inventta-tools setup

O instalador detecta Claude Code, Cursor e Codex instalados na máquina, pede o token (cole quando solicitado) e, em todos de uma vez:

• registra o MCP inventta-tools no arquivo de config de cada agente, preservando os demais servidores e fazendo backup (.inventta.bak);
• remove instalações antigas (inventta-tools, inventta-acervo, inventta-wiki) e as skills legadas (wiki-buscar, wiki-salvar, onedrive-buscar);
• instala as skills globais inventta-remote-files, inventta-wiki, inventta-planner, inventta-email e inventta-agents no formato de cada agente.

| Agente | Config MCP | Skills | | ----------- | ---------------------- | ----------------------- | | Claude Code | ~/.claude.json | ~/.claude/commands/*.md | | Cursor | ~/.cursor/mcp.json | ~/.cursor/rules/*.mdc | | Codex | ~/.codex/config.toml | ~/.codex/prompts/*.md |

Flags/envs opcionais: --token=inv_pat_... (ou INVENTTA_API_TOKEN) e --api-url=... (ou INVENTTA_API_URL, default https://api-inventta-tools.avantti.app). É idempotente — pode rodar de novo a qualquer momento. Reinicie o agente no fim.

Como usar (stdio — config manual)

1. Gere um token pessoal (PAT) em https://inventta-tools.avantti.app/settings/tokens.
2. Adicione a config ao seu cliente MCP (a própria tela /settings/tokens já gera esse JSON):

{
  "mcpServers": {
    "inventta-tools": {
      "command": "npx",
      "args": ["-y", "@patricklouback/mcp-inventta-tools"],
      "env": {
        "INVENTTA_API_URL": "https://api-inventta-tools.avantti.app",
        "INVENTTA_API_TOKEN": "inv_pat_..."
      }
    }
  }
}

3. Reinicie o cliente. As tools wiki_*, remote_*, planner_*, my_email_read e agent_* aparecem na sua sessão.

Conector web (Claude.ai / ChatGPT) — OAuth

No Claude.ai ou ChatGPT (modo desenvolvedor) não se usa este pacote nem PAT: as tools são servidas pela API (@inventta/mcp-connector), autenticadas por OAuth 2.1.

Use preferencialmente um conector por ferramenta (mesma conta Microsoft). Isso reduz o número de tools por conexão e melhora as descrições disponíveis para modelos web:

| URL | Perfil | | -------------------------------------------------------------- | ------------------------------------------ | | https://api-inventta-tools.avantti.app/mcp/wiki | Wiki: leitura + escrita (wiki_*) | | https://api-inventta-tools.avantti.app/mcp/remote-files | OneDrive/SharePoint (remote_*) | | https://api-inventta-tools.avantti.app/mcp/autonomous-agents | Agentes autônomos (agent_*) | | https://api-inventta-tools.avantti.app/mcp/planner | Planner por plannerUrl ou planId | | https://api-inventta-tools.avantti.app/mcp/my-email | Leitura da própria caixa (my_email_read) | | https://api-inventta-tools.avantti.app/mcp | legado: leitura consolidada | | https://api-inventta-tools.avantti.app/mcp/actions | legado: ações consolidadas |

1. Configurações → Conectores → Adicionar conector personalizado.
2. Deixe Client ID/Secret vazios (DCR) e autorize com sua conta Microsoft.

A tela /settings/tokens mostra as URLs prontas.

Tools disponíveis

| Tool | O que faz | | ---------------------------- | ------------------------------------------------------- | | wiki_get_tree | Lista toda a árvore (pastas + docs, sem conteúdo) | | wiki_search_docs | Busca por termo em título e conteúdo | | wiki_get_doc | Lê o markdown completo de um doc | | wiki_list_folders | Lista pastas filhas de uma pasta (ou raiz) | | wiki_list_docs | Lista docs de uma pasta (ou raiz) | | wiki_create_doc | Cria um doc novo | | wiki_update_doc | Edita título / conteúdo / pasta de um doc | | wiki_delete_doc | Exclui um doc | | wiki_create_folder | Cria pasta | | wiki_update_folder | Renomeia / move pasta | | wiki_delete_folder | Exclui pasta (e tudo dentro) | | remote_get_drives | Lista drives do OneDrive/SharePoint sincronizados | | remote_search | Busca arquivos/pastas por nome | | remote_list_folder | Lista o conteúdo direto de uma pasta | | remote_breadcrumb | Caminho hierárquico de um item | | remote_get_content | Extrai o texto de um arquivo (pdf, docx, xlsx…) | | remote_index_drive | Indexa e resume um drive inteiro | | remote_create_folder | Cria pasta no OneDrive/SharePoint | | remote_upload_file | Salva arquivo como cópia (binário local via contentBase64) | | remote_move_item | Move/renomeia arquivo ou pasta | | planner_update_task | Edita tarefa do Planner (prazo, status, prioridade…) | | my_email_send | Envia e-mail pela própria caixa | | planner_list_tasks | Lista tarefas de um board por plannerUrl ou planId | | planner_get_task | Detalha uma tarefa do Planner por taskId | | planner_list_buckets | Lista colunas/buckets de um board | | my_email_read | Lê mensagens, threads e anexos da própria caixa | | agent_list | Lista agentes visíveis (seus, públicos, compartilhados) | | agent_get | Lê a configuração completa de um agente | | agent_create | Cria um agente (você vira o dono) | | agent_update | Edita um agente (se você puder editar) | | agent_delete | Exclui um agente (só dono/admin) | | agent_get_access | Mostra visibilidade, bloqueio e compartilhamentos | | agent_set_access | Define visibilidade / bloqueio (só dono/admin) | | agent_list_shares | Lista compartilhamentos de um agente | | agent_add_share | Compartilha com um usuário (reader/editor) | | agent_remove_share | Remove um compartilhamento | | agent_run | Dispara uma execução manual | | agent_list_runs | Lista execuções recentes | | agent_get_run | Detalhes de uma execução | | agent_retry_run | Reexecuta uma execução | | agent_delete_run | Exclui uma execução do histórico | | agent_clear_runs | Limpa o histórico de execuções | | agent_duplicate | Duplica um agente como novo agente seu | | agent_rotate_webhook_token | Gera novo token de webhook |

Variáveis de ambiente

| Var | Default | Descrição | | -------------------- | ----------------------- | ----------------------------------------- | | INVENTTA_API_URL | http://localhost:3333 | URL base da API do Inventta Tools | | INVENTTA_API_TOKEN | — | PAT (formato inv_pat_...). Obrigatório. |

E-mail (my_email_read)

my_email_read é compartilhada entre o Chat interno, /mcp/my-email e os agentes. A implementação passa pela rota /autonomous-agents/mcp/my-email/messages e pelo provider readUserMailbox de @inventta/remote-files.

Parâmetros principais:

| Parâmetro | Uso | | -------------------- | -------------------------------------------------------------------------- | | messageId | Lê um e-mail específico retornado como [email:id] | | query | Texto simples; não depende de sintaxe Graph | | from | Filtra por remetente, domínio ou nome | | subject | Filtra por trecho do assunto | | receivedDate | Filtra por data YYYY-MM-DD | | conversationMode | Retorna a thread/conversa recente por conversationId | | includeBody | Inclui corpo completo em texto | | includeAttachments | Lista/processa anexos; documentos extraem texto e imagens passam por visão |

O provider não repassa query livre para $search do Microsoft Graph. Ele busca uma janela recente ordenada por data e aplica filtros locais tolerantes para evitar erro com @, aspas, from: e texto natural como "leia toda a conversa da EDP".

Permissões

O token herda exatamente as permissões do usuário que o gerou. Tokens podem ser revogados a qualquer momento em /settings/tokens.