DokuTrak

dokutrak-mcp

O conector aberto MCP para DokuTrak: deixe seu agente ir atrás dos documentos.

O DokuTrak coleta documentos dos seus clientes em seu nome: você envia uma solicitação, o cliente faz o upload por um link seguro, os arquivos são revisados e clientes silenciosos recebem lembretes. Este conector coloca esse ciclo dentro do agente em que você já trabalha, então "onde está o arquivo da Dupont?" é respondido sem sair do Claude.

O conector é um cliente fino e sem estado da API do DokuTrak. Ele guarda a Conexão de Agente que você fornece, não armazena nada em disco, não mantém cache e não duplica nenhuma regra: o que seu agente pode ou não fazer é decidido pelo serviço, e recusas voltam como erros de ferramenta com a explicação do próprio serviço.

Instalação

Você precisa de um workspace DokuTrak e de uma Conexão de Agente, emitida em Configurações → Conectar um agente no aplicativo DokuTrak. Essa tela entrega uma configuração pronta para colar, com sua chave já no lugar; as instruções abaixo são a mesma coisa, feita manualmente.

A chave é lida da variável de ambiente DOKUTRAK_API_KEY. Ela nunca é obtida pela linha de comando.

Claude Desktop

Abra o arquivo de configuração:

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

Adicione o servidor em mcpServers (crie o objeto se o arquivo estiver vazio):

