Docmost (self-hosted)

Servidor MCP para Docmost auto-hospedado — leia e escreva espaços, páginas e comentários a partir do Claude, Cursor ou VS Code; funciona na Edição Comunitária gratuita.

GitHub
13

Documentação

@wisflux/docmost-local-mcp

npm version npm downloads license

Servidor MCP para Docmost construído para instâncias self-hosted, especialmente implantações que não possuem licença enterprise, mas ainda desejam acesso MCP confiável a partir de IDEs locais e ferramentas de IA.

O pacote é iniciado com npx, enquanto o servidor real é um binário Rust baixado dos GitHub Releases durante a instalação. Esse binário lida com tráfego MCP via stdio, UX de autenticação local, armazenamento de sessão e acesso à API do Docmost.

A principal razão deste projeto existir: trazer acesso MCP para instalações self-hosted do Docmost sem tornar uma licença enterprise um pré-requisito.

Por Que Este Projeto

Muitas integrações MCP são projetadas em torno de premissas hospedadas ou enterprise. Este projeto é intencionalmente otimizado para Docmost self-hosted:

  • Funciona com sua própria URL base do Docmost
  • Usa autenticação por e-mail/senha do Docmost
  • Armazena o estado da sessão localmente para reutilização
  • Abre um fluxo de autenticação local em vez de exigir um plano de controle hospedado separado
  • É distribuído como um ponto de entrada simples via npx para fácil integração com IDEs

Se você executa seu próprio Docmost e deseja usá-lo dentro do Cursor, Claude Desktop ou outro cliente MCP, este pacote é o caminho direto.

Destaques

  • Ótima adequação para instâncias Docmost self-hosted sem licenciamento enterprise
  • Núcleo do servidor em Rust com um pequeno inicializador Node para instalações locais previsíveis
  • Janela de autenticação nativa em plataformas suportadas, com fallback para navegador
  • Seleção explícita da instância Docmost via configuração de inicialização
  • Reutilização de sessão com verificação de expiração do JWT e re-login automático
  • Armazenamento de credenciais no chaveiro do sistema operacional em plataformas suportadas
  • Superfície de ferramentas limpa para espaços, páginas, comentários, membros e contexto do usuário atual

Ferramentas Disponíveis

  • list_spaces: lista os espaços Docmost disponíveis
  • get_space: busca detalhes de um espaço específico
  • search_docs: pesquisa documentação, opcionalmente restrita a um espaço
  • search_pages: alias compatível com versões anteriores para search_docs
  • get_page: busca uma página e retorna seu conteúdo como Markdown
  • list_pages: lista páginas recentes em um espaço
  • list_child_pages: lista páginas filhas de um ID de página pai
  • get_comments: lista comentários de uma página
  • list_workspace_members: lista membros do workspace
  • get_current_user: busca o usuário autenticado e o contexto do workspace
  • create_page: cria uma nova página em um espaço a partir de conteúdo Markdown
  • update_page: atualiza o título e/ou o conteúdo Markdown de uma página existente
  • duplicate_page: duplica uma página (e suas subpáginas) dentro do seu espaço
  • copy_page_to_space: copia uma página (e suas subpáginas) para um espaço diferente
  • move_page: move uma página para um novo pai, ou para a raiz do espaço
  • move_page_to_space: move uma página (e suas subpáginas) para um espaço diferente
  • create_space: cria um novo espaço com nome e slug de URL
  • update_space: atualiza o nome, slug e/ou descrição de um espaço
  • create_comment: adiciona um comentário em nível de página a partir de Markdown
  • update_comment: substitui o corpo de um comentário existente por novo Markdown

Roadmap

Todas as ferramentas de leitura e escrita planejadas já estão implementadas. create_comment adiciona comentários em nível de página; comentários ancorados a uma seleção específica de texto (comentários inline) exigem as posições do cursor do editor colaborativo e estão fora do escopo deste servidor baseado em REST.

Compatibilidade

Tem como alvo o Docmost aproximadamente do último ano de lançamentos (v0.22+); servidores mais antigos funcionam na melhor das hipóteses. O servidor detecta a versão do Docmost (via POST /api/version) uma vez por sessão e se adapta onde o comportamento difere:

  • Edições de corpo de página: update_page só pode alterar o corpo de uma página existente no Docmost v0.70.0+. Em servidores mais antigos, o corpo vive no editor colaborativo e uma atualização de corpo via REST é ignorada — update_page diz isso explicitamente e sugere create_page (que persiste corpos em todas as versões via endpoint de importação). Atualizações de título funcionam em todos os lugares.

Suporte a Conteúdo

Corpos de páginas e comentários são escritos em Markdown (cabeçalhos, negrito/itálico/tachado, código inline, links, listas, listas de tarefas, citações, blocos de código; páginas também suportam tabelas e imagens com URL externa). Comentários suportam um conjunto menor — sem tabelas, listas de tarefas ou imagens.

Menções (@marcação): em qualquer corpo Markdown, um link com URL user: ou page: vira uma menção — [Display Name](user:USER_UUID) marca um usuário (encontre o UUID com list_workspace_members) e [Page Title](page:PAGE_UUID) vincula uma página. Usuários marcados são notificados pelo Docmost.

Anexar arquivos/imagens enviados (em vez de referenciar uma URL de imagem) não é suportado.

Requisitos

  • Node.js 18 ou mais recente para npx
  • Uma instância Docmost acessível
  • Autenticação por e-mail/senha habilitada nessa instância Docmost

Início Rápido

Execute o servidor diretamente com npx:

npx -y @wisflux/docmost-local-mcp --base-url=https://docs.example.com

Você também pode fornecer a URL base com uma variável de ambiente:

DOCMOST_BASE_URL=https://docs.example.com npx -y @wisflux/docmost-local-mcp

Configuração do Cliente MCP

A maioria dos clientes MCP inicia o servidor diretamente com npx. Adicione isso à configuração MCP do seu cliente, substituindo a URL base pela sua própria instância Docmost:

{
  "mcpServers": {
    "docmost": {
      "command": "npx",
      "args": ["-y", "@wisflux/docmost-local-mcp", "--base-url=https://docs.example.com"]
    }
  }
}

Onde essa configuração fica, por cliente:

  • Claude Desktop — claude_desktop_config.json (Configurações → Desenvolvedor → Editar Configuração)

  • Cursor — ~/.cursor/mcp.json (global) ou .cursor/mcp.json (por projeto)

  • Claude Code — um comando, sem edição de arquivos:

    claude mcp add docmost -- npx -y @wisflux/docmost-local-mcp --base-url=https://docs.example.com

  • VS Code (GitHub Copilot) — .vscode/mcp.json, usando uma chave de nível superior servers em vez de mcpServers:

    {
  "servers": {
    "docmost": {
      "command": "npx",
      "args": ["-y", "@wisflux/docmost-local-mcp", "--base-url=https://docs.example.com"]
    }
  }
}

Essa configuração funciona bem quando você deseja uma instância Docmost fixa por configuração de cliente. Se --base-url ou DOCMOST_BASE_URL estiver definido, a página de login mostra essa URL pré-preenchida e bloqueia o campo. Se nenhuma URL base estiver configurada, o fluxo de login a solicita durante o login interativo.

Exemplos de Prompts

Depois de conectado, pergunte ao seu cliente de IA coisas como:

  • "Pesquise no espaço Engineering do Docmost nosso runbook de plantão e resuma."
  • "Crie uma nova página no espaço Product intitulada 'Planejamento Q3' a partir destas notas: …"
  • "Transforme esta transcrição de reunião em uma página Docmost estruturada sob o espaço Team."
  • "Encontre todas as páginas no Docmost que mencionam o endpoint antigo da API e liste-as."
  • "Leia a página 'Onboarding' e rascunhe uma checklist mais curta como uma nova subpágina."
  • "Adicione um comentário na página de notas de versão sinalizando a etapa de migração ausente."

Fluxo de Autenticação

  1. Seu cliente MCP inicia o servidor via stdio.
  2. Na primeira chamada de ferramenta autenticada, o servidor inicia uma página de login HTTP local em 127.0.0.1.
  3. O servidor abre uma janela de autenticação nativa quando disponível, ou recorre ao navegador do sistema.
  4. Você insere seu e-mail e senha lá. Se --base-url ou DOCMOST_BASE_URL estiver definido, a URL do Docmost é pré-preenchida e bloqueada.
  5. O servidor faz login via /api/auth/login, extrai o cookie authToken, armazena a sessão e, opcionalmente, armazena as credenciais para re-login automático.
  6. Solicitações futuras reutilizam o token salvo até que esteja próximo da expiração ou seja rejeitado pelo Docmost.

Estado Local e Armazenamento de Credenciais

O servidor armazena o estado local em:

~/.docmost-local-mcp/

Arquivos usados lá:

  • config.json: última URL base e e-mail
  • session.json: token de autenticação salvo e expiração

As credenciais são armazenadas no chaveiro do sistema operacional quando disponível, que é o caminho preferido em plataformas suportadas.

Se o armazenamento seguro de credenciais do SO não estiver disponível, o servidor recorre ao armazenamento local de credenciais criptografado para ainda suportar a reutilização de login sem escrever credenciais em texto puro. Esse fallback é intencionalmente secundário ao armazenamento via chaveiro.

Notas de Plataforma

A janela de autenticação nativa usa o webview do sistema em cada plataforma:

  • macOS: WKWebView
  • Windows: WebView2
  • Linux: WebKitGTK

Avisos importantes:

  • Windows precisa do runtime WebView2 disponível
  • Ambientes de desktop Linux precisam dos pacotes WebKitGTK instalados
  • Quando o binário é compilado sem o recurso native-webview, o fallback para navegador é sempre usado

Referência de Ferramentas

list_spaces

Retorna nomes, slugs e IDs dos espaços Docmost.

search_docs

Entradas:

  • query: texto de pesquisa obrigatório
  • space_id: ID de espaço Docmost opcional

search_pages

Entradas:

  • query: texto de pesquisa obrigatório
  • space_id: ID de espaço Docmost opcional

Este é um alias compatível com versões anteriores para pesquisa de páginas. search_docs permanece disponível.

get_space

Entradas:

  • space_id: ID de espaço Docmost obrigatório

get_page

Entradas:

  • slug_id: o ID de slug da página retornado por search_docs

list_pages

Entradas:

  • space_id: ID de espaço Docmost obrigatório
  • limit: limite opcional de contagem de páginas
  • cursor: cursor de paginação opcional

list_child_pages

Entradas:

  • page_id: ID de página pai obrigatório
  • limit: limite opcional de contagem de páginas
  • cursor: cursor de paginação opcional

get_comments

Entradas:

  • page_id: ID de página obrigatório
  • limit: limite opcional de contagem de comentários
  • cursor: cursor de paginação opcional

list_workspace_members

Entradas:

  • limit: limite opcional de contagem de membros
  • cursor: cursor de paginação opcional
  • query: texto de pesquisa de membros opcional
  • admin_view: sinalizador opcional de visibilidade de administrador

get_current_user

Entradas:

  • nenhuma

create_page

Entradas:

  • space_id: ID de espaço Docmost obrigatório (UUID) para criar a página
  • title: título da página obrigatório
  • markdown: corpo da página opcional como Markdown
  • parent_page_id: ID de página pai opcional para aninhar (apenas páginas somente com título)

Quando markdown é fornecido, o corpo da página é enviado pelo endpoint de importação do Docmost (POST /api/pages/import), que é o único mecanismo que persiste de forma confiável o conteúdo do corpo da página em todas as versões do Docmost (incluindo servidores self-hosted mais antigos). Páginas criadas com corpo ficam na raiz do espaço — parent_page_id é respeitado apenas para páginas somente com título.

update_page

Entradas:

  • page_id: ID de página Docmost ou ID de slug obrigatório
  • title: novo título opcional (omitir para não alterar)
  • markdown: novo corpo opcional como Markdown; substitui o conteúdo existente (omitir para não alterar)

Atualizar o título de uma página funciona em todas as versões do Docmost. Atualizar o corpo de uma página existente via REST funciona apenas em versões mais novas do Docmost; em servidores self-hosted mais antigos (ex.: v0.25.x), o corpo é editado exclusivamente pelo editor colaborativo e uma atualização de corpo via REST não é aplicada. Para definir o conteúdo do corpo de forma confiável lá, crie uma nova página com create_page em vez disso.

Para o design completo, detalhes de conversão Markdown→ProseMirror, campos verificados da API do Docmost e ressalvas de versão, veja docs/write-tools.md.

Desenvolvimento

Para detalhes do fluxo de trabalho de mantenedores e contribuidores, veja CONTRIBUTING.md.

Licença

MIT