{
  "mcpServers": {
    "dokutrak": {
      "command": "npx",
      "args": ["-y", "dokutrak-mcp"],
      "env": { "DOKUTRAK_API_KEY": "dk_live_…" }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas do DokuTrak aparecem no menu de ferramentas de uma nova conversa.

Claude Code

claude mcp add dokutrak -e DOKUTRAK_API_KEY=dk_live_… -- npx -y dokutrak-mcp

Depois, /mcp dentro do Claude Code lista dokutrak e suas ferramentas.

claude.ai

Não suportado nesta versão. O claude.ai conecta-se a servidores MCP remotos via HTTP com OAuth; este conector fala stdio com uma chave de API, que é o que uma instalação local no Claude Desktop ou no Claude Code precisa. Uma variante hospedada é uma decisão separada e posterior.

A partir de um clone, antes do lançamento no npm

git clone https://github.com/Crackx17/dokutrak-mcp.git
cd dokutrak-mcp
npm ci && npm run build

Depois, aponte o cliente para o arquivo compilado em vez de npx:

{
  "mcpServers": {
    "dokutrak": {
      "command": "node",
      "args": ["/path/to/dokutrak-mcp/dist/cli.js"],
      "env": { "DOKUTRAK_API_KEY": "dk_live_…" }
    }
  }
}

ou, para Claude Code: claude mcp add dokutrak -e DOKUTRAK_API_KEY=dk_live_… -- node /path/to/dokutrak-mcp/dist/cli.js.

A habilidade

skills/dokutrak/SKILL.md ensina ao agente os três usos do dia a dia — pedir documentos a um cliente, saber onde uma solicitação está, cobrar arquivos rejeitados — e como conectar. É o que um usuário do DokuTrak instala junto com o conector:

npx skills add Crackx17/dokutrak-mcp        # the open agent-skills installer
# or by hand, for Claude Code / Claude Desktop:
cp -r skills/dokutrak ~/.claude/skills/dokutrak

Configuração

Variável	Obrigatória	Padrão	Significado
DOKUTRAK_API_KEY	sim	—	A Conexão de Agente, de Configurações → Conectar um agente.
DOKUTRAK_API_URL	não	https://app.dokutrak.com/api	URL base da API. Termina em /api; o conector adiciona /v1.

Ferramentas

Quatro ferramentas, uma ida e volta: pedir, cobrar, saber, coletar.

create_request

Cria uma Solicitação de Documentos e a envia, em uma única chamada, para que nada fique criado mas não enviado. Recebe o e-mail do cliente, um prazo (YYYY-MM-DD ou uma data ISO), a lista de verificação dos documentos desejados e um título e mensagem opcionais. O e-mail vai para o destinatário informado aqui e para mais ninguém; o cliente faz o upload pelo link seguro que ele contém. Por baixo dos panos, este é o mesmo processo em duas etapas que o aplicativo DokuTrak executa: criar com sendEmail: false e depois enviar. Se o envio falhar, o erro nomeia a solicitação criada, que permanece visível no painel.

Nada sai sem o seu sim. O e-mail para um cliente real não pode ser recuperado, então a ferramenta diz ao agente para mostrar a você o destinatário, o prazo, a lista de verificação e a mensagem, e para aguardar sua confirmação. A ferramenta também é sinalizada para que o cliente pergunte a você antes de cada chamada: o Claude Code pergunta a cada vez, mesmo nos modos automático ou de bypass, e o Claude Desktop a trata como uma ferramenta que sempre precisa de aprovação. Um cliente que ignora essas sinalizações fica apenas com a instrução ao agente.

request_replacement

Cobra o cliente pelos arquivos rejeitados de uma solicitação: sinaliza-os, move a solicitação de volta para aguardando o cliente e a retorna ao ritmo automático de lembretes. Esta chamada não envia e-mail por si só; os lembretes enviam, e o DokuTrak não tem como enviar e-mail ao cliente imediatamente, nem mesmo pelo painel. A mensagem opcional é registrada na trilha de auditoria da solicitação e não é enviada ao cliente. Ela recusa uma solicitação sem arquivo rejeitado.

get_request

Onde uma Solicitação de Documentos está, em uma única chamada: status, a lista de verificação, cada arquivo coletado com seu veredito (aprovado, rejeitado com o motivo do revisor ou pendente) e o estado dos lembretes. Informe um request_id ou um termo search que corresponda ao título ou ao nome ou e-mail do cliente. Quando várias solicitações corresponderem, a ferramenta retorna os candidatos e pede o id.

download_documents

Cada arquivo coletado de uma solicitação, como um único arquivo zip. O arquivo volta embutido no resultado da ferramenta como conteúdo binário (um recurso MCP com um blob base64 e application/zip), não como um link: a API não tem endpoint de link curto para um zip, e o conector não grava nada em disco. O que o agente faz com os bytes é decidido no lado do profissional, exatamente como um download pelo navegador. Arquivos grandes geram resultados grandes; verifique com get_request se os documentos chegaram antes de chamá-la.

O que o conector não pode fazer

Aprovar ou rejeitar um documento é sua decisão, tomada no painel do DokuTrak. Nenhuma ferramenta aqui pode tomá-la, e o serviço a recusa a qualquer Conexão de Agente, independentemente de qual conector pedir. O mesmo vale para cobrança, configurações do workspace e gerenciamento de chaves de API.

Revogar a Conexão de Agente no DokuTrak tem efeito na chamada seguinte: o conector responde com o 401 do serviço e nada mais.

Desenvolvimento

npm ci
npm run check   # typecheck, build, tests
npm test        # tests alone

Os testes são testes de contrato na costura do MCP: um cliente MCP real e o servidor real, conectados em memória pelo transporte do SDK oficial, com HTTP simulado em fetch usando respostas gravadas. Eles chamam ferramentas, nunca funções, e rodam sem conta DokuTrak e sem rede.

A execução de teste

Antes de um lançamento, o binário compilado é executado uma vez contra um workspace real, por um cliente MCP real via stdio: criar → cobrar → ler → coletar → revogar → 401. É um registro colado no PR do lançamento, nunca uma verificação de CI (uma verificação bloqueante não chama terceiros). Ela pausa duas vezes para ações que o serviço recusa a qualquer Conexão de Agente: rejeitar o arquivo enviado e revogar a chave.

npm run build
DOKUTRAK_API_KEY=dk_live_… STAGING_RECIPIENT_EMAIL=you@example.com npm run staging

Uma Solicitação de Documentos real é criada e um e-mail real vai para STAGING_RECIPIENT_EMAIL. A transcrição vai para staging-run-<timestamp>.md (ignorada pelo git); a chave nunca é gravada nela.

Lançamento

Uma tag vX.Y.Z correspondente a package.json e SERVER_VERSION aciona .github/workflows/release.yml: npm run check, npm publish (publicação confiável pelo token OIDC do GitHub, proveniência anexada) e depois a listagem no Registro MCP como io.github.Crackx17/dokutrak-mcp — o mcpName de package.json, que o registro verifica contra o tarball publicado. Executar o fluxo de trabalho manualmente faz um --dry-run e não publica nada.

Licença

MIT